api-documentation

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

1.11x

Quality

38%

Does it follow best practices?

Impact

95%

1.11x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/antigravity-api-documentation/SKILL.md

Quality

Discovery

42%

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 effectively communicates specific capabilities around API documentation workflows with concrete actions. However, it critically lacks explicit trigger guidance ('Use when...') which would help Claude know when to select this skill. Adding natural user trigger terms and a clear 'when' clause would significantly improve skill selection accuracy.

Suggestions

Add a 'Use when...' clause with explicit triggers like 'Use when the user asks about API docs, Swagger files, OpenAPI specifications, or REST documentation'

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

Clarify the scope to reduce overlap with general documentation skills, e.g., specify 'REST/HTTP APIs' if applicable

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	Describes what the skill does but completely lacks a 'Use when...' clause or any explicit trigger guidance. Per rubric guidelines, missing explicit trigger guidance caps completeness at 2, and this has no 'when' component at all.	1 / 3
Trigger Term Quality	Includes relevant terms like 'API documentation', 'OpenAPI specs', and 'developer guides', but misses common variations users might say like 'Swagger', 'REST docs', 'API reference', or 'endpoint documentation'.	2 / 3
Distinctiveness Conflict Risk	The focus on API documentation and OpenAPI specs provides some specificity, but 'developer guides' and 'documentation' are broad enough to potentially overlap with general documentation or technical writing skills.	2 / 3
	Total	8 / 12 Passed

Implementation

35%

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

This skill provides a high-level workflow structure for API documentation but lacks the concrete, executable guidance needed to be actionable. It reads more like a table of contents or checklist than a skill that teaches Claude how to perform specific tasks. The repetitive phase structure adds bulk without adding value, and critical implementation details are absent.

Suggestions

Add concrete, executable examples for at least one phase - e.g., show actual OpenAPI YAML structure, specific curl commands, or real code snippets for SDK examples

Include validation checkpoints with specific criteria - e.g., 'Validate OpenAPI spec: `npx @redocly/cli lint openapi.yaml`' with expected output

Consolidate the repetitive phase structure - the identical format across 7 phases could be a template with phase-specific details only where they differ

Replace vague actions like 'Document request/response' with specific guidance such as 'For each endpoint, document: HTTP method, path, query params, request body schema, response codes with example payloads'

Dimension	Reasoning	Score
Conciseness	The content is moderately efficient but includes repetitive structure across phases (each phase follows identical format) and some unnecessary scaffolding. The 'Copy-Paste Prompts' sections are minimal but the overall document could be condensed significantly.	2 / 3
Actionability	The skill provides only vague, abstract guidance. Actions like 'Inventory endpoints' and 'Create OpenAPI schema' lack any concrete code, commands, or specific examples. The 'Copy-Paste Prompts' are just skill invocations, not executable instructions.	1 / 3
Workflow Clarity	Phases are clearly sequenced and the workflow structure is logical, but there are no validation checkpoints or feedback loops. No guidance on what to do if a phase fails or how to verify completion before proceeding.	2 / 3
Progressive Disclosure	The document references other skills appropriately but doesn't provide clear navigation to detailed materials. The structure is organized but the content that should be in referenced files (actual implementation details) is simply missing rather than properly linked.	2 / 3
	Total	7 / 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: boisenoise/skills-collections
Commit: 5c5ae21

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