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

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

68%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is highly actionable with concrete discovery commands, code, and templates, but the body is verbose: it inlines template content that duplicates the provided bundle and lacks an explicit validation feedback loop for its batch file-writing operation.

Suggestions

Remove the large inline markdown templates (README, endpoints, schemas, errors) from the body and rely on the assets/api-doc-template.md bundle, keeping only a brief structural summary inline to improve conciseness and progressive disclosure.

Add an explicit validation feedback loop to the workflow (e.g., verify generated links resolve and that every discovered endpoint is documented, then fix and re-check) so the batch file-writing operation has a validate-fix-retry checkpoint.

Trim the generic 'Tips for Effective Documentation' section, which restates documentation-writing basics Claude already knows, to reclaim token budget.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with concrete templates and commands, but the 500+ line body inlines extensive markdown templates that duplicate the assets bundle and restates generic documentation-writing advice Claude already knows.	3 / 5
Actionability	Fully executable guidance: real find/grep discovery commands, language-specific extraction patterns, complete endpoint/schemas/errors markdown templates, and curl/Python code examples covering common cases.	5 / 5
Workflow Clarity	A clear 7-step sequence with a quality-check list exists, but for a batch file-writing skill there is no validate-fix-retry feedback loop; the quality checks are a static checklist rather than a validation loop, capping the score per the rubric.	3 / 5
Progressive Disclosure	A real bundle (assets/api-doc-template.md) is referenced clearly twice as one-level-deep links, but large template blocks are inlined in the body that overlap the bundle, slightly blunting the disclosure benefit.	4 / 5
	Total	15 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that clearly states capabilities and triggers in third person with concrete, natural phrasing. Only minor synonym/extension gaps in trigger terms prevent a perfect trigger_term_quality score.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions across explicit source types — 'extract endpoint details, request/response schemas, authentication methods, and generates code examples' — for comprehensive coverage.	5 / 5
Completeness	Explicitly answers what ('Generate comprehensive API documentation... Extracts endpoint details...') and when ('Use when documenting APIs... Triggers when users ask to...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Strong natural phrases users would say ('document APIs', 'generate API docs', 'create API reference', 'summarize API endpoints', 'OpenAPI'); a few synonyms like 'Swagger' or file extensions are missing.	4 / 5
Distinctiveness Conflict Risk	Clear niche of generating API documentation from repository sources with distinct triggers and minimal overlap with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

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 — 14 / 16 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
relative_links	Relative link issues: 6 missing	Warning

	Total	14 / 16 Passed

Repository: ArabelaTso/Skills-4-SE
Path: skills/api-documentation-generator/SKILL.md
Commit: 4f38503

Reviewed: 21 days 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.