migration-guide-creator
Migration Guide Creator - Auto-activating skill for Technical Documentation. Triggers on: migration guide creator, migration guide creator Part of the Technical Documentation skill category.
33
3%
Does it follow best practices?
Impact
81%
0.97xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./planned-skills/generated/17-technical-docs/migration-guide-creator/SKILL.mdQuality
Discovery
7%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 description is extremely thin and formulaic, consisting only of a title, a duplicated trigger phrase, and a category label. It provides no concrete actions, no natural trigger terms users would actually say, and no explicit guidance on when Claude should select this skill. It would be nearly indistinguishable from a generic documentation skill in a multi-skill environment.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates step-by-step migration guides for API upgrades, framework version changes, and database schema migrations, including breaking change summaries and code transformation examples.'
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about migrating, upgrading, porting code, handling breaking changes, version upgrades, or creating migration documentation.'
Remove the duplicated trigger term and replace with diverse natural keywords users would actually say, such as 'migrate', 'upgrade guide', 'breaking changes', 'version migration', 'porting', 'deprecation'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain ('migration guide creator') but provides no concrete actions. It does not describe what the skill actually does—no mention of specific tasks like 'generates step-by-step migration instructions', 'compares API versions', or 'creates upgrade checklists'. | 1 / 3 |
Completeness | The description fails to answer both 'what does this do' and 'when should Claude use it'. There is no explanation of capabilities and no explicit 'Use when...' clause—only a redundant trigger phrase and a category label. | 1 / 3 |
Trigger Term Quality | The only trigger terms listed are 'migration guide creator' repeated twice, which is not a natural phrase users would say. Missing natural terms like 'migrate', 'upgrade', 'breaking changes', 'version upgrade', 'porting', 'migration steps', etc. | 1 / 3 |
Distinctiveness Conflict Risk | The term 'migration guide' is somewhat specific to a niche (migration documentation), which provides some distinctiveness. However, the lack of concrete detail means it could overlap with general documentation or technical writing skills. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a hollow template with no actual content. It contains no actionable instructions, no examples, no code, and no domain-specific knowledge about creating migration guides. Every section restates the skill name without providing any substance, making it entirely useless as a skill definition.
Suggestions
Add concrete, actionable content: define what a migration guide should contain (e.g., breaking changes, step-by-step upgrade instructions, before/after code examples, rollback procedures) with specific templates or examples.
Include at least one executable workflow, e.g., '1. Identify breaking changes from changelog 2. Document each change with before/after code 3. Add migration steps 4. Validate all code examples compile/run'.
Provide a concrete example of a migration guide output (e.g., a sample section migrating from API v1 to v2) so Claude knows the expected format and quality.
Remove all boilerplate sections ('When to Use', 'Example Triggers', 'Capabilities') that just restate the skill name and replace them with actual technical content about migration guide creation patterns.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler and boilerplate. It explains nothing Claude doesn't already know, repeats the trigger phrase 'migration guide creator' excessively, and provides zero domain-specific information or instructions. | 1 / 3 |
Actionability | There is no concrete guidance, no executable code, no specific commands, no examples of migration guide content, and no actual instructions on how to create a migration guide. Every section is vague and abstract. | 1 / 3 |
Workflow Clarity | No workflow is defined at all. There are no steps, no sequence, no validation checkpoints—just generic claims like 'provides step-by-step guidance' without actually providing any. | 1 / 3 |
Progressive Disclosure | There is no meaningful structure or content to disclose. No references to supporting files, no layered organization, and no bundle files exist. The sections are superficial headings over empty content. | 1 / 3 |
Total | 4 / 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.