jbvc/api-documentation-generator
Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
53
53%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
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 hurts completeness, and could benefit from more natural trigger terms that users would actually say. Adding trigger guidance and common keyword variations would significantly improve skill selection accuracy.
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 needs Swagger/OpenAPI documentation.'
Include more natural trigger term variations such as 'API docs', 'REST API', 'OpenAPI', 'Swagger', 'endpoint documentation', 'API reference' to improve matching against user requests.
| 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 file extensions. Coverage is decent but not comprehensive. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on API documentation from code is somewhat specific, but 'documentation' and 'code' are broad terms that could overlap with general documentation skills, code commenting skills, or README generation skills. The API focus helps but isn't fully distinctive. | 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-80% while improving effectiveness.
Suggestions
Reduce content to ~50-80 lines: keep only the output template/format examples and remove all explanatory sections about what API documentation is, when to use it, common pitfalls, and best practices that Claude already knows.
Add a concrete workflow with validation: e.g., 'Step 1: Read route files → Step 2: Extract endpoint signatures → Step 3: Generate docs using template → Step 4: Verify all endpoints are covered by cross-referencing route definitions'.
Move the detailed REST, GraphQL, and Auth examples into separate referenced files (e.g., TEMPLATES.md) and keep only a concise template skeleton in the main skill.
Replace the descriptive 'How It Works' steps with actionable instructions that tell Claude exactly what to look for in code (decorators, route definitions, schema files) and how to extract documentation from them.
| 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. No content is split into referenced files despite the document being extremely long. The 'Related Skills' and 'Additional Resources' sections reference external links but the core content is not structured for progressive disclosure. | 1 / 3 |
Total | 5 / 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.
Reviewed
Table of Contents