generating-api-docs
Create comprehensive API documentation with examples, authentication guides, and SDKs. Use when creating comprehensive API documentation. Trigger with phrases like "generate API docs", "create API documentation", or "document the API".
47
51%
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-development/api-documentation-generator/skills/generating-api-docs/SKILL.mdQuality
Discovery
82%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 functional and covers the basics well, with explicit trigger phrases and a clear 'Use when' clause. Its main weaknesses are moderate specificity in the capabilities listed and some risk of overlap with general documentation skills. The trigger terms are strong and natural, which is the description's greatest strength.
Suggestions
Add more specific concrete actions beyond the high-level deliverables, e.g., 'generate endpoint reference tables, create request/response examples, produce OpenAPI/Swagger specs'.
Improve distinctiveness by clarifying what differentiates this from general documentation skills, e.g., specifying REST/GraphQL APIs, or mentioning specific output formats like OpenAPI, Postman collections.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (API documentation) and mentions some deliverables (examples, authentication guides, SDKs), but these are somewhat high-level and not deeply specific concrete actions like 'generate endpoint reference tables' or 'create request/response examples'. | 2 / 3 |
Completeness | Clearly answers both 'what' (create comprehensive API documentation with examples, authentication guides, and SDKs) and 'when' (explicit 'Use when' clause and 'Trigger with phrases' providing concrete trigger guidance). | 3 / 3 |
Trigger Term Quality | Includes natural trigger phrases users would say: 'generate API docs', 'create API documentation', 'document the API'. These are realistic phrases a user would type. Also includes terms like 'authentication guides' and 'SDKs' that help with matching. | 3 / 3 |
Distinctiveness Conflict Risk | While 'API documentation' is a reasonably specific niche, it could overlap with general documentation skills or code documentation skills. The term 'comprehensive' is vague and doesn't sharpen the boundary. However, the API-specific triggers help somewhat. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
20%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a product requirements document than an actionable skill for Claude. It describes what API documentation should contain at a high level but provides no executable code, no concrete commands, no configuration templates, and no specific implementation guidance. The verbose descriptions of concepts Claude already understands (CORS, OAuth2, static hosting) waste token budget without adding value.
Suggestions
Replace the abstract instruction steps with concrete, executable code snippets — e.g., show the actual Redoc CLI command (`npx @redocly/cli build-docs openapi.yaml --output docs/index.html`), a real redoc.yaml configuration template, and a working code example generator script.
Remove explanations of concepts Claude already knows (what CORS is, what OAuth2 flows are, what static hosting means) and replace with specific configuration values and templates.
Add validation checkpoints to the workflow — e.g., 'Run `npx @redocly/cli lint openapi.yaml` and fix all errors before proceeding' after step 1, and 'Verify generated examples compile/run against staging' after step 4.
Provide at least one complete, executable example showing the end-to-end flow for a simple API spec, including the input spec snippet, the commands to run, and the expected output structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is verbose and padded with information Claude already knows. It explains what CORS is, what OAuth2 flows are, what Faker does, and lists obvious hosting platforms. The prerequisites section describes things Claude doesn't need explained (e.g., 'Static site hosting for documentation deployment'). The examples section describes concepts rather than providing executable content. | 1 / 3 |
Actionability | Despite being lengthy, the skill contains zero executable code, no concrete commands, no configuration snippets, and no copy-paste-ready examples. Every instruction is a high-level description ('Generate interactive documentation using Redoc') without showing how. The examples section describes desired outcomes ('Stripe-style API docs') without any actionable implementation. | 1 / 3 |
Workflow Clarity | The 8 steps provide a reasonable sequence for the overall process, but there are no validation checkpoints, no feedback loops for error recovery, and no verification steps between stages. Step 1 mentions 'audit documentation completeness' but doesn't specify what to do if the audit fails. For a multi-step process involving code generation and deployment, the lack of validation caps this at 2. | 2 / 3 |
Progressive Disclosure | The skill references external files (implementation.md, errors.md, examples.md) which is good structure, but none of these bundle files actually exist. The main SKILL.md itself is a wall of descriptive text that could benefit from better organization. The references are one-level deep and clearly signaled, but their absence undermines the disclosure pattern. | 2 / 3 |
Total | 6 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
16dfbca
- 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.