api-documentation

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

Quality

56%

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/SKILL.md

Quality

Content

53%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 workflow is clearly structured and token-efficient, but it operates almost entirely at the orchestration level: phases name other skills to invoke and list abstract actions without a single concrete command, example, or validation step. Adding executable detail (e.g., a sample OpenAPI snippet, a spec-validation command, and per-phase verification) would substantially improve actionability and workflow clarity.

Suggestions

Add at least one concrete, executable artifact per phase — e.g., a minimal OpenAPI YAML snippet in Phase 2, a curl example in Phase 4, or a `swagger-cli validate` command in Phase 7 — instead of abstract action bullets.

Insert validation checkpoints between phases with feedback loops (e.g., after Phase 2: validate the spec, fix errors, re-validate before writing the developer guide), and make the Quality Gates actionable by stating how to verify each one.

Tighten the repetitive phase scaffold by collapsing 'Skills to Invoke' and 'Copy-Paste Prompts' into one line per phase, or move per-phase detail into reference files to reduce the body's length.

Dimension	Reasoning	Score
Conciseness	The body is efficient with terse bullet lists and no explanation of concepts Claude already knows, but the seven-phase 'Skills to Invoke / Actions / Copy-Paste Prompts' scaffold repeats verbatim and words like 'comprehensive' pad without adding information.	4 / 5
Actionability	Actions such as 'Inventory endpoints', 'Define paths', and 'Configure security' are high-level hints with no commands, code, or examples; the copy-paste prompts are single-line skill invocations with no executable specifics, matching the anchor for minimal concrete guidance.	2 / 5
Workflow Clarity	The seven phases are clearly sequenced and a Quality Gates checklist exists, but the gates are end-of-workflow checkboxes with no validation steps or feedback loops between phases, so checkpoints are only implicit.	3 / 5
Progressive Disclosure	The body is well-organized with clear per-phase section headers, no bundle files exist or are needed, and there are no nested or buried references; the ~160 lines of repetitive phase scaffolding keep it just short of ideal organization.	4 / 5
	Total	13 / 20 Passed

Description

58%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 communicates a clear, specific capability set around API documentation and OpenAPI specs in third person, but it omits any 'when to use' trigger guidance and lacks common synonyms like Swagger or REST API. Adding an explicit 'Use when...' clause with natural trigger phrases would raise both completeness and trigger term quality.

Suggestions

Add an explicit 'Use when...' clause (e.g., 'Use when the user asks to document an API, generate an OpenAPI/Swagger spec, or write developer guides for endpoints').

Include natural trigger synonyms such as 'Swagger', 'REST API', 'API reference', and 'endpoint documentation' so the description matches how users actually phrase these requests.

Replace the circular phrase 'maintaining comprehensive API documentation' with a distinct concrete action (e.g., 'setting up interactive docs with Swagger UI/Redoc').

Dimension	Reasoning	Score
Specificity	Names the domain plus concrete actions ('generating OpenAPI specs', 'creating developer guides'), but 'maintaining comprehensive API documentation' is circular filler rather than a distinct capability, so coverage has minor gaps.	4 / 5
Completeness	The 'what' is clear and specific, but there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	'API documentation', 'OpenAPI specs', and 'developer guides' are natural terms, but common variations users would say — 'Swagger', 'REST API', 'API reference', 'endpoint docs' — are missing.	3 / 5
Distinctiveness Conflict Risk	API documentation with OpenAPI spec generation is a mostly distinct niche with only minor overlap risk against generic documentation skills; it is not fully distinct because the trigger phrasing alone doesn't disambiguate from general documentation work.	4 / 5
	Total	14 / 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/SKILL.md
Commit: c26b706

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