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.

1.00x

Quality

16%

Does it follow best practices?

Impact

100%

1.00x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/antigravity-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 lists some concrete outputs (interactive docs, SDKs, developer portals), but suffers from vague buzzwords ('AI-powered tools', 'modern developer experience practices', 'Master') and completely lacks explicit trigger guidance. It would benefit significantly from a 'Use when...' clause and more natural user-facing keywords.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API documentation, OpenAPI/Swagger specs, generating API references, or building developer portals.'

Replace vague phrases like 'AI-powered tools' and 'modern developer experience practices' with specific capabilities such as 'validate OpenAPI specs, generate client SDKs in multiple languages, create API reference pages.'

Include common keyword variations users would naturally say: 'Swagger', 'REST API docs', 'API spec', 'API reference', '.yaml spec files'.

Dimension	Reasoning	Score
Specificity	Names the domain (API documentation) and lists some actions like 'Create interactive docs, generate SDKs, and build comprehensive developer portals,' but also includes vague phrases like 'Master API documentation' and 'modern developer experience practices' which are more aspirational than concrete.	2 / 3
Completeness	Describes what it does (create docs, generate SDKs, build portals) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also somewhat vague, so this scores a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'OpenAPI 3.1', 'SDKs', 'developer portals', and 'API documentation', but misses common user variations like 'Swagger', 'REST API docs', 'API reference', 'API spec', or '.yaml/.json spec files'. 'AI-powered tools' is vague and unlikely to be a natural trigger.	2 / 3
Distinctiveness Conflict Risk	The mention of OpenAPI 3.1 and SDK generation provides some distinctiveness, but 'API documentation' and 'developer portals' are broad enough to overlap with general documentation skills or web development skills. 'AI-powered tools' adds confusion about scope.	2 / 3
	Total	7 / 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 capability catalog or persona description rather than actionable documentation. It lists dozens of topics Claude should know about but provides zero concrete examples, code snippets, commands, or specific workflows. The content would be almost entirely ineffective as a skill because it adds no knowledge Claude doesn't already have while consuming significant token budget.

Suggestions

Replace the extensive capability lists with 2-3 concrete, executable examples (e.g., a complete OpenAPI 3.1 spec snippet, a specific SDK generation command, a Redoc configuration)

Add a clear multi-step workflow with validation checkpoints for the most common task (e.g., creating an OpenAPI spec: write → validate with spectral → generate docs → test examples)

Remove the 'Capabilities', 'Behavioral Traits', and 'Knowledge Base' sections entirely—these describe things Claude already knows and waste tokens

Split detailed guidance into referenced files (e.g., OPENAPI_PATTERNS.md, SDK_GENERATION.md, AUTH_DOCS.md) and keep SKILL.md as a concise overview with links

Dimension	Reasoning	Score
Conciseness	Extremely verbose with extensive lists of capabilities, behavioral traits, and knowledge base items that Claude already knows. The content reads like a resume or marketing brochure rather than actionable instructions. Most of the 150+ bullet points describe general concepts Claude is already familiar with.	1 / 3
Actionability	No concrete code examples, no executable commands, no specific tool configurations, no copy-paste ready snippets. Everything is described at an abstract level ('OpenAPI 3.1+ specification authoring with advanced features') without showing how to actually do anything. The 'Instructions' section is four vague bullet points.	1 / 3
Workflow Clarity	The four-step 'Instructions' section is extremely vague ('Create or validate specifications with examples and auth flows') with no validation checkpoints, no error recovery, and no concrete sequencing. The 'Response Approach' section is similarly abstract with no actionable detail.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files. All content is inline in one massive document with 10+ capability sections that could be split into focused reference files. No navigation aids or links to deeper resources.	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: 636b862

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