jbvc/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. Use PROACTIVELY for API documentation or developer portal creation.
46
46%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
67%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 covers both what the skill does and when to use it, which is good for completeness. However, it relies on buzzwordy language ('Master,' 'AI-powered tools,' 'modern developer experience practices') that adds fluff without specificity. The trigger terms are reasonable but miss common user vocabulary variations like 'Swagger,' 'REST API docs,' or 'API spec.'
Suggestions
Replace vague phrases like 'Master API documentation,' 'AI-powered tools,' and 'modern developer experience practices' with concrete actions (e.g., 'Generates OpenAPI 3.1 specifications, creates interactive API reference pages, produces client SDKs').
Add common trigger term variations users would naturally say, such as 'Swagger,' 'REST API docs,' 'API spec,' 'API reference,' '.yaml spec,' or '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/buzzwordy phrases like 'Master API documentation,' 'AI-powered tools,' and 'modern developer experience practices' that don't describe concrete actions. | 2 / 3 |
Completeness | Answers both 'what' (create interactive docs, generate SDKs, build developer portals with OpenAPI 3.1) and 'when' ('Use PROACTIVELY for API documentation or developer portal creation'), providing an explicit trigger clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'API documentation,' 'OpenAPI 3.1,' 'SDKs,' and 'developer portals,' but misses common user variations like 'Swagger,' 'REST API docs,' 'API reference,' 'API spec,' or '.yaml/.json spec files.' The term 'AI-powered tools' is generic and not a natural trigger. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on OpenAPI 3.1 and developer portals provides some distinctiveness, but broad terms like 'API documentation' and 'AI-powered tools' could overlap with general documentation skills or other API-related skills. The mention of SDK generation helps differentiate somewhat. | 2 / 3 |
Total | 9 / 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 persona description and capability inventory rather than actionable documentation. It contains no executable code, no concrete examples, no specific tool commands, and no real workflow guidance. The vast majority of content enumerates topics and concepts Claude already knows, making it extremely token-inefficient while providing almost no practical value for task execution.
Suggestions
Replace the extensive capability/knowledge/behavioral trait lists with 2-3 concrete, executable examples (e.g., a complete OpenAPI 3.1 spec snippet, a specific SDK generation command, a Redoc configuration example).
Add a concrete multi-step workflow with validation checkpoints, such as: write spec → validate with spectral lint → generate docs → test examples → deploy, with actual commands at each step.
Remove sections that describe what Claude already knows (Capabilities, Knowledge Base, Behavioral Traits) and replace with specific patterns, gotchas, or project-specific conventions that add genuine value.
Either add references to detailed sub-documents for advanced topics (e.g., 'See AUTH_DOCS.md for OAuth flow documentation patterns') or dramatically reduce scope to a focused, actionable skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose with extensive lists of capabilities, behavioral traits, and knowledge base items that Claude already knows. The bulk of the content is taxonomic enumeration of topics rather than actionable instruction. Sections like 'Capabilities', 'Behavioral Traits', and 'Knowledge Base' are essentially restating general knowledge Claude possesses, wasting significant token budget. | 1 / 3 |
Actionability | Contains zero concrete code examples, no executable commands, no specific tool invocations, and no copy-paste ready content. The 'Instructions' section is four vague bullet points. Everything is described at an abstract level ('Create or validate specifications with examples and auth flows') without showing how to actually do anything. | 1 / 3 |
Workflow Clarity | The four-step 'Instructions' workflow is extremely high-level and lacks any validation checkpoints, error recovery steps, or concrete sequencing. The 'Response Approach' section lists 8 abstract steps but none include specific validation or feedback loops. For a skill involving spec authoring and SDK generation, the absence of any concrete workflow with checkpoints is a significant gap. | 1 / 3 |
Progressive Disclosure | The content is a monolithic wall of bullet-point lists with no references to external files, no links to detailed guides, and no clear separation between overview and detailed content. All content is inline and poorly organized — extensive capability lists that should either be removed or split into referenced documents are dumped into the main skill file. | 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 |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents