versioning-apis
Implement API versioning with backward compatibility, deprecation notices, and migration paths. Use when managing API versions and backward compatibility. Trigger with phrases like "version the API", "manage API versions", or "handle API versioning".
65
58%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/api-development/api-versioning-manager/skills/versioning-apis/SKILL.mdQuality
Discovery
89%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 solid description that clearly communicates its purpose and provides explicit trigger guidance. Its main weakness is that the capability descriptions are somewhat high-level (listing feature areas rather than granular actions). The trigger terms and completeness are strong, making it easy for Claude to select this skill appropriately.
Suggestions
Make capabilities more concrete by listing specific actions, e.g., 'Add version prefixes to API routes, generate deprecation response headers, create version migration guides, and manage sunset timelines.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API versioning) and lists some actions (backward compatibility, deprecation notices, migration paths), but these are more like feature areas than concrete specific actions. It doesn't detail exactly what operations are performed (e.g., 'add version headers', 'generate deprecation warnings', 'create migration scripts'). | 2 / 3 |
Completeness | Clearly answers both 'what' (implement API versioning with backward compatibility, deprecation notices, and migration paths) and 'when' (explicit 'Use when' clause and 'Trigger with phrases' clause providing clear guidance on when to select this skill). | 3 / 3 |
Trigger Term Quality | Includes natural trigger phrases like 'version the API', 'manage API versions', 'handle API versioning', plus keywords like 'backward compatibility', 'deprecation notices', and 'migration paths'. These are terms users would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | API versioning is a well-defined niche that is unlikely to conflict with other skills. The specific triggers around 'version the API' and 'API versioning' are distinct and narrow enough to avoid overlap with general API design or other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a high-level design document than an actionable skill for Claude. It describes what to do at an architectural level but provides zero executable code, no concrete file contents, and references bundle files that don't exist. The workflow is sequenced but lacks validation checkpoints appropriate for a multi-step API restructuring task.
Suggestions
Add executable code examples for at least the version router middleware and compatibility layer transformation — these are the core actionable pieces Claude needs to implement.
Provide the referenced bundle files (implementation.md, errors.md, examples.md) or remove the references and inline the essential content.
Add explicit validation checkpoints between steps, such as 'Run the breaking change detector after step 4 to verify no unintended contract changes' and 'Execute compatibility tests after step 5 before proceeding.'
Replace the prose-based examples section with concrete before/after code showing the version router configuration and a compatibility layer transformation function.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some unnecessary verbosity. The prerequisites section explains things Claude would know (e.g., what Kong and AWS API Gateway are), and the examples section describes scenarios at a high level without providing executable code. The error handling table is useful but some entries over-explain obvious causes. | 2 / 3 |
Actionability | Despite listing 8 steps, the skill provides no executable code, no concrete commands, and no copy-paste-ready examples. Instructions like 'Create a version router' and 'Build a compatibility layer' are descriptive rather than instructive. The examples section describes scenarios in prose without any code. The referenced implementation.md is not provided in the bundle. | 1 / 3 |
Workflow Clarity | The 8 steps provide a reasonable sequence for the overall process, and step 8 mentions writing compatibility tests. However, there are no explicit validation checkpoints between steps, no feedback loops for error recovery during implementation, and no verification that each step succeeded before proceeding to the next. For a complex multi-step process involving breaking changes, this lacks sufficient guardrails. | 2 / 3 |
Progressive Disclosure | The skill references three external files (implementation.md, errors.md, examples.md) but none are provided in the bundle, making these dead references. The main content is a wall of descriptive text without the referenced supporting materials, so the progressive disclosure structure is broken — the overview promises depth that doesn't exist. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
3a2d27d
- 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.