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/antigravity-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 (endpoints, parameters, examples, best practices) and clearly identifies its domain (API documentation from code). However, it lacks an explicit 'Use when...' clause, which is critical for Claude to know when to select this skill, and could benefit from more natural trigger terms that users would actually say.
Suggestions
Add a 'Use when...' clause such as 'Use when the user asks to document an API, generate API docs, create endpoint references, or produce API specifications from source code.'
Include additional natural trigger terms like 'API docs', 'REST API', 'OpenAPI', 'Swagger', 'API reference', or 'document endpoints' to improve keyword 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 relevant terms like 'API documentation', 'endpoints', 'parameters', and 'examples', but misses common user variations like 'API docs', 'REST API', 'Swagger', 'OpenAPI', 'docstrings', or 'API reference'. | 2 / 3 |
Distinctiveness Conflict Risk | Fairly specific to API documentation generation, but could overlap with general documentation skills or code commenting skills. The phrase 'from code' helps narrow it, but without explicit trigger boundaries it could still conflict with broader documentation tools. | 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 tutorial or blog post about API documentation best practices than an actionable skill for Claude. It's extremely verbose, explaining concepts Claude already knows, and lacks concrete executable workflows. The examples showing what good documentation looks like are somewhat useful as templates, but the overall content could be reduced by 70%+ while improving clarity.
Suggestions
Reduce content to ~50-80 lines by removing sections Claude already knows (what APIs are, basic best practices, common pitfalls) and focus on a concise template/format specification for generated docs.
Add a concrete, step-by-step workflow with validation: e.g., 1) scan route files, 2) extract endpoint signatures, 3) generate docs in specified format, 4) validate all examples compile/parse correctly.
Move the detailed REST, GraphQL, and Auth examples into separate reference files (e.g., EXAMPLES.md) and link to them from a concise overview.
Replace the descriptive 'How It Works' narrative with actionable instructions: specific file patterns to look for, specific tools/commands to use, and explicit output format requirements.
| 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 | Provides concrete example outputs (REST endpoint docs, GraphQL docs, OpenAPI snippets) which are useful as templates, but the skill describes a process rather than giving executable instructions. There are no actual commands or code to run that generate documentation—it's mostly showing what good documentation looks like rather than how to produce it programmatically. | 2 / 3 |
Workflow Clarity | The 5-step workflow (Analyze, Generate, Add Guidelines, Document Errors, Create Examples) is vague and descriptive rather than actionable. Steps like 'I'll examine your API codebase' and 'I'll include' are not concrete instructions with validation checkpoints. There's no verification step to ensure generated documentation is accurate or complete. | 1 / 3 |
Progressive Disclosure | Monolithic wall of text with everything inline. The massive examples (REST, GraphQL, Auth) could easily be in separate reference files. The 'Related Skills' and 'Additional Resources' sections reference external links but the core content is not split or organized for progressive discovery. No internal file references for detailed content. | 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
- boisenoise/skills-collections
- Commit
636b862
- 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.