api-documentation-generator
Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
59
37%
Does it follow best practices?
Impact
99%
1.11xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/api-documentation-generator/SKILL.mdQuality
Discovery
60%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 does a good job listing specific capabilities around API documentation generation, naming concrete deliverables like endpoints, parameters, and examples. However, it lacks an explicit 'Use when...' clause, which is critical for skill selection, and could benefit from more natural trigger terms that users would actually say. The domain is reasonably distinct but could be sharpened further.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to document an API, generate API docs, create endpoint references, or produce OpenAPI/Swagger documentation.'
Include more natural trigger term variations such as 'API docs', 'REST API', 'OpenAPI', 'Swagger', 'endpoint documentation', and 'docstrings' to improve matching.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: generating API documentation from code, covering endpoints, parameters, examples, and best practices. These are concrete, identifiable outputs. | 3 / 3 |
Completeness | Clearly answers 'what does this do' (generate API documentation from code with specific elements), but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes good terms like 'API documentation', 'endpoints', 'parameters', and 'examples', but misses common user variations like 'API docs', 'REST API', 'Swagger', 'OpenAPI', 'docstrings', or file extensions. Coverage is decent but not comprehensive. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on API documentation from code is fairly specific, but 'documentation' and 'best practices' could overlap with general documentation skills or code review skills. The API focus helps but isn't fully disambiguated. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
14%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 general tutorial or blog post about API documentation best practices than an actionable skill for Claude. It is extremely verbose, explaining many concepts Claude already knows, while lacking concrete workflow steps, validation checkpoints, and any progressive disclosure structure. The example output templates have some value but are buried in excessive padding.
Suggestions
Cut the content by 70%+: remove 'When to Use', 'Common Pitfalls', 'Best Practices' do/don't lists, 'Documentation Structure' recommended sections, and 'Additional Resources'—Claude already knows all of this.
Replace the vague 5-step 'How It Works' with a concrete workflow: e.g., 1) scan route files for endpoints, 2) extract parameter types from schemas/decorators, 3) generate docs in specified format, 4) validate examples against actual endpoint responses.
Move the lengthy REST/GraphQL/Auth examples into separate reference files (e.g., EXAMPLES.md or TEMPLATES.md) and link to them from a concise overview.
Add explicit validation steps: e.g., verify generated cURL examples are syntactically valid, check that documented parameters match code signatures, confirm response schemas match actual responses.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. Explains concepts Claude already knows (what REST APIs are, what HTTP methods are, what authentication is). The 'When to Use This Skill' section, 'How It Works' steps, 'Common Pitfalls', 'Best Practices' do/don't lists, and 'Documentation Structure' sections are all things Claude inherently understands. The examples are useful but massively padded with obvious guidance. | 1 / 3 |
Actionability | The examples show concrete output formats (REST endpoint docs, GraphQL docs, OpenAPI YAML), which is useful as templates. However, the skill never provides executable code or commands for actually generating documentation—it describes what documentation should look like rather than giving Claude specific instructions on how to analyze code and produce it. It's more of a style guide than an actionable procedure. | 2 / 3 |
Workflow Clarity | The 5-step 'How It Works' process is vague and descriptive rather than prescriptive—it says 'I'll examine your API codebase' and 'I'll create documentation' without concrete steps, commands, or validation checkpoints. There's no feedback loop for verifying generated documentation accuracy against actual code behavior, and no validation steps whatsoever. | 1 / 3 |
Progressive Disclosure | The entire skill is a monolithic wall of text with no references to external files. All content—examples, best practices, tools, common pitfalls, documentation structure recommendations—is inlined. The examples alone (REST, GraphQL, Auth) could easily be separate reference files, and the OpenAPI/Postman sections could be split out. | 1 / 3 |
Total | 5 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- sickn33/antigravity-awesome-skills
- Commit
d739c8b
- 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.