api-documentation

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

Quality

36%

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/antigravity-awesome-skills/skills/api-documentation/SKILL.md

Quality

Content

12%Scale 1-3

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

This skill is essentially a hollow template that lists phases and action items without providing any concrete, executable guidance. It references numerous other skills that don't exist in the bundle, making it impossible to actually follow. The repetitive structure across seven phases adds significant token cost without proportional value, and the complete absence of real code examples, spec snippets, or specific instructions makes it nearly useless as a skill document.

Suggestions

Add concrete, executable examples: include an actual OpenAPI spec snippet, real curl commands, and sample code in at least 2-3 languages to make the skill actionable.

Consolidate the seven phases into a concise workflow with specific validation steps (e.g., 'Run `swagger-cli validate openapi.yaml` to check spec validity') rather than vague action lists.

Either provide the referenced skills (api-documenter, openapi-spec-generation, etc.) as bundle files or remove the references and inline the essential guidance directly.

Replace the generic 'Copy-Paste Prompts' with actual templates or commands that produce concrete output, such as a starter OpenAPI YAML template or a documentation page scaffold.

Dimension	Reasoning	Score
Conciseness	The content is highly verbose and repetitive. Each phase follows an identical template structure with vague action items that add no real value. The 'Copy-Paste Prompts' sections are trivial one-liners that don't provide meaningful guidance. The entire skill could be condensed to a fraction of its size.	1 / 3
Actionability	The skill provides no concrete, executable guidance whatsoever. There are no actual code examples, no OpenAPI spec snippets, no curl commands, no real templates. Every action item is a vague directive like 'Create OpenAPI schema' or 'Configure security' without any specifics on how to do so. The 'Copy-Paste Prompts' just say 'Use @skill-name to do X' which is not actionable.	1 / 3
Workflow Clarity	The phases are sequenced logically (discovery → spec → guide → examples → interactive docs → site → maintenance), and there is a quality gates checklist. However, there are no validation checkpoints within phases, no feedback loops for error recovery, and no concrete criteria for when to move between phases.	2 / 3
Progressive Disclosure	The skill references many other skills (api-documenter, openapi-spec-generation, etc.) but none of these are provided in the bundle, and there are no links or file paths to actual supporting documents. The content is a monolithic wall of repetitive phase templates with no actual depth anywhere. References are unverifiable and appear to be placeholders.	1 / 3
	Total	5 / 12 Passed

Description

60%Scale 1-3

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 does a good job listing specific capabilities around API documentation, but it lacks an explicit 'Use when...' clause which limits its effectiveness for skill selection. Adding natural trigger terms and user-facing language variations would improve discoverability, and clarifying when to use this skill versus a general documentation skill would reduce conflict risk.

Suggestions

Add a 'Use when...' clause with explicit triggers, e.g., 'Use when the user asks about API docs, OpenAPI specs, Swagger files, REST API references, or endpoint documentation.'

Include common term variations users might say: 'Swagger', 'REST API', 'API reference', 'endpoint docs', '.yaml', '.json' spec files.

Differentiate from general documentation skills by specifying the unique scope, e.g., 'Focuses specifically on API-facing documentation rather than general technical writing or user guides.'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'generating OpenAPI specs', 'creating developer guides', and 'maintaining comprehensive API documentation'. These are distinct, actionable capabilities.	3 / 3
Completeness	Clearly answers 'what does this do' with specific actions, but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied by the domain context.	2 / 3
Trigger Term Quality	Includes relevant terms like 'OpenAPI specs', 'API documentation', and 'developer guides', but misses common user variations like 'Swagger', 'REST API docs', 'API reference', 'endpoints documentation', or file extensions like '.yaml'/'.json'.	2 / 3
Distinctiveness Conflict Risk	The focus on API documentation and OpenAPI specs provides some distinctiveness, but 'developer guides' and 'comprehensive API documentation' could overlap with general documentation or technical writing skills.	2 / 3
	Total	9 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: popey/claude-code-skills
Path: plugins/antigravity-awesome-skills/skills/api-documentation/SKILL.md
Commit: a5a6601

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