api-documentation

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

Quality

30%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Quality

Discovery

60%

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 workflows, making it clear what the skill does. However, it lacks an explicit 'Use when...' clause, which is critical for Claude to know when to select this skill. Adding natural trigger terms and variations (e.g., Swagger, REST docs) would improve discoverability.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API documentation, OpenAPI specs, Swagger files, or developer guides.'

Include common keyword variations users might say: 'Swagger', 'REST API docs', 'API reference', 'endpoint documentation', '.yaml spec'

Clarify boundaries to reduce overlap with general documentation skills, e.g., specify that this is for REST/HTTP API documentation specifically.

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, which caps this dimension at 2 per the rubric guidelines.	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', 'endpoint documentation', '.yaml', or 'API reference'.	2 / 3
Distinctiveness Conflict Risk	The focus on API documentation and OpenAPI specs provides some distinctiveness, but 'maintaining comprehensive API documentation' and 'creating developer guides' could overlap with general documentation or technical writing skills.	2 / 3
	Total	9 / 12 Passed

Implementation

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 vague action items without providing any concrete, actionable guidance. It references many external skills that don't exist in the bundle, making it entirely dependent on undefined resources. Every phase follows the same repetitive structure of vague bullet points and single-line 'prompts' that offer no real instruction.

Suggestions

Replace vague action items with concrete, executable examples — e.g., provide an actual minimal OpenAPI 3.0 spec template with paths, schemas, and security definitions that Claude can adapt.

Add real code examples for at least the most common tasks: a curl request example, a Python SDK example, and a complete OpenAPI YAML snippet.

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

Add explicit validation steps between phases — e.g., 'Validate OpenAPI spec with `npx @redocly/cli lint openapi.yaml` before proceeding to Phase 3' — to create meaningful quality gates.

Dimension	Reasoning	Score
Conciseness	Extremely verbose and repetitive. Each phase follows an identical template with vague action lists that add no real value. The 'Copy-Paste Prompts' are just 'Use @skill-name to do X' repeated seven times. Much of this content is padding that Claude already knows or could infer.	1 / 3
Actionability	No concrete, executable guidance anywhere. No actual OpenAPI spec examples, no real code snippets, no specific commands. Every action item is vague ('Create OpenAPI schema', 'Configure security', 'Choose platform') with no details on how to accomplish them. The 'Copy-Paste Prompts' just delegate to other skills without providing any actual instructions.	1 / 3
Workflow Clarity	While phases are listed sequentially, the steps within each phase are superficial bullet points with no real sequencing logic, no validation checkpoints between phases, and no error recovery. The 'Quality Gates' checklist at the end is disconnected from the workflow and lacks any verification mechanism.	1 / 3
Progressive Disclosure	References numerous other skills (@api-documenter, @openapi-spec-generation, etc.) but none of these are provided in the bundle. No actual supporting files exist. The skill is a monolithic document that is simultaneously too long (repetitive structure) and too shallow (no real content at any level).	1 / 3
	Total	4 / 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: cfced3a

Reviewed: about 12 hours 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.