api-documentation-generator

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

Quality

62%

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

65%Weight 40%Scale 1-3

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

The content shines on actionability with concrete multi-language examples, but it is verbose and monolithic, and its workflow lacks the validation checkpoints the skill itself tells users to enforce. Tightening prose and adding a verify step would raise the lower dimensions.

Suggestions

Add an explicit validation/verification step to the workflow (e.g., 'Step 6: Verify — run each example against the live API and confirm status codes/bodies match') to close the workflow-clarity gap.

Move the worked examples, the 'Documentation Structure' template, and the OpenAPI/Postman snippets into separate reference files (e.g., references/EXAMPLES.md, references/STRUCTURE.md) referenced one level deep, to reduce the monolithic body.

Trim generically-obvious material (the 'Recommended Sections' definitions, 'Common Pitfalls' restatements, and the Do/Don't lists) to content Claude does not already know, improving token efficiency.

Dimension	Reasoning	Score
Conciseness	The ~490-line body is mostly useful but padded with generically-obvious guidance (the 'Recommended Sections' definitions, 'Common Pitfalls', and Do/Don't best-practice lists) that restate knowledge Claude already has.	2 / 3
Actionability	It provides fully executable, copy-paste-ready examples in cURL, JavaScript fetch, Python requests, a GraphQL query, OpenAPI YAML, and a Postman JSON snippet, matching the anchor for concrete executable code.	3 / 3
Workflow Clarity	Steps 1–5 are clearly sequenced, but there are no validation or verification checkpoints (e.g., confirming examples run against the real API), which the rubric caps at 2 when validation gaps are present.	2 / 3
Progressive Disclosure	The body is a single monolithic ~490-line file; although well-sectioned, content like the full example set, structure template, and pitfalls could be split into separate one-level-deep reference files rather than kept inline.	2 / 3
	Total	9 / 12 Passed

Description

60%Weight 40%Scale 1-3

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 is specific and concrete about deliverables, but it omits any 'Use when...' trigger guidance, which caps both completeness and trigger-term quality. Adding an explicit invocation clause would lift the weakest dimensions.

Suggestions

Append an explicit 'Use when...' clause (e.g., 'Use when documenting a new or existing REST/GraphQL/WebSocket API, generating OpenAPI/Swagger specs, or onboarding developers to an API') to satisfy the completeness and trigger-term dimensions.

Add natural user phrasings such as 'document my API', 'API docs', and 'Swagger/OpenAPI' to broaden trigger-term coverage.

Sharpen the opening verb set to concrete actions (e.g., 'Generate, structure, and verify API documentation...') to reinforce distinctiveness from generic writing skills.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete deliverables — 'endpoints, parameters, examples, and best practices' — in third person ('Generate'), matching the anchor for enumerating specific actions.	3 / 3
Completeness	It clearly states what the skill does but provides no 'Use when...' or equivalent trigger for when to invoke it; per the rubric, a missing trigger clause caps completeness at 2.	2 / 3
Trigger Term Quality	It includes relevant terms like 'API documentation' and 'endpoints' but omits common natural variations a user would say (e.g., 'document my API', 'Swagger/OpenAPI', 'API docs'), so coverage is partial.	2 / 3
Distinctiveness Conflict Risk	The 'API documentation from code' niche is fairly specific, but without explicit triggers and with the broad term 'documentation' it could overlap with general doc-writing skills.	2 / 3
	Total	9 / 12 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/antigravity-awesome-skills
Path: skills/api-documentation-generator/SKILL.md
Commit: b7f833d

Reviewed: 4 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.