api-documentation-generator

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

Quality

52%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/api-documentation-generator/SKILL.md

Quality

Content

46%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 body delivers genuinely strong, complete code examples, but it buries them in a ~480-line monolith padded with generic API-documentation knowledge Claude already possesses. Splitting the examples and format templates into reference files and converting the descriptive first-person steps into an executable, validated workflow would address both major weaknesses.

Suggestions

Move the three long example documents and the OpenAPI/Postman templates into references/ files (e.g. references/examples.md, references/formats.md) and keep SKILL.md as a concise overview with one-level-deep, clearly signaled links.

Cut the generic "Best Practices", "Recommended Sections", and "Common Pitfalls" sections down to only non-obvious, project-specific guidance; Claude already knows standard API-doc conventions.

Turn the five steps into an executable workflow with a validation checkpoint — e.g. after generating examples, verify each cURL/request example against the actual routes before finishing.

Dimension	Reasoning	Score
Conciseness	The ~480-line body spends large sections restating knowledge Claude already has: a 10-item "✅ Do This" / 8-item "❌ Don't Do This" best-practice list, a 9-section "Recommended Sections" outline, generic "Common Pitfalls", and three full-length example documents. This matches anchor 2 (several unnecessary explanations or padded sections); it avoids anchor 1 only because the examples themselves are on-topic and not tutorials about what an API is.	2 / 5
Actionability	The examples are concrete and complete — copy-paste-ready cURL, JavaScript fetch, Python requests, GraphQL, OpenAPI YAML, and a Postman collection. Not anchor 5 because the five workflow steps are descriptive first-person plans ("I'll examine your API codebase to understand...") rather than executable instructions, leaving a gap in how to actually perform Step 1's analysis.	4 / 5
Workflow Clarity	Steps 1–5 (analyze structure, generate endpoint docs, add usage guidelines, document errors, create interactive examples) are clearly sequenced, but there are no validation checkpoints — e.g. the skill's own best practice "Don't Leave Examples Broken — test all code examples" never appears as a workflow step. This matches anchor 3 (sequence present, checkpoints missing); it is not capped lower because the task is document generation, not a destructive or batch operation.	3 / 5
Progressive Disclosure	There are no bundle files at all (no references/, scripts/, or assets/ directories), and everything is inlined in one monolithic SKILL.md — including three 60–100-line example documents and full OpenAPI/Postman templates that clearly belong in separate reference files. This matches anchor 2 (content that clearly belongs in separate files is inlined); the section headers keep it above anchor 1's unstructured wall of text.	2 / 5
	Total	11 / 20 Passed

Description

58%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.

The description states a concrete, third-person capability with a clear list of deliverables, but it entirely lacks a "Use when..." trigger clause and misses natural trigger terms like OpenAPI/Swagger that users would actually say. It is serviceable but below the standard of the good examples, which pair a crisp what with explicit when-phrases.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks to document an API, create API docs, or generate OpenAPI/Swagger specifications."

Include natural synonyms users would say — "API docs", "OpenAPI", "Swagger", "reference documentation" — to improve trigger-term coverage.

Trim subjective padding ("comprehensive, developer-friendly") and instead name one or two more concrete outputs such as authentication details and error-code references.

Dimension	Reasoning	Score
Specificity	"Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices" names the domain and lists several concrete deliverables (endpoints, parameters, examples). It is not a 5 because "comprehensive, developer-friendly" is mild padding and coverage has minor gaps (no mention of authentication or error handling, which the body itself treats as core outputs).	4 / 5
Completeness	The description clearly answers "what" (generate API documentation from code with endpoints, parameters, examples) but contains no "Use when..." clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It is above anchor 2 because the "what" is concrete, not vague.	3 / 5
Trigger Term Quality	Relevant keywords like "API documentation", "endpoints", and "parameters" are present, but common natural variations users would say — "OpenAPI", "Swagger", "API docs", "document my API" — are missing. This matches anchor 3 (some relevant keywords, missing common variations) rather than anchor 4's good coverage.	3 / 5
Distinctiveness Conflict Risk	"API documentation" plus "endpoints, parameters" carves a mostly distinct niche with only minor overlap risk against general technical-writing or documentation skills. Not anchor 5 because the triggers are not specific enough to fully separate it from sibling docs/writing skills.	4 / 5
	Total	14 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: sickn33/agentic-awesome-skills
Path: skills/api-documentation-generator/SKILL.md
Commit: c26b706

Reviewed: 2 hours 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.