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".
71
66%
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 skill description that clearly defines its domain and provides explicit trigger guidance. Its main weakness is that the capability descriptions lean slightly toward feature categories rather than concrete actions. The inclusion of both 'Use when' and 'Trigger with phrases' clauses is a strength that ensures good skill selection.
Suggestions
Make capabilities more concrete by specifying exact actions, e.g., 'Add version prefixes to API routes, generate deprecation response headers, create version migration guides' instead of abstract feature areas.
| 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 selection guidance). | 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 with distinct triggers. The combination of 'API versioning', 'backward compatibility', 'deprecation notices', and 'migration paths' creates a clear, specific domain unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is well-organized with good progressive disclosure and a clear structure, but critically lacks actionable, executable content. The instructions read like a project plan rather than concrete guidance Claude can follow — no code snippets, no specific commands, no executable examples. The workflow has a logical sequence but lacks validation checkpoints for what is essentially a multi-step, potentially breaking operation.
Suggestions
Add concrete, executable code examples for key steps — especially the version router middleware, compatibility layer transformation functions, and breaking change detector. Even one complete example for the version router would dramatically improve actionability.
Include a specific validation checkpoint after building the compatibility layer (e.g., 'Run v1 requests against the compatibility layer and diff responses against baseline before proceeding to step 7').
Replace the prose-based Examples section with actual input/output code showing a v1 request being transformed through the compatibility layer to produce the expected v1 response.
Trim the Prerequisites section — Claude doesn't need to be told it needs 'version control history' or a 'consumer notification channel'; focus prerequisites on specific tooling or configuration requirements.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably structured but includes some unnecessary explanation that Claude would already know (e.g., explaining what URL path versioning, header versioning, and query parameter versioning are). The prerequisites section lists things Claude can infer, and some instructions describe concepts rather than giving precise commands. | 2 / 3 |
Actionability | Despite listing 8 steps, the instructions are almost entirely descriptive rather than executable. There are no concrete code examples, no copy-paste ready snippets, no specific commands — just abstract directions like 'Create a version router' and 'Build a compatibility layer.' The examples section describes scenarios in prose without any actual code. | 1 / 3 |
Workflow Clarity | The 8 steps provide a reasonable sequence for the overall process, and the error handling table adds some validation awareness. However, there are no explicit validation checkpoints or feedback loops within the workflow — step 8 mentions tests but doesn't integrate a validate-fix-retry cycle, and there's no checkpoint after the compatibility layer is built to verify correctness before proceeding. | 2 / 3 |
Progressive Disclosure | The skill effectively uses progressive disclosure with clear references to external files (implementation.md, errors.md, examples.md) that are one level deep and well-signaled. The main content serves as an overview with appropriate pointers to detailed materials. | 3 / 3 |
Total | 8 / 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
70e9fa4
- 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.