agent-docs-api-openapi

Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi

Quality

15%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-docs-api-openapi/SKILL.md

Quality

Content

22%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill body is dominated by a large legacy agent-config YAML block that adds little actionable value, and it lacks a sequenced, validated workflow for producing OpenAPI specs. Useful guidance exists (a spec template and concrete best practices) but is buried amid verbose, partially redundant content.

Suggestions

Remove or externalize the legacy agent-definition YAML block (~115 lines) and its explanatory comment — it is agent metadata, not guidance for documenting an API.

Add a sequenced workflow with an explicit validation checkpoint, e.g. analyze routes -> draft paths/schemas -> validate (`swagger-cli validate openapi.yaml`) -> fix and re-validate -> finalize.

Trim the basic OpenAPI structure skeleton (Claude already knows the spec shape) and keep only non-obvious guidance such as reusable component patterns and security-scheme conventions.

Dimension	Reasoning	Score
Conciseness	The body is padded with a ~115-line legacy agent-definition YAML block (triggers, capabilities, hooks with shell scripts, integration config) retained 'for any tool still parsing it', plus an explanatory HTML comment, none of which helps Claude document an API. The OpenAPI structure skeleton also re-teaches spec basics Claude already knows.	1 / 3
Actionability	A concrete copy-pasteable OpenAPI spec template and specific best-practice pointers ('Use $ref for reusable components', 'Group endpoints logically with tags') provide some guidance, but the rest is a descriptive checklist with no executable commands, generation process, or validation step. It is incomplete rather than fully abstract, so it sits above score 1.	2 / 3
Workflow Clarity	There is no real sequenced workflow — 'Key responsibilities' is a deliverables list, not a process — and no validation/verification checkpoint anywhere, even though spec authoring is a multi-step task that benefits from a validate-fix-retry loop. The missing validation and absence of a genuine sequence match the score-1 anchor.	1 / 3
Progressive Disclosure	The body has organized sections (responsibilities, best practices, structure, elements), but it is monolithic with no references to other files, and the legacy YAML block is content that should be separate yet is inlined. This fits 'some structure but content that should be separate is inline' rather than a clean overview with one-level-deep references.	2 / 3
	Total	6 / 12 Passed

Description

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The frontmatter description is essentially a machine slug plus invocation syntax: it states no concrete actions and provides no 'Use when' trigger guidance. It is too vague to reliably tell Claude what the skill does or when to invoke it.

Suggestions

Rewrite the description to state concrete actions, e.g. 'Create and maintain OpenAPI 3.0/Swagger specifications: document endpoints, define request/response schemas, and add security schemes.'

Add an explicit 'Use when...' trigger clause with natural terms users say, e.g. 'Use when creating or updating OpenAPI/Swagger specs, documenting REST endpoints, or working with openapi.yaml/swagger.yaml files.'

Drop the invocation syntax ('$agent-docs-api-openapi') from the description — it is not a natural trigger term and wastes the limited description budget.

Dimension	Reasoning	Score
Specificity	The description only names a domain ('docs-api-openapi') and names no concrete actions at all — it does not say it creates specs, documents endpoints, or defines schemas. This matches the score-1 anchor 'vague or no actions' like 'Helps with documents'.	1 / 3
Completeness	The 'what' is near-empty (just 'agent skill for docs-api-openapi' with no actions) and the 'when' is entirely absent — there is no 'Use when...' clause or equivalent trigger guidance, which the rubric caps at 2 even when present. Both halves are weak, so this is score 1.	1 / 3
Trigger Term Quality	The text is a machine identifier and invocation syntax ('$agent-docs-api-openapi'), not natural language a user would say when they need this skill. Although 'openapi' is a recognizable term, it is buried in a hyphenated slug, matching the score-1 'technical jargon' anchor.	1 / 3
Distinctiveness Conflict Risk	The named niche (OpenAPI/API documentation) is specific enough not to be generic like 'code and documents', so it is above score 1, but with no trigger terms it could still overlap with other API-documentation skills. This fits 'somewhat specific but could still overlap'.	2 / 3
	Total	5 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/ruflo
Path: .agents/skills/agent-docs-api-openapi/SKILL.md
Commit: 26c35b5

Reviewed: about 6 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.