api-documentation

API documentation workflow for generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

35%

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

The skill lays out a clear multi-phase structure but offers almost no concrete, executable guidance — its actions are abstract directives and its only "code" is thin skill-invocation prompts — and it keeps all content inline in one file with no progressive disclosure.

Suggestions

Replace abstract action items with concrete, executable guidance: example OpenAPI YAML snippets, curl/SDK examples, and actual commands rather than 'Create OpenAPI schema'.

Add validation checkpoints between phases (e.g., 'Validate the OpenAPI spec with a linter before writing the developer guide') to turn the terminal checklist into inline feedback loops.

Move per-phase detail (e.g., full OpenAPI authoring steps, developer-guide templates) into reference files under references/ and link to them one level deep to reduce inline bulk.

Dimension	Reasoning	Score
Conciseness	The body uses terse bullets and avoids explaining concepts Claude already knows, but it is padded with low-value copy-paste prompt blocks and repeats `api-documenter` across nearly every phase, so it could be tightened.	2 / 3
Actionability	Every action is an abstract directive ("Create OpenAPI schema", "Define paths", "Inventory endpoints") with no executable code or commands; the copy-paste prompts are trivial skill-invocation wrappers, so it describes rather than instructs.	1 / 3
Workflow Clarity	The seven phases are clearly sequenced and a terminal Quality Gates checklist exists, but there are no inter-phase validation checkpoints or feedback loops, leaving validation implicit.	2 / 3
Progressive Disclosure	The file is well-sectioned into phases but is a monolithic ~160-line SKILL.md with no bundle files or one-level-deep references; some per-phase detail could be externalized to reference files.	2 / 3
	Total	7 / 12 Passed

Description

75%

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 uses natural trigger terms, but it omits any explicit "when to use" guidance, which caps completeness and slightly raises conflict risk with adjacent documentation skills.

Suggestions

Add an explicit 'Use when...' clause naming common trigger phrases (e.g., 'Use when creating API docs, OpenAPI/Swagger specs, or developer guides').

Include more trigger variations users would say (e.g., Swagger, REST API reference, endpoint documentation) to sharpen distinctiveness from general documentation skills.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — "generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation" — matching the anchor for several specific concrete actions rather than vague language.	3 / 3
Completeness	It clearly answers "what" but provides no "Use when…" clause or equivalent explicit trigger guidance, so per the judging guidelines completeness is capped at 2.	2 / 3
Trigger Term Quality	It surfaces natural terms a user would actually say ("API documentation", "OpenAPI specs", "developer guides"), giving good coverage of trigger keywords rather than a single generic term.	3 / 3
Distinctiveness Conflict Risk	The API-documentation niche is somewhat specific, but without explicit triggers it could still overlap with general documentation skills (the body itself lists "documentation" as a related bundle).	2 / 3
	Total	10 / 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.