api-documentation
Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.
86
82%
Does it follow best practices?
Impact
94%
1.28xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-crafted skill description that excels across all dimensions. It provides specific capabilities, includes natural trigger terms developers would use, explicitly states both what it does and when to use it, and carves out a distinct niche in API documentation that won't conflict with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'documenting REST APIs, GraphQL schemas, SDK methods' and 'Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides' - these are specific, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers both what ('Create comprehensive API documentation', 'Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides') AND when ('Use when documenting REST APIs, GraphQL schemas, or SDK methods') with explicit triggers. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'API documentation', 'REST APIs', 'GraphQL', 'SDK', 'OpenAPI', 'Swagger', 'API reference' - these are all terms developers naturally use when seeking this type of help. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on API documentation with distinct triggers like 'REST APIs', 'GraphQL schemas', 'OpenAPI/Swagger' that are unlikely to conflict with general documentation or coding skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides highly actionable, executable examples for API documentation including OpenAPI specs, code annotations, and interactive docs setup. However, it's verbose with a lengthy inline OpenAPI example that could be referenced externally, lacks validation steps for verifying documentation accuracy, and contains placeholder content in the Examples section that adds no value.
Suggestions
Add validation steps: include commands to validate OpenAPI specs (e.g., `npx @redocly/cli lint openapi.yaml`) and verify docs match actual API responses
Move the full OpenAPI spec example to a referenced file and keep only essential patterns inline to improve conciseness
Remove or complete the empty Examples section at the end - placeholder content wastes tokens
Remove the Metadata section (version, tags, compatible platforms) as it adds no actionable value for Claude
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill provides substantial content but is verbose in places. The full OpenAPI spec example is comprehensive but could be trimmed to essential patterns. The metadata section at the end adds unnecessary tokens (version, tags, platform compatibility). | 2 / 3 |
Actionability | Excellent executable examples throughout: complete OpenAPI YAML spec, working TypeScript/Express code with JSDoc, Swagger UI setup code, and curl commands with request/response examples. All code is copy-paste ready. | 3 / 3 |
Workflow Clarity | Steps 1-4 provide a logical sequence for creating API documentation, but there are no validation checkpoints. Missing guidance on how to verify the OpenAPI spec is valid, or how to test that generated docs match actual API behavior. | 2 / 3 |
Progressive Disclosure | The output format section shows good file structure organization, and references to external tools are provided. However, the skill itself is monolithic with a very long OpenAPI example inline. The Examples section at the end is empty placeholder content, suggesting incomplete structure. | 2 / 3 |
Total | 9 / 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 | |
- Repository
- supercent-io/skills-template
- Commit
c033769
- 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.