api-documentation-generator

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

Quality

58%

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

50%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 is rich with executable templates and a clear sequenced workflow, but it is verbose with generic API-doc advice Claude already knows and lacks validation checkpoints and external reference files. Splitting examples/templates into referenced files would substantially improve it.

Suggestions

Move the long Examples, Tools and Formats, and Common Pitfalls blocks into separate reference files (e.g. examples.md, templates.md) and link to them one level deep.

Trim generic best-practices do/don't and recommended-sections lists that Claude already knows; keep only skill-specific guidance.

Add explicit validation checkpoints to the workflow, e.g. 'verify every code example executes' and 'confirm doc matches actual endpoint responses' before finalizing.

Dimension	Reasoning	Score
Conciseness	The ~480-line body inlines several generic sections Claude already knows (Best Practices do/don't lists, Common Pitfalls, Recommended Sections, Additional Resources) alongside useful templates, making it noticeably verbose with padded material.	2 / 5
Actionability	Provides concrete, copy-paste-ready templates — full REST/GraphQL/auth examples with cURL/JS/Python, OpenAPI YAML, and Postman JSON — with only minor gaps (no generation scripts/commands).	4 / 5
Workflow Clarity	A clear 5-step sequence (analyze → generate endpoints → usage guidelines → error handling → interactive examples) is present, but validation checkpoints are only implicit (e.g. 'Don't Leave Examples Broken') with no verify-fix-retry loop in the workflow.	3 / 5
Progressive Disclosure	Section headers give reasonable structure, but the monolithic file inlines large blocks (three full examples, OpenAPI/Postman templates, pitfalls) that belong in separate reference files, and no bundle files are provided.	3 / 5
	Total	12 / 20 Passed

Description

66%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 clearly states what the skill does with several concrete capabilities, but omits any explicit 'when to use it' trigger guidance, which caps its completeness. It is specific and reasonably distinctive but could add natural trigger phrases and synonyms (OpenAPI/Swagger).

Suggestions

Add an explicit trigger clause, e.g. 'Use when documenting a new or existing API, creating OpenAPI/Swagger specs, or onboarding developers to an API.'

Include natural synonyms users say, such as 'OpenAPI', 'Swagger', 'API docs', and 'document my API'.

Mention auth and error-handling generation explicitly to close the specificity gap toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('endpoints, parameters, examples, and best practices') for the API-docs domain, but 'best practices' is generic and auth/error-handling coverage is only implied, leaving minor gaps versus the comprehensive anchor.	4 / 5
Completeness	The 'what' is clear and detailed ('Generate comprehensive... API documentation from code, including...'), but there is no 'Use when...' clause or equivalent explicit trigger guidance, capping completeness at 3 per the rubric.	3 / 5
Trigger Term Quality	Strong natural terms ('API documentation', 'endpoints', 'parameters', 'examples') that users would say, but missing common synonyms like 'OpenAPI', 'Swagger', 'API docs', or 'document my API'.	4 / 5
Distinctiveness Conflict Risk	'API documentation from code' carves a clear niche distinct from generic writing skills, with only minor overlap risk against adjacent doc/copywriting skills.	4 / 5
	Total	15 / 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: b1aebac

Reviewed: ~18 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.