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.

Quality

92%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

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

Description

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

Validation

90%

Warnings & errors only

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: 4 months ago

Table of Contents

Discovery Implementation Validation

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.