api-documentation-generator

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

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

50%

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

Highly actionable with excellent copy-paste examples, but the body is verbose and explains concepts Claude already knows, and its multi-step workflow lacks explicit validation checkpoints. Moving examples and reference material into separate bundle files would also improve progressive disclosure.

Suggestions

Trim generic explanatory prose (e.g. REST/GraphQL/WebSocket basics and the long do/don't lists) to assume Claude's competence and cut token usage.

Add explicit validation checkpoints to the workflow (e.g. 'Verify generated examples are executable' between steps) to lift workflow clarity.

Split the three full examples and the OpenAPI/Postman snippets into referenced reference files (e.g. EXAMPLES.md, FORMATS.md) so the main body is a lean overview.

Dimension	Reasoning	Score
Conciseness	The ~485-line body explains concepts Claude already knows (REST/GraphQL/WebSocket basics, generic do/don't best-practice lists, lengthy prose descriptions of each step) rather than leaning on Claude's competence — padded with unnecessary context.	1 / 3
Actionability	Provides complete, copy-paste-ready cURL/JavaScript/Python examples, concrete OpenAPI and Postman JSON snippets, and real request/response payloads with status codes — fully executable guidance.	3 / 3
Workflow Clarity	A five-step process is clearly sequenced, but steps describe what will be done ('I'll examine', 'I'll create') without validation checkpoints or error-recovery feedback loops, which the rubric caps at 2.	2 / 3
Progressive Disclosure	Sections are well-organized, but the body is a monolithic single file with three full examples, best-practice lists, pitfalls, and structure guidance inlined that would be better split into separate reference files; no bundle references exist to offload detail.	2 / 3
	Total	8 / 12 Passed

Description

60%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A specific, third-person description that names several concrete capabilities, but it omits an explicit 'Use when...' trigger clause and leans on slightly generic phrasing. Adding natural trigger terms and a clear when-to-use clause would raise it from a solid 2-range to a strong 3.

Suggestions

Add an explicit trigger clause, e.g. 'Use when documenting or updating an API, or when creating OpenAPI/Swagger specs from code.'

Include natural phrasings users actually say, such as 'API docs', 'document my API', or 'write API documentation'.

Tighten 'best practices' to a concrete artifact (e.g. 'and usage guidelines with code examples') to sharpen distinctiveness.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions in third person — 'endpoints, parameters, examples, and best practices' generated 'from code' — covering generation scope comprehensively.	3 / 3
Completeness	Answers 'what' clearly but has no 'Use when...' clause or explicit trigger guidance in the description, so the 'when' is only implied — capping completeness at 2 per the rubric guideline.	2 / 3
Trigger Term Quality	Includes 'API documentation', 'endpoints', 'parameters', and 'OpenAPI/Swagger' but is missing the most common natural phrasings a user would say ('document my API', 'API docs', 'write API documentation').	2 / 3
Distinctiveness Conflict Risk	The 'API documentation' niche is reasonably distinct, but the bare phrase 'best practices' and lack of trigger terms leave overlap with general documentation/copywriting 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: boisenoise/skills-collections
Commit: f36337d

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