agent-docs-api-openapi

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

1.06x

Quality

—

Does it follow best practices?

Impact

99%

1.06x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

37%

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

The body mixes a large, non-instructional agent-config YAML dump with a concise but generic OpenAPI guide that lacks a sequenced workflow and validation step, and contains corrupted placeholder tokens.

Suggestions

Remove the ~115-line agent-config YAML block from SKILL.md; it is metadata, not skill instructions, and wastes tokens.

Add a numbered workflow with a validation checkpoint, e.g. '1. Inventory endpoints 2. Draft the spec 3. Validate with a linter 4. Fix and re-validate'.

Fix the corrupted tokens in the YAML template ('$endpoint' -> '/endpoint', 'application$json' -> 'application/json', 'request$response' -> 'request/response').

Dimension	Reasoning	Score
Conciseness	The instructional markdown is reasonably lean, but the body is padded with ~115 lines of agent-config YAML metadata and OpenAPI boilerplate Claude already knows, so it is mostly efficient with unnecessary context.	2 / 3
Actionability	An OpenAPI YAML structure template and concrete best-practice lists give some guidance, but the template is incomplete and corrupted with placeholder tokens like '$endpoint', 'request$response', and 'application$json'.	2 / 3
Workflow Clarity	There is no sequenced multi-step workflow and no validation/verification checkpoint (e.g. linting the spec), which the guidelines require for documentation-generating tasks.	1 / 3
Progressive Disclosure	The instructional content is organized into labeled sections with no external references needed, but the body is bloated by an inline monolithic YAML config block that should not live in SKILL.md.	2 / 3
	Total	7 / 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 description is a generic invocation label rather than a capability statement: it names a domain but no actions, lacks natural trigger terms, and omits any usage guidance.

Suggestions

Replace the description with concrete actions, e.g. 'Create and maintain OpenAPI 3.0 specifications, document endpoints, and define request/response schemas.'

Add an explicit trigger clause: 'Use when the user asks to create or update OpenAPI/Swagger documentation, or mentions api docs, endpoints, or .yaml spec files.'

Use natural user-facing keywords (openapi, swagger, api documentation) instead of the internal slug 'docs-api-openapi'.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for docs-api-openapi' names a domain but lists no concrete actions; it does not say what the skill actually does, matching the vague/abstract anchor.	1 / 3
Completeness	It neither concretely states what the skill does nor provides any 'Use when...' trigger guidance, missing both 'what' and 'when'.	1 / 3
Trigger Term Quality	The only terms are the internal slug 'docs-api-openapi' and the invocation token '$agent-docs-api-openapi', neither of which a user would naturally say; natural terms like 'openapi', 'swagger', or 'api documentation' are absent.	1 / 3
Distinctiveness Conflict Risk	The 'docs-api-openapi' niche is fairly specific and unlikely to conflict with unrelated skills, but the generic 'Agent skill for...' phrasing keeps it from being clearly distinctive.	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/claude-flow
Commit: 8ae8752

Reviewed: 2 days 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.