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.
57
64%
Does it follow best practices?
Impact
—
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 specific capabilities, includes natural trigger terms developers would use, and explicitly states both what the skill does and when to use it. The description is concise yet comprehensive, covering the domain of API documentation with distinct terminology that minimizes 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. These are concrete, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates professional API documentation using OpenAPI specs with endpoints, auth, and interactive examples) and 'when' (explicit 'Use when' clause covering REST APIs, SDK references, and developer portals). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'API documentation', 'OpenAPI', 'endpoints', 'authentication', 'REST APIs', 'SDK references', 'developer portals'. These cover a good range of terms developers naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly occupies a distinct niche around API documentation and OpenAPI specifications. The specific domain terms like 'OpenAPI', 'REST APIs', 'SDK references', and 'developer portals' make it 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 valid OpenAPI spec example but fails to deliver actionable, workflow-driven guidance for creating API documentation. It reads more like a reference checklist than an instructional skill, with generic best practices Claude already knows and no clear process for going from API to published docs. The lack of executable commands, validation steps, and progressive disclosure significantly limits its utility.
Suggestions
Add a clear step-by-step workflow: e.g., 1) Write/generate OpenAPI spec, 2) Validate with `npx @redocly/cli lint spec.yaml`, 3) Generate docs with `npx @redocly/cli build-docs spec.yaml`, 4) Verify output
Remove generic best practices and checklist items that Claude already knows; replace with concrete examples of common patterns (e.g., a complete endpoint with request body, response, and error examples)
Add executable commands for at least one documentation tool (e.g., Redoc or Swagger UI) showing how to render the spec into browsable documentation
Split the lengthy OpenAPI spec into a referenced file (e.g., OPENAPI_TEMPLATE.yaml) and keep SKILL.md as a concise overview with navigation to detailed resources
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The OpenAPI spec example is reasonably useful but overly long for what it teaches. The checklist and best practices sections are generic advice Claude already knows (e.g., 'Include request/response examples', 'Document all parameters'). The tools list adds little value without guidance on when/how to use each. | 2 / 3 |
Actionability | The OpenAPI spec is a concrete, valid YAML example which is good, but the skill lacks executable steps for actually generating documentation from it. There are no commands to run (e.g., how to use Swagger UI or Redoc to render the spec), no complete endpoint examples with request/response pairs, and the checklist items are aspirational rather than instructional. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequence of steps for creating API documentation. The skill presents a spec example, a checklist, and best practices as disconnected sections with no process flow, no validation steps, and no guidance on how to go from input (an API) to output (published documentation). | 1 / 3 |
Progressive Disclosure | The content is a monolithic file with no references to supporting files. The lengthy OpenAPI spec example could be in a separate reference file, and topics like authentication examples, SDK examples, and migration guides are mentioned but never linked to any detailed content. There's no navigation structure. | 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
5e92b71
- 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.