api-documentation-generator
Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
49
37%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
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 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 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 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, while lacking concrete workflows for actually extracting API information from code and generating documentation. The examples show what good output looks like but don't provide executable steps to produce that output from a codebase.
Suggestions
Cut the content by 60-70%: remove 'When to Use', 'Common Pitfalls', 'Best Practices' do/don't lists, 'Documentation Structure' recommended sections, and 'Additional Resources'—Claude already knows these concepts.
Add a concrete, executable workflow: specify how to scan route files (e.g., grep for decorators like @app.route, @Get, etc.), extract parameter types, and generate structured output, with validation steps to verify completeness.
Provide one concise output template instead of three lengthy examples—a single parameterized template that covers REST endpoints would be more token-efficient and actionable.
Split detailed examples (GraphQL, OpenAPI spec, Postman collection) into separate bundle files referenced from the main SKILL.md to improve progressive disclosure.
| 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' recommended sections are all things Claude inherently understands. The massive example blocks repeat similar patterns across REST, GraphQL, and auth without adding proportional value. | 1 / 3 |
Actionability | The examples are concrete and show realistic API documentation output (JSON schemas, cURL commands, multi-language examples, OpenAPI YAML). However, the skill describes a process ('I'll examine your API codebase') rather than providing executable instructions Claude can follow. There are no concrete commands for extracting routes from code, no specific tool invocations, and no actual code-generation scripts—it's mostly a template/reference for what good API docs look like rather than how to generate them from code. | 2 / 3 |
Workflow Clarity | The 5-step workflow (Analyze, Generate, Add Guidelines, Document Errors, Create Examples) is vague and descriptive rather than actionable. There are no validation checkpoints, no feedback loops, no verification that generated documentation matches actual API behavior. Steps like 'I'll examine your API codebase' and 'I'll include' describe intent without concrete procedures. | 1 / 3 |
Progressive Disclosure | Monolithic wall of text with no bundle files to reference. All content is inline—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' sections link externally but don't organize the skill's own content across files. | 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
431bfad
- 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.