api-doc-generator

This skill should be used when the user asks to "generate API docs", "create API documentation", "generate curl examples", "create developer docs", or mentions generating documentation, curl examples, or developer guides from OpenAPI/OAS specifications.

Quality

66%

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 ./.claude/skills/api-doc-generator/SKILL.md

Quality

Content

67%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 skill body is well-structured and highly actionable, with concrete install/run commands and realistic examples that make it easy to execute. The chief weakness is conciseness, as several sections explain outcomes Claude could infer without added guidance.

Suggestions

Trim or remove the 'Organizing Documentation' and 'Using with Claude' sections, whose contents Claude can readily infer, to tighten token efficiency.

Add a brief verification checkpoint after generation (e.g., 'Confirm docs/README.md lists all endpoints and open one endpoint page to sanity-check the curl example') to lift workflow clarity.

If advanced configuration exists, link it with an explicit 'See X for advanced options' pointer rather than inlining all usage detail.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with useful executable commands and examples, but sections like 'Organizing Documentation', 'Each endpoint gets its own file...', and 'Using with Claude' restate obvious outcomes and add padding Claude could infer.	3 / 5
Actionability	Install and run commands are concrete and copy-paste ready with arguments, and a realistic output sample plus a generated curl example are provided, with only minor gaps around configuring base URLs or handling generation errors.	4 / 5
Workflow Clarity	This is an unambiguous single-action skill (run generate_docs.py spec.yaml [output-dir]) shown with multiple concrete examples; the destructive/batch cap does not apply since generation is read-only, but no output-verification checkpoint is shown, keeping it just below 5.	4 / 5
Progressive Disclosure	Content is well-organized into clear sections and the one bundle reference (scripts/generate_docs.py) is real and one level deep, but some inlinable guidance could be trimmed and there are no explicit 'see X for advanced' pointers to earn a 5.	4 / 5
	Total	15 / 20 Passed

Description

65%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 communicates a well-scoped niche and provides explicit, natural trigger phrases for when to invoke the skill. Its main weakness is specificity: it rephrases a single capability (generating API documentation) rather than enumerating multiple distinct concrete actions.

Suggestions

Lead with a concise capability statement that lists distinct actions (e.g., 'Generates multi-page markdown documentation with curl examples from OpenAPI/OAS specifications') before the trigger phrases, so 'what' is stated independently of 'when'.

Add a few more natural synonyms and file extensions (e.g., 'swagger', '.yaml', '.json') to broaden trigger coverage.

Tighten 'create developer docs' toward the specific OAS context to reduce overlap with generic documentation skills.

Dimension	Reasoning	Score
Specificity	The description names the domain (OpenAPI/OAS documentation) but only one real action—'generate API docs'—restated as synonymous trigger phrasings ('create API documentation', 'generate curl examples', 'create developer docs') rather than listing multiple distinct concrete actions.	2 / 5
Completeness	Both 'what' (generate API docs and curl examples from OpenAPI/OAS specs) and 'when' ('when the user asks to... or mentions...') are explicitly present with concrete trigger phrases, but the 'what' is conveyed largely through the trigger phrasing rather than a crisp standalone capability statement.	4 / 5
Trigger Term Quality	Strong natural-language trigger coverage including 'generate API docs', 'create API documentation', 'generate curl examples', and 'create developer docs' plus synonyms (docs/documentation, developer docs/guides) and the OpenAPI/OAS anchor, though a few terms like 'swagger' or file extensions are missing.	4 / 5
Distinctiveness Conflict Risk	The OpenAPI/OAS-to-markdown-docs niche is specific with distinct triggers and low conflict risk, though 'create developer docs' is moderately broad and could marginally overlap with general documentation skills.	4 / 5
	Total	14 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mulesoft/mulesoft-dx
Path: .claude/skills/api-doc-generator/SKILL.md
Commit: af20367

Reviewed: 1 day 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.