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

16%

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 ./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 deliverables, but relies on buzzwords like 'AI-powered tools' and 'modern developer experience practices' without specificity. The biggest weakness is the complete absence of a 'Use when...' clause, making it unclear when Claude should select this skill over others. Adding explicit trigger conditions and more natural user keywords would significantly improve it.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API documentation, OpenAPI specs, Swagger files, 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 from .yaml/.json files'.

Include common trigger term variations users would naturally say: 'Swagger', 'REST API docs', 'API spec', 'API reference', '.yaml', '.json schema'.

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 'AI-powered tools' and 'modern developer experience practices' that are more buzzwords than concrete actions.	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, warranting a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'OpenAPI 3.1', 'API documentation', 'SDKs', and 'developer portals', but misses common user variations like 'Swagger', 'REST API docs', 'API spec', 'API reference', or '.yaml/.json spec files'.	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.	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 persona description or capability catalog rather than an actionable skill document. It contains no executable code, no concrete examples with inputs/outputs, no specific tool commands, and no real workflow guidance. The vast majority of content describes things Claude already knows (OAuth flows, OpenAPI specs, technical writing principles) without adding any novel, actionable instructions.

Suggestions

Replace the extensive capability bullet lists with 2-3 concrete, executable examples (e.g., a complete OpenAPI 3.1 spec snippet, a specific SDK generation command, a validation workflow with actual tool commands).

Add a concrete workflow with validation checkpoints, such as: 'Write spec → validate with `npx @redocly/cli lint spec.yaml` → generate docs with `npx redocly build-docs` → test examples with `npx @openapitools/openapi-generator-cli generate`'.

Remove the 'Capabilities', 'Behavioral Traits', and 'Knowledge Base' sections entirely — these describe what Claude already knows and waste tokens. Replace with specific patterns, templates, or code that Claude should follow.

Add at least one complete worked example showing input (e.g., a set of API endpoints) and expected output (e.g., a valid OpenAPI 3.1 YAML specification) to make the skill actionable.

Dimension	Reasoning	Score
Conciseness	Extremely verbose and padded with extensive lists of capabilities, behavioral traits, and knowledge base items that Claude already knows. The content reads like a marketing brochure or job description rather than actionable instructions. Massive sections like 'Capabilities' with 10+ subsections of bullet points add no executable value.	1 / 3
Actionability	No concrete code examples, commands, or executable guidance anywhere in the skill. Everything is abstract description — 'OpenAPI 3.1+ specification authoring with advanced features' tells Claude nothing it doesn't already know. The 'Instructions' section is four vague bullet points with no specifics. The 'Example Interactions' are just prompt suggestions, not worked examples with inputs and outputs.	1 / 3
Workflow Clarity	The four-step 'Instructions' section is extremely vague ('Create or validate specifications with examples and auth flows') with no concrete sequencing, validation checkpoints, or error recovery. The 'Response Approach' section lists 8 abstract steps but none include specific tools, commands, or validation criteria. No feedback loops or verification steps are present.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files and no bundle files to support it. All content is inline in a single massive document. The extensive capability lists could be split into reference files, but instead everything is dumped into one long skill file with poor information hierarchy.	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: 431bfad

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