api-documentation-generator
Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
39
37%
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 ./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 and variations that users would actually say.
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 developer documentation from source code.'
Include common trigger term variations such as 'API docs', 'REST API', 'OpenAPI', 'Swagger', 'endpoint documentation', or 'reference docs' to improve matching coverage.
| 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 distinct without explicit trigger boundaries. | 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 blog post or tutorial about API documentation best practices than an actionable skill for Claude. It is extremely verbose, explaining many concepts Claude already knows, and provides output templates rather than concrete instructions for analyzing code and generating documentation. The workflow is descriptive rather than prescriptive, lacking validation steps and concrete commands.
Suggestions
Cut the content by 60-70%: remove 'When to Use', 'How It Works' narrative descriptions, generic best practices, and common pitfalls that Claude already knows. Focus on the specific output format templates and any non-obvious conventions.
Add concrete, actionable instructions for HOW to analyze code — e.g., specific patterns to look for in route definitions, decorator patterns, framework-specific extraction approaches (Express, FastAPI, Django, etc.).
Replace the vague 5-step 'How It Works' with a concrete workflow: 1) Identify framework → 2) Extract routes/handlers → 3) Infer schemas from types/validation → 4) Generate doc in specified format → 5) Validate completeness against route list.
Split the large example templates (REST, GraphQL, Auth, OpenAPI) into separate bundle files and reference them from a concise SKILL.md overview.
| 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' and 'How It Works' sections describe rather than instruct. The 'Best Practices' do/don't lists, 'Common Pitfalls', and 'Documentation Structure' sections are generic knowledge Claude already possesses. Most of this content is padding. | 1 / 3 |
Actionability | The examples (REST endpoint doc, GraphQL doc, auth doc, OpenAPI YAML, Postman JSON) are concrete and well-formed, which is good. However, the skill doesn't provide actionable instructions for *how to generate* documentation from code — it mostly shows what the output should look like. There are no executable scripts, no code-scanning commands, no concrete steps for extracting endpoints from a codebase. It's more of a template gallery than an executable workflow. | 2 / 3 |
Workflow Clarity | The 5-step 'How It Works' section is vague and descriptive ('I'll examine your API codebase', 'I'll create documentation including') rather than providing a clear, actionable sequence. There are no validation checkpoints, no feedback loops, and no concrete commands to execute at each step. It reads like a marketing description of capabilities rather than a workflow. | 1 / 3 |
Progressive Disclosure | Everything is crammed into a single monolithic file with no bundle files. The massive examples, best practices, common pitfalls, tools section, and documentation structure could all be split into separate reference files. The 'Related Skills' and 'Additional Resources' link to external resources but there's no internal structure. The content is a wall of text that would benefit enormously from splitting. | 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
8854d4e
- 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.