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".
68
62%
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 reasonably well-structured description with explicit 'Use when' and 'Trigger with' clauses that clearly communicate when to activate the skill. Its main weakness is the lack of specific concrete actions beyond the general 'implement API migrations' — listing specific sub-tasks like endpoint mapping, deprecation handling, or schema migration would strengthen it. The scope is slightly broad ('platforms or frameworks') which could cause overlap with other migration-related skills.
Suggestions
Add specific concrete actions such as 'map deprecated endpoints to new versions, update authentication schemes, transform request/response schemas, generate migration scripts'
Narrow the scope or add more distinctive terms to reduce potential overlap with general code migration or framework upgrade skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API migrations) and some actions ('implement API migrations'), but doesn't list multiple specific concrete actions like generating migration scripts, updating endpoints, handling deprecations, or mapping schema changes. | 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 clear activation 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 natural language variations. | 3 / 3 |
Distinctiveness Conflict Risk | While 'API migration' is somewhat specific, the broad mention of 'platforms or frameworks' could overlap with general code migration or framework upgrade skills. The trigger terms help but the scope is still fairly wide. | 2 / 3 |
Total | 10 / 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.
This skill is well-organized with good progressive disclosure and a clear phased migration workflow, but critically lacks actionability—there are no executable code examples, concrete commands, or copy-paste-ready snippets anywhere in the content. The instructions read more like a project management checklist than a technical skill Claude can execute, describing what to do conceptually without showing how to do it concretely.
Suggestions
Add executable code examples for at least the adapter transformation and traffic routing steps—e.g., a concrete Express-to-FastAPI adapter function, an nginx routing config snippet, or a shadow comparison script.
Include a concrete endpoint-mapping.json schema example showing the expected structure with sample data, rather than just listing it as an output.
Integrate explicit validation checkpoints into the workflow (e.g., 'STOP: Verify shadow comparison shows <0.1% mismatch rate before proceeding to canary') to create proper feedback loops for this multi-step destructive operation.
Replace the narrative examples section with at least one worked example showing actual code transformations (e.g., an Express route handler and its FastAPI equivalent with the adapter code between them).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably structured but includes some unnecessary verbosity—the overview largely restates the description, the examples section describes scenarios without executable code, and the resources section lists general concepts Claude already knows. Some tightening is possible. | 2 / 3 |
Actionability | Despite listing 8 steps, the skill provides zero executable code, no concrete commands, no actual adapter implementations, and no copy-paste-ready snippets. Everything is described at a high conceptual level (e.g., 'create request/response adapters', 'implement a traffic router') without showing how. The examples section describes scenarios narratively rather than providing concrete implementations. | 1 / 3 |
Workflow Clarity | The 8-step workflow is clearly sequenced and the phased cutover (shadow → canary → ramp → decommission) with rollback triggers is well-articulated. However, validation checkpoints are implicit rather than explicit—there's no clear 'stop and verify before proceeding' gate between steps, and the feedback loop for error recovery is only partially addressed in the error handling table rather than integrated into the workflow. | 2 / 3 |
Progressive Disclosure | The skill appropriately keeps the main file as an overview and references external files for implementation details (`implementation.md`), error patterns (`errors.md`), and examples (`examples.md`). References are one level deep and clearly signaled. The output section clearly lists expected artifacts. | 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
3e83543
- 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.