migrating-apis
Implement API migrations between versions, platforms, or frameworks with minimal downtime. Use when upgrading APIs between versions. Trigger with phrases like "migrate the API", "upgrade API version", or "migrate to new API".
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-migration-tool/skills/migrating-apis/SKILL.mdQuality
Discovery
82%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 competent description that clearly communicates its purpose and includes explicit trigger guidance. Its main weaknesses are a lack of specific concrete actions (what exactly does the migration entail?) and some potential overlap with other migration-related skills due to the broad scope of 'platforms or frameworks'. The trigger phrases are well-chosen and natural.
Suggestions
Add more specific concrete actions like 'updates endpoint signatures, transforms request/response schemas, handles breaking changes, generates adapter layers' to improve specificity.
Narrow the scope or add distinguishing details to reduce overlap with other migration skills (e.g., database migrations, framework migrations) — consider specifying 'REST API', 'GraphQL', or other API-specific terms.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API migrations) and some actions (migrations between versions, platforms, frameworks), but doesn't list specific concrete actions like 'update endpoint signatures', 'transform request/response schemas', or 'generate compatibility layers'. | 2 / 3 |
Completeness | Clearly answers both 'what' (implement API migrations between versions, platforms, or frameworks with minimal downtime) and 'when' (explicit 'Use when' clause and 'Trigger with phrases' providing concrete trigger guidance). | 3 / 3 |
Trigger Term Quality | Includes natural trigger phrases users would say: 'migrate the API', 'upgrade API version', 'migrate to new API', plus keywords like 'versions', 'platforms', 'frameworks'. Good coverage of how users would naturally phrase these requests. | 3 / 3 |
Distinctiveness Conflict Risk | Reasonably specific to API migrations, but 'migrate' and 'upgrade' could overlap with database migration skills, framework migration skills, or general code refactoring skills. The scope of 'platforms or frameworks' broadens it enough to risk conflicts. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a well-organized conceptual framework for API migration with good workflow sequencing and error categorization, but critically lacks actionable, executable content. The instructions read as a high-level project plan rather than concrete guidance Claude can execute—no code examples, no specific commands, no executable adapters or router configurations. The referenced bundle files don't exist, undermining the progressive disclosure structure.
Suggestions
Add executable code examples for at least the adapter transformation, traffic router middleware, and shadow comparison steps—even minimal working examples would dramatically improve actionability.
Include a concrete endpoint-mapping.json schema example showing the expected structure, so Claude knows exactly what format to produce.
Add explicit validation gates between workflow phases (e.g., 'Do NOT proceed to canary until shadow comparison shows <0.1% unexpected mismatches for 24 hours').
Either provide the referenced bundle files (implementation.md, errors.md, examples.md) or remove the references to avoid pointing to non-existent resources.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some unnecessary verbosity. The overview partially restates the instructions, the examples section describes scenarios without executable code, and the resources section lists general knowledge Claude already has. The error handling table adds value but could be tighter. | 2 / 3 |
Actionability | Despite listing 8 steps, the instructions are almost entirely abstract descriptions rather than concrete, executable guidance. There are no code snippets, no specific commands, no copy-paste-ready examples. Phrases like 'Create request/response adapters' and 'Implement a traffic router' describe what to do without showing how. | 1 / 3 |
Workflow Clarity | The 8-step workflow is clearly sequenced and the phased cutover (shadow -> canary -> ramp -> decommission) with rollback triggers is well-structured. However, explicit validation checkpoints are weak—step 5 mentions comparing outputs but doesn't specify how to gate progression, and the rollback trigger threshold is only mentioned as an example rather than a concrete check. | 2 / 3 |
Progressive Disclosure | The skill references three external files (implementation.md, errors.md, examples.md) which is good structure, but none of these bundle files actually exist. The main SKILL.md also contains substantial inline content (error table, examples) that partially duplicates what the references claim to cover, creating unclear boundaries between overview and detail. | 2 / 3 |
Total | 7 / 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.