api-reference-documentation

Creates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples. Use when documenting REST APIs, creating SDK references, or building developer portals.

Quality

63%

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 ./plugins/api-reference-documentation/skills/api-reference-documentation/SKILL.md

Quality

Content

43%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 content is well-sectioned and free of conceptual padding, but it offers a template-plus-checklist rather than an executable, sequenced workflow for producing API documentation. Moving the full spec example to a reference file and adding concrete generation/verification steps would materially improve it.

Suggestions

Add a sequenced workflow with validation (e.g., 1. author/extend the OpenAPI spec, 2. render with `redocly build-docs` or Swagger UI, 3. validate the spec with `redocly lint`, 4. only publish when validation passes).

Replace the large inline e-commerce OpenAPI example with a minimal schema sketch and move the full example to a referenced file (e.g., examples/openapi-template.yaml).

Provide concrete, copy-pasteable commands for the listed tools (e.g., Swagger UI / Redoc / Stoplight) instead of only naming them.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining concepts Claude already knows, but the ~50-line inline e-commerce OpenAPI spec is substantial illustrative bulk that could be tightened into a minimal template.	3 / 5
Actionability	A concrete, usable OpenAPI YAML template is provided, but there are no executable commands or scripts for actually generating/rendering documentation—only a tool list and checklist.	3 / 5
Workflow Clarity	No sequenced workflow is present; a checklist and best-practices list imply order but lack defined steps and any validation checkpoints for producing and verifying the docs.	2 / 5
Progressive Disclosure	Sections are clearly organized, but the large inline OpenAPI spec is content that would be better placed in a separate reference file; no bundle files or external references exist.	3 / 5
	Total	11 / 20 Passed

Description

83%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 that clearly states capabilities and provides explicit, natural 'Use when' trigger guidance with concrete scenarios. It is specific and complete, with only minor room for additional synonyms and conflict-risk sharpening.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('Creates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples') naming the domain plus multiple specific capabilities, with only minor coverage gaps.	4 / 5
Completeness	Explicitly answers both what ('Creates professional API documentation using OpenAPI specifications...') and when ('Use when documenting REST APIs, creating SDK references, or building developer portals') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural trigger phrases are present ('documenting REST APIs', 'creating SDK references', 'building developer portals'), giving good keyword coverage, though common synonyms like 'Swagger' are missing.	4 / 5
Distinctiveness Conflict Risk	The OpenAPI/developer-portal niche is mostly distinct with specific triggers, with only minor overlap risk against general documentation skills.	4 / 5
	Total	17 / 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: secondsky/claude-skills
Path: plugins/api-reference-documentation/skills/api-reference-documentation/SKILL.md
Commit: ad16332

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