api-documentation-generator
Generate comprehensive API documentation from repository sources including OpenAPI specs, code comments, docstrings, and existing documentation. Use when documenting APIs, creating API reference guides, or summarizing API functionality from codebases. Extracts endpoint details, request/response schemas, authentication methods, and generates code examples. Triggers when users ask to document APIs, generate API docs, create API reference, or summarize API endpoints from a repository.
93
92%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the key criteria. It provides specific concrete actions, includes comprehensive natural trigger terms users would actually say, explicitly addresses both what the skill does and when to use it, and carves out a distinct niche around API documentation that minimizes conflict risk with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Generate comprehensive API documentation', 'Extracts endpoint details, request/response schemas, authentication methods', 'generates code examples'. Also specifies sources: 'OpenAPI specs, code comments, docstrings, and existing documentation'. | 3 / 3 |
Completeness | Clearly answers both what ('Generate comprehensive API documentation...Extracts endpoint details, request/response schemas, authentication methods, and generates code examples') AND when ('Use when documenting APIs, creating API reference guides...Triggers when users ask to document APIs, generate API docs, create API reference, or summarize API endpoints'). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'documenting APIs', 'API reference guides', 'API docs', 'API reference', 'API endpoints', 'OpenAPI specs'. These are terms users would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on API documentation with distinct triggers like 'OpenAPI specs', 'API reference', 'endpoint details', 'request/response schemas'. Unlikely to conflict with general documentation or code generation skills due to specific API focus. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, comprehensive skill for API documentation generation. It excels in actionability with executable examples and clear workflow structure with validation checkpoints. The main weakness is some verbosity - the endpoint documentation format is demonstrated multiple times and could be consolidated, though this redundancy may aid clarity for complex documentation tasks.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some redundancy - the endpoint documentation examples are shown multiple times in slightly different contexts, and some explanations (like the discovery approach) could be tightened. However, it largely avoids explaining concepts Claude already knows. | 2 / 3 |
Actionability | Provides fully executable code examples throughout - bash commands for discovery, complete curl examples, Python code snippets, and detailed markdown templates. The documentation format examples are copy-paste ready and the workflow steps are concrete. | 3 / 3 |
Workflow Clarity | Clear 7-step workflow with explicit sequencing (Discover → Extract → Organize → Generate → Include Examples → Handle Special Cases → Quality Checks). Includes a comprehensive quality checklist at the end serving as validation, and handles edge cases like missing specs or incomplete information. | 3 / 3 |
Progressive Disclosure | Well-organized with clear sections, references external template file appropriately (assets/api-doc-template.md), and structures content logically from overview through detailed examples. The example workflows at the end provide practical application without cluttering the main instructions. | 3 / 3 |
Total | 11 / 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 |
|---|---|---|
skill_md_line_count | SKILL.md is long (518 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- ArabelaTso/Skills-4-SE
- Commit
0f00a4f
- 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.