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.
45
16%
Does it follow best practices?
Impact
100%
1.00xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/api-documenter/SKILL.mdQuality
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 marketing-style language ('Master', 'AI-powered tools', 'modern developer experience practices') and completely lacks explicit trigger guidance for when Claude should select this skill. It would benefit from removing fluff and adding a clear 'Use when...' clause with natural user trigger terms.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API documentation, OpenAPI specs, Swagger files, SDK generation, or building developer portals.'
Replace vague phrases like 'Master API documentation' and 'AI-powered tools' with specific actions such as 'Write and validate OpenAPI 3.1 specifications, generate API reference pages, create client SDKs.'
Include common trigger term variations users would naturally say, such as 'swagger', 'REST API docs', 'API spec', 'API reference', '.yaml', or 'API endpoint documentation'.
| 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 any 'Use when...' clause or 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', 'API documentation', and 'interactive docs', but misses common user variations like 'swagger', 'REST API docs', 'API spec', 'API reference', or file extensions like '.yaml'/'.json'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of OpenAPI 3.1 and SDK generation provides some distinctiveness, but broad terms like 'API documentation', 'developer experience', and 'AI-powered tools' could overlap with general coding skills, documentation skills, or other API-related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
0%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, or executable guidance. The content would be far more effective if it were reduced to 20% of its current size and replaced the abstract bullet points with specific, working examples of OpenAPI specs, SDK generation commands, and documentation templates.
Suggestions
Replace the extensive capability bullet lists with 2-3 concrete, executable examples (e.g., a minimal OpenAPI 3.1 spec template, a command to generate an SDK, a validation workflow)
Add a clear multi-step workflow with validation checkpoints for common tasks like 'creating an OpenAPI spec from scratch' or 'generating SDK documentation'
Remove the 'Capabilities', 'Behavioral Traits', and 'Knowledge Base' sections entirely—these describe what Claude already knows and waste tokens
Split advanced topics (authentication docs, SDK generation, migration guides) into separate referenced files 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. | 1 / 3 |
Workflow Clarity | The 'Instructions' section has 4 extremely vague steps ('Identify target users', 'Create or validate specifications'). The 'Response Approach' section lists 8 abstract phases with no validation checkpoints, no error recovery, and no concrete sequencing. Neither constitutes a usable workflow. | 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%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
- sickn33/antigravity-awesome-skills
- Commit
d739c8b
- Reviewed
Table of Contents
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.