api-documenter

Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals.

Quality

33%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agent/skills/api-documenter/SKILL.md

Quality

Discovery

32%

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 identifies a clear domain (API documentation with OpenAPI) and mentions several capabilities, but relies on vague marketing language ('Master', 'AI-powered tools', 'modern practices') rather than concrete actions. The critical missing element is any explicit trigger guidance telling Claude when to select this skill, which significantly limits its utility in a multi-skill environment.

Suggestions

Add an explicit 'Use when...' clause with trigger terms like 'OpenAPI', 'swagger', 'API spec', 'API reference', 'REST documentation', or 'SDK generation'

Replace vague phrases like 'Master' and 'AI-powered tools' with specific actions such as 'validate OpenAPI specs', 'generate client libraries', 'create endpoint documentation'

Include common file extensions and format variations users might mention: '.yaml', '.json', 'swagger.json', 'openapi.yaml'

Dimension	Reasoning	Score
Specificity	Names the domain (API documentation, OpenAPI 3.1) and lists some actions (create interactive docs, generate SDKs, build developer portals), but 'Master' and 'AI-powered tools' are vague buzzwords that don't describe concrete capabilities.	2 / 3
Completeness	Describes what it does (albeit vaguely) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'OpenAPI 3.1', 'API documentation', 'SDKs', 'developer portals', but misses common variations users might say like 'swagger', 'API spec', 'REST docs', 'API reference'.	2 / 3
Distinctiveness Conflict Risk	OpenAPI 3.1 and SDK generation provide some distinctiveness, but 'API documentation' and 'developer experience practices' are broad enough to potentially overlap with general documentation or coding skills.	2 / 3
	Total	7 / 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 reads more like a high-level best practices overview than actionable guidance for Claude. It lacks concrete examples, executable code, and specific templates that would make it immediately useful. The workflow section hints at a process but doesn't provide enough detail for reliable execution.

Suggestions

Add concrete, executable examples: show a complete OpenAPI 3.1 snippet, a real SDK generation command with flags, and example JSON responses

Replace vague instructions like 'Use standard templates' with actual template references or inline examples

Add validation checkpoints to the workflow: what does success look like after each step? How to verify the generated docs are correct?

Either link to external reference files for detailed content (schemas, templates, examples) or include them inline

Dimension	Reasoning	Score
Conciseness	The content is reasonably efficient but includes some unnecessary framing ('You are a Senior Technical Writer...', 'documentation that isn't just a reference, but a delight'). The bullet points are mostly lean but could be tighter.	2 / 3
Actionability	The content is almost entirely abstract guidance ('Use JSON Schema', 'Provide realistic examples', 'Write How-to guides') with no concrete code examples, templates, or executable commands beyond one validator script invocation. It describes what to do rather than showing how.	1 / 3
Workflow Clarity	The Execution Protocol provides a 4-step sequence, but steps 2-4 are vague ('Use standard templates', 'Audit the documentation', 'Publish to the developer portal') with no validation checkpoints or error recovery guidance.	2 / 3
Progressive Disclosure	The internal menu provides structure and the content is organized into sections, but there are no references to external files for detailed content. Everything is inline at a high level without clear pointers to deeper resources.	2 / 3
	Total	7 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: Dokhacgiakhoa/antigravity-ide
Commit: 3395991

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