api-documentation-generator

tessl i github:sickn33/antigravity-awesome-skills --skill api-documentation-generator

Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices

53%

Overall

Validation — 81%

Implementation — 27%

Activation — 68%

SKILL.md

Review

Evals

Validation

81%

Warnings & errors only

Criteria	Description	Result
description_trigger_hint	Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...')	Warning
metadata_version	'metadata' field is not a dictionary	Warning
license_field	'license' field is missing	Warning

	Total	13 / 16 Passed

Implementation

27%

This skill is excessively verbose, explaining basic concepts Claude already understands while providing extensive example output rather than actionable generation instructions. The content would benefit from dramatic trimming, focusing on the specific patterns and decisions Claude should make when generating API docs, with examples moved to separate reference files.

Suggestions

Reduce content by 70%+ by removing explanations of basic concepts (REST, authentication, HTTP methods) and assuming Claude's competence

Add executable code or clear commands for actually generating documentation from code (e.g., parsing route decorators, extracting JSDoc comments)

Move the extensive examples (REST endpoint, GraphQL, Authentication) to separate reference files and link to them from a concise overview

Add validation steps to the workflow (e.g., 'Verify all documented endpoints exist in code', 'Test example requests against actual API')

Dimension	Reasoning	Score
Conciseness	Extremely verbose with extensive explanations of concepts Claude already knows (what REST APIs are, what authentication is, basic HTTP methods). The document is over 400 lines when the core actionable content could be conveyed in under 100 lines.	1 / 3
Actionability	Provides concrete examples of documentation output format, but lacks executable code for actually generating documentation from code. The examples show what documentation looks like, not how to create it programmatically.	2 / 3
Workflow Clarity	Steps 1-5 outline a process but lack validation checkpoints or feedback loops. No verification steps to ensure generated documentation is accurate or complete. The workflow describes what to include but not how to validate the output.	2 / 3
Progressive Disclosure	Monolithic wall of text with everything inline. The 'Related Skills' and 'Additional Resources' sections reference external content, but the main body dumps hundreds of lines of examples and best practices that should be in separate reference files.	1 / 3
	Total	6 / 12 Passed

Activation

68%

The description effectively communicates specific capabilities for API documentation generation with concrete deliverables (endpoints, parameters, examples, best practices). However, it lacks explicit trigger guidance ('Use when...') which limits Claude's ability to know when to select this skill, and could benefit from more natural keyword variations that users might actually say.

Suggestions

Add a 'Use when...' clause with trigger scenarios like 'Use when the user asks to document an API, generate API docs, create endpoint documentation, or mentions swagger/OpenAPI'

Include common keyword variations users might say: 'docs', 'swagger', 'OpenAPI', 'REST API docs', 'API reference'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices' - covers documentation generation with specific deliverables.	3 / 3
Completeness	Clearly answers 'what' (generate API documentation with specific components) but lacks an explicit 'Use when...' clause or trigger guidance for when Claude should select this skill.	2 / 3
Trigger Term Quality	Contains relevant keywords like 'API documentation', 'endpoints', 'parameters', but missing common variations users might say like 'docs', 'swagger', 'OpenAPI', 'REST API', or file extensions.	2 / 3
Distinctiveness Conflict Risk	Clear niche focused specifically on API documentation generation from code - distinct from general documentation skills or code generation skills, with specific domain markers like 'endpoints' and 'parameters'.	3 / 3
	Total	10 / 12 Passed

Reviewed

15 days ago

Table of Contents

Validation Implementation Activation

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.