api-documentation
API documentation workflow for generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation.
38
36%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/antigravity-awesome-skills-claude/skills/api-documentation/SKILL.mdQuality
Discovery
60%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 does a good job listing specific capabilities around API documentation workflows, making it clear what the skill does. However, it lacks an explicit 'Use when...' clause, which is critical for Claude to know when to select this skill. Adding natural trigger terms and variations (e.g., Swagger, REST docs) would improve discoverability.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API documentation, OpenAPI specs, Swagger files, or developer guides.'
Include common trigger term variations such as 'Swagger', 'REST API docs', 'API reference', 'endpoint documentation', '.yaml spec', or 'API portal'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'generating OpenAPI specs', 'creating developer guides', and 'maintaining comprehensive API documentation'. These are distinct, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers 'what does this do' with specific actions, but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this dimension at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes relevant terms like 'OpenAPI specs', 'API documentation', and 'developer guides', but misses common user variations like 'Swagger', 'REST API docs', 'endpoint documentation', '.yaml', or 'API reference'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on API documentation and OpenAPI specs provides some distinctiveness, but 'maintaining comprehensive API documentation' and 'creating developer guides' could overlap with general documentation or technical writing skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
12%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 hollow skeleton that delegates all actual work to other skills without providing any concrete guidance itself. It contains no executable code, no real examples, no specific commands, and no substantive instructions—just vague action lists repeated across seven nearly identical phases. The content would need to be fundamentally rewritten to provide actual value.
Suggestions
Add concrete, executable examples for key tasks—e.g., a minimal OpenAPI spec YAML template, actual curl commands, or a real code snippet showing SDK usage patterns.
Collapse the seven repetitive phases into a concise workflow with specific validation checkpoints and feedback loops (e.g., 'validate OpenAPI spec with `swagger-cli validate spec.yaml`, fix errors before proceeding').
Remove the generic 'Copy-Paste Prompts' sections that just say 'Use @skill-name to do X'—either provide the actual prompts with specific parameters or remove them entirely.
Either provide the referenced bundle files (api-documenter, openapi-spec-generation, etc.) or inline the essential guidance directly in this skill so it's self-contained and actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose and repetitive. Each phase follows an identical template with vague action lists that add no real value. The 'Copy-Paste Prompts' sections are just one-liners telling Claude to invoke other skills. The entire document could be condensed to a fraction of its size. It also explains obvious concepts like what API documentation is. | 1 / 3 |
Actionability | No concrete, executable guidance anywhere. Actions are vague bullet points like 'Create OpenAPI schema' and 'Define paths' with no actual code, commands, schemas, or examples. The 'Copy-Paste Prompts' are just generic invocations of other skills with no substance. Nothing is copy-paste ready or executable. | 1 / 3 |
Workflow Clarity | The phases are clearly sequenced and the quality gates checklist provides some validation structure. However, there are no validation checkpoints within phases, no feedback loops for error recovery, and the steps within each phase are too vague to actually follow. The workflow reads more like a table of contents than actionable instructions. | 2 / 3 |
Progressive Disclosure | References numerous other skills (api-documenter, openapi-spec-generation, etc.) but none of these are provided in the bundle. There's no way to verify these exist or contain useful content. The skill itself is a monolithic wall of repetitive phase templates with no actual content split into supporting files. All the real knowledge is deferred to non-existent references. | 1 / 3 |
Total | 5 / 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
b3869ba
- 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.