api-documenter
tessl i github:sickn33/antigravity-awesome-skills --skill api-documenterMaster 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.
Validation
75%| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
metadata_version | 'metadata.version' is missing | Warning |
license_field | 'license' field is missing | Warning |
body_output_format | No obvious output/return/format terms detected; consider specifying expected outputs | Warning |
Total | 12 / 16 Passed | |
Implementation
13%This skill reads as a comprehensive capability manifest rather than actionable documentation. It extensively lists what an API documentation specialist should know and do, but provides zero concrete examples, code snippets, or executable guidance. The content would benefit from dramatic reduction and replacement of descriptive lists with actual working examples of OpenAPI specs, SDK generation commands, and documentation templates.
Suggestions
Replace the 'Capabilities' and 'Knowledge Base' sections with 2-3 concrete, executable examples (e.g., a minimal OpenAPI 3.1 spec template, a command to generate SDKs, a validation script)
Add actual code examples showing OpenAPI spec structure, authentication documentation patterns, and SDK generation commands that Claude can copy and adapt
Move detailed capability lists to a separate REFERENCE.md file and keep SKILL.md focused on quick-start workflows with validation checkpoints
Remove 'Behavioral Traits' and 'Example Interactions' sections entirely - these describe Claude's persona rather than providing actionable instructions
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose with extensive lists of capabilities, knowledge bases, and behavioral traits that Claude already knows. The content reads like a job description rather than actionable instructions, with significant padding that doesn't add operational value. | 1 / 3 |
Actionability | No concrete code examples, commands, or executable guidance anywhere. The entire skill describes what to do abstractly ('Create comprehensive specifications', 'Build interactive experiences') without showing how. Example interactions are prompts, not demonstrations of outputs. | 1 / 3 |
Workflow Clarity | The 'Instructions' and 'Response Approach' sections provide numbered steps, but they are high-level and lack validation checkpoints. No feedback loops for error recovery, no specific validation steps, and no concrete sequencing for complex multi-step processes like SDK generation or portal building. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files for detailed content. All capabilities are listed inline rather than organized into separate reference documents. No navigation structure or links to deeper materials for advanced topics. | 1 / 3 |
Total | 5 / 12 Passed |
Activation
67%The description adequately covers both what the skill does and when to use it, earning full marks for completeness. However, it relies on some vague buzzwords ('AI-powered tools', 'modern developer experience practices') and could benefit from more natural trigger terms that users would actually say. The distinctiveness is moderate but could be improved with more specific file types or tool names.
Suggestions
Replace vague phrases like 'AI-powered tools' and 'modern developer experience practices' with specific capabilities (e.g., 'validate schemas', 'mock API responses', 'generate client libraries')
Add common trigger term variations users would naturally say: 'swagger', 'API docs', 'REST documentation', '.yaml specs', 'API reference'
| 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 'AI-powered tools' and 'modern developer experience practices' are vague buzzwords that lack concrete specificity. | 2 / 3 |
Completeness | Clearly 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 explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'API documentation', 'OpenAPI', 'SDKs', 'developer portals', but misses common variations users might say such as 'swagger', 'API docs', 'API reference', 'REST documentation', or file extensions like '.yaml', '.json'. | 2 / 3 |
Distinctiveness Conflict Risk | The OpenAPI 3.1 and SDK generation aspects provide some distinctiveness, but 'API documentation' is broad enough to potentially overlap with general documentation skills or code generation skills. | 2 / 3 |
Total | 9 / 12 Passed |
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.