api-reference-documentation
Creates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples. Use when documenting REST APIs, creating SDK references, or building developer portals.
72
64%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/api-reference-documentation/skills/api-reference-documentation/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly communicates what the skill does and when to use it. It uses specific, domain-appropriate terminology that users would naturally employ when seeking API documentation help. The description is concise yet comprehensive, with a clear 'Use when' clause and distinct trigger terms that minimize conflict risk with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: creating API documentation, using OpenAPI specifications, documenting endpoints, authentication, and interactive examples. Also mentions SDK references and developer portals. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples) and 'when' (explicit 'Use when' clause covering documenting REST APIs, creating SDK references, or building developer portals). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'API documentation', 'OpenAPI', 'REST APIs', 'SDK references', 'developer portals', 'endpoints', 'authentication'. These cover common variations of how users would describe this need. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly occupies a distinct niche around API documentation specifically, with domain-specific triggers like 'OpenAPI', 'REST APIs', 'SDK references', and 'developer portals' that are unlikely to conflict with general documentation or coding skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
29%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable OpenAPI template but lacks actionable workflow guidance, clear sequencing, and progressive disclosure. It reads more like a reference checklist than an instructional skill—Claude would know most of the best practices already, and the content doesn't teach how to actually produce documentation step by step. The large inline YAML spec consumes tokens without proportional instructional value.
Suggestions
Replace the static checklist and best practices with a concrete step-by-step workflow (e.g., '1. Gather endpoint info, 2. Write OpenAPI spec, 3. Validate with `swagger-cli validate spec.yaml`, 4. Generate docs with Redoc').
Add validation checkpoints—e.g., how to validate the OpenAPI spec and verify generated documentation renders correctly.
Move the full OpenAPI example to a referenced file (e.g., 'See [example-spec.yaml](example-spec.yaml)') and keep only a minimal inline snippet showing the key pattern.
Add concrete, executable commands for at least one documentation tool (e.g., `npx @redocly/cli build-docs spec.yaml --output docs.html`) instead of just listing tool names.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The OpenAPI spec example is lengthy and takes up significant space for what is essentially a standard YAML template. The checklist and best practices sections contain items Claude already knows about API documentation. However, it's not egregiously verbose—it avoids lengthy prose explanations. | 2 / 3 |
Actionability | The OpenAPI spec is a concrete, usable template, which is good. However, the checklist and best practices are vague bullet points ('Document all parameters and headers', 'Enable interactive API exploration') without concrete commands, code, or specific instructions on how to accomplish them. The tools section just lists names with no guidance on usage. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced steps for creating API documentation. The content is a static template, a checklist, and a list of best practices, but there's no process: no 'first do X, then Y, validate with Z.' For a multi-step task like creating API documentation, the lack of any sequencing or validation steps is a significant gap. | 1 / 3 |
Progressive Disclosure | The content is a monolithic file with a large inline OpenAPI spec that could be referenced externally. There are no links to deeper resources, no separation of quick-start vs. advanced content, and no navigation structure. The tools section could link to guides but doesn't. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- secondsky/claude-skills
- Commit
88da5ff
- Reviewed
Table of Contents
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.