generating-api-docs

tessl i github:jeremylongshore/claude-code-plugins-plus-skills --skill generating-api-docs

Create comprehensive API documentation with examples, authentication guides, and SDKs. Use when creating comprehensive API documentation. Trigger with phrases like "generate API docs", "create API documentation", or "document the API".

55%

Overall

Validation — 81%

Implementation — 22%

Activation — 82%

SKILL.md

Review

Evals

Validation

81%

Warnings & errors only

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
metadata_version	'metadata' field is not a dictionary	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	13 / 16 Passed

Implementation

22%

This skill content is poorly structured and lacks actionable guidance for generating API documentation. It reads more like a generic project template than a skill for documentation generation, with vague instructions, no concrete examples of documentation output, and confusing duplicate step numbering. The title says 'Generating API Docs' but the content focuses on building APIs rather than documenting them.

Suggestions

Add concrete examples of API documentation output (e.g., OpenAPI spec snippets, markdown documentation templates) that Claude can use as reference

Fix the duplicate step numbering and create a clear sequential workflow with explicit phases (analyze -> generate -> validate)

Include executable code or commands for documentation generation tools (e.g., swagger-jsdoc, pydoc, actual CLI commands)

Remove the redundant overview sentences and generic prerequisites; focus on documentation-specific guidance rather than API development guidance

Dimension	Reasoning	Score
Conciseness	Contains some unnecessary boilerplate phrases like 'This skill provides automated assistance for...' repeated twice, and generic prerequisites that Claude would know. However, the structure is reasonably compact overall.	2 / 3
Actionability	Extremely vague with no concrete code examples, no actual API documentation templates, no executable commands. Instructions like 'Define resource models' and 'Document request/response schemas' describe rather than instruct with specifics.	1 / 3
Workflow Clarity	Steps are poorly organized with duplicate numbering (two separate lists both starting at 1), no validation checkpoints, and the workflow jumps from planning to code generation without clear transitions. Missing any verification steps for documentation accuracy.	1 / 3
Progressive Disclosure	References external files appropriately (implementation.md, errors.md, examples.md) which is good structure, but the main content is too thin to serve as a useful overview. The skill offloads too much to external files without providing actionable quick-start content.	2 / 3
	Total	6 / 12 Passed

Activation

82%

This is a reasonably well-structured description with explicit trigger guidance and a clear 'Use when' clause. The main weakness is the somewhat circular 'Use when creating comprehensive API documentation' which doesn't add much beyond the first sentence, and the specificity could be improved by detailing more concrete outputs or formats.

Suggestions

Make the 'Use when' clause more specific about scenarios (e.g., 'Use when documenting REST APIs, generating endpoint references, or creating developer onboarding materials')

Add more specific capabilities like 'generate OpenAPI specs', 'create endpoint references', or 'build interactive API explorers' to increase specificity

Dimension	Reasoning	Score
Specificity	Names the domain (API documentation) and lists some actions (examples, authentication guides, SDKs), but 'comprehensive' is vague and the specific actions could be more detailed about what exactly is created or how.	2 / 3
Completeness	Clearly answers both what (create API documentation with examples, authentication guides, SDKs) and when (explicit 'Use when' clause and 'Trigger with phrases' providing clear activation guidance).	3 / 3
Trigger Term Quality	Includes good natural trigger phrases users would say: 'generate API docs', 'create API documentation', 'document the API', plus mentions 'SDKs' and 'authentication guides' which are relevant terms.	3 / 3
Distinctiveness Conflict Risk	While 'API documentation' is fairly specific, it could overlap with general documentation skills or code documentation skills. The triggers help but 'comprehensive documentation' is somewhat generic.	2 / 3
	Total	10 / 12 Passed

Reviewed

16 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.