api-documentation-generator

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

1.11x

Quality

58%

Does it follow best practices?

Impact

99%

1.11x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/AI-Agents-Safe-Coding-Skills/skills/api-documentation-generator/SKILL.md

The canonical home for this skill is api-documentation-generator in sickn33/agentic-awesome-skills

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 offers strong, executable examples across REST/GraphQL/auth and tooling formats, but is padded with generic guidance Claude already knows, lacks validation steps in its workflow, and keeps everything in one oversized file instead of progressively disclosing to reference files.

Suggestions

Trim or remove the generic 'Best Practices' Do/Don't, 'Common Pitfalls', 'Documentation Structure', and 'Related Skills' sections — Claude already knows this material.

Add an explicit validation step to the workflow, e.g. 'Verify every code example runs and matches the current API before finalizing docs', with a fix-and-retry loop.

Move the three large worked examples and the OpenAPI/Postman specs into reference files (e.g. references/examples.md, references/formats.md) and link to them one level deep, leaving SKILL.md a lean overview.

Dimension	Reasoning	Score
Conciseness	The 480-line body is noticeably verbose, with padded sections Claude does not need — generic Do/Don't best-practice lists, Common Pitfalls, a recommended Documentation Structure, Related Skills, and a closing Pro Tip — alongside genuinely useful examples.	2 / 5
Actionability	Provides concrete, copy-paste-ready examples in cURL, JavaScript fetch, Python requests, GraphQL, OpenAPI YAML, and Postman JSON that cover the common cases; minor gaps stem from the descriptive 'How It Works' steps.	4 / 5
Workflow Clarity	A clear 5-step sequence exists (Analyze, Generate, Usage, Errors, Examples) but it has no validation or verification checkpoint, and a batch documentation-generation workflow without a 'verify examples work / docs match code' step caps clarity at 3.	3 / 5
Progressive Disclosure	Sections are well-organized with clear headers, but no bundle/reference files exist and large blocks that belong in separate files (three full examples, OpenAPI/Postman specs, the doc-structure guide) are all inlined in one monolithic SKILL.md.	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 and names concrete outputs, but it lacks any explicit 'when to use' trigger guidance and misses common synonyms like Swagger/OpenAPI. It is specific and largely distinct but incomplete as a trigger.

Suggestions

Add an explicit 'Use when...' clause naming trigger situations, e.g. 'Use when documenting a new or existing REST/GraphQL API, or when creating OpenAPI/Swagger specs'.

Include natural trigger synonyms users actually say — 'Swagger', 'OpenAPI spec', 'REST API docs', 'GraphQL schema docs' — to improve trigger term coverage.

Drop the filler adjectives 'comprehensive, developer-friendly' to tighten the description without losing meaning.

Dimension	Reasoning	Score
Specificity	Lists several concrete artifacts the skill produces ('endpoints, parameters, examples, and best practices'), though 'best practices' is generic and prevents a top score.	4 / 5
Completeness	The 'what' is clearly stated but there is no 'Use when...' clause or equivalent trigger guidance, which the rubric caps at 3.	3 / 5
Trigger Term Quality	Includes natural phrases like 'API documentation', 'endpoints', 'parameters', and 'examples', but omits common synonyms users say such as 'Swagger', 'OpenAPI spec', or 'REST docs'.	4 / 5
Distinctiveness Conflict Risk	The API-documentation niche is mostly distinct from generic writing skills, with only minor overlap risk against closely related 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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/api-documentation-generator/SKILL.md
Commit: 900c504

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