CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

64

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

75%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.

A highly actionable, well-structured body: the single-command workflow is executable end-to-end with realistic example output. The main cost is redundancy — several sections restate frontmatter triggers or inferable uses, spending tokens without adding guidance.

Suggestions

Drop or merge 'When to Use This Skill' and 'Using with Claude' into a single line (or rely on the frontmatter description) — they duplicate trigger phrases already in the description.

Trim 'Organizing Documentation' to one or two lines; the bullet list of uses for generated files is inferable.

Add one line on handling invalid specs (e.g., pointing to the api-spec-validator skill before generating) to close the workflow validation gap.

DimensionReasoningScore

Conciseness

The core sections (Prerequisites, Running, What Gets Generated, Example) are lean, but 'When to Use This Skill' and 'Using with Claude' restate trigger phrases the frontmatter description already covers, and 'Organizing Documentation' explains uses Claude could infer — matching the 'mostly efficient but includes some unnecessary explanation' anchor.

3 / 5

Actionability

Fully executable, copy-paste ready guidance: 'pip install pyyaml', 'python3 skills/api-doc-generator/scripts/generate_docs.py path/to/spec.yaml [output-dir]', a worked example with realistic output, and a concrete sample curl command — matching the top anchor.

5 / 5

Workflow Clarity

The sequence is clear (install prerequisite, run command with stated default output dir, inspect the shown output) and unambiguous, but there is no guidance on what happens with an invalid spec (validation is only delegated to a related skill) or how to verify results — anchor 4, not 5.

4 / 5

Progressive Disclosure

Well-organized headers with a correctly resolvable script reference (scripts/generate_docs.py exists in the bundle) and no buried or nested references; minor organization gaps (the Curl Examples detail and Organizing sections could be trimmed or split) keep it at anchor 4 rather than 5.

4 / 5

Total

16

/

20

Passed

Description

78%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.

A strong description with explicit, natural trigger phrases and a clearly bounded OpenAPI/OAS niche. Its main weakness is that it is structured entirely as a 'when' clause — the capability statement (what output it produces) is only implied by the embedded action phrases.

Suggestions

Lead with a standalone third-person capability statement (e.g., 'Generates markdown documentation pages with curl examples from OpenAPI/OAS specifications') before the 'use when' clause, so the 'what' is explicit rather than embedded in triggers.

Add missing natural synonyms such as 'Swagger', 'OpenAPI spec', 'API reference', or file extensions like '.yaml'/.json' to broaden trigger coverage.

DimensionReasoningScore

Specificity

Quotes several concrete action phrases ("generate API docs", "create developer docs", "generate curl examples") anchored to a clear domain ("OpenAPI/OAS specifications"), but never states what the skill actually produces (markdown endpoint pages), so it falls short of comprehensive coverage at 5.

4 / 5

Completeness

The "when" is fully explicit ("This skill should be used when the user asks to...") and a "what" is present ("generating documentation, curl examples, or developer guides from OpenAPI/OAS specifications"), but the what is only embedded inside the when-clause rather than stated as a standalone capability, matching anchor 4 rather than 5.

4 / 5

Trigger Term Quality

Includes natural phrases users would say ("generate API docs", "create API documentation", "generate curl examples") plus domain terms ("OpenAPI/OAS"), but misses common synonyms like "Swagger", "API reference", or file extensions (.yaml/.json), keeping it below the comprehensive 5 anchor.

4 / 5

Distinctiveness Conflict Risk

The OpenAPI/OAS-to-documentation niche is clear with distinct quoted trigger phrases; only minimal overlap risk with generic documentation helpers, matching the 'clear niche with distinct triggers' anchor.

5 / 5

Total

17

/

20

Passed

Validation

100%

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

Revision

b8cef7d

Reviewed

Table of Contents

DiscoveryImplementationValidation

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.

Claim skill