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
Quality
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 essentially a placeholder that provides almost no useful information for skill selection. It repeats the skill name as triggers, lacks any description of concrete capabilities, and provides no guidance on when Claude should select this skill. The description reads as auto-generated boilerplate rather than a thoughtful explanation of the skill's purpose.
Suggestions
Add specific actions the skill performs, e.g., 'Creates step-by-step migration guides for API version upgrades, database schema changes, and framework transitions. Documents breaking changes, provides code examples for updates, and generates compatibility matrices.'
Replace redundant triggers with natural user language: 'Use when users mention upgrading versions, breaking changes, deprecation notices, migration steps, upgrade paths, or transitioning between API versions.'
Specify the types of migrations covered to distinguish from other documentation skills, e.g., 'Focuses on software/API migrations rather than data migrations or infrastructure changes.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description only states 'Migration Guide Creator' without describing any concrete actions. It doesn't explain what the skill actually does - no verbs describing capabilities like 'generates', 'converts', 'documents steps', etc. | 1 / 3 |
Completeness | The description fails to answer 'what does this do' beyond the name, and provides no meaningful 'when to use' guidance. The 'Triggers on' section just repeats the skill name rather than describing actual use cases. | 1 / 3 |
Trigger Term Quality | The triggers listed are redundant ('migration guide creator' repeated twice) and represent the skill name rather than natural user language. Missing terms users would actually say like 'upgrade', 'version change', 'breaking changes', 'migration steps', 'upgrade path'. | 1 / 3 |
Distinctiveness Conflict Risk | While 'migration guide' is somewhat specific to a niche, the lack of detail about what kind of migrations (database, API, framework, version upgrades) means it could conflict with other documentation or migration-related 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 placeholder template with no actual content about migration guide creation. It consists entirely of generic boilerplate that could apply to any skill, providing zero actionable guidance, examples, or structure for the stated purpose. Claude would gain no useful information from this skill.
Suggestions
Add a concrete migration guide template with sections (overview, prerequisites, step-by-step migration steps, rollback procedures, validation checklist)
Include at least one complete example showing a before/after migration scenario with specific code or configuration changes
Define a clear workflow: 1) Assess current state, 2) Document breaking changes, 3) Write step-by-step instructions, 4) Add validation steps, 5) Include rollback procedures
Remove all generic boilerplate ('provides automated assistance', 'follows industry best practices') and replace with specific, actionable content about migration documentation
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is padded with generic boilerplate that explains nothing specific about migration guide creation. Phrases like 'provides automated assistance' and 'follows industry best practices' are filler that waste tokens without adding value. | 1 / 3 |
Actionability | No concrete guidance, code, commands, or examples are provided. The skill describes what it does in abstract terms but never shows how to actually create a migration guide - no templates, no structure, no executable content. | 1 / 3 |
Workflow Clarity | No workflow is defined. There are no steps for creating a migration guide, no validation checkpoints, and no process to follow. The 'Capabilities' section mentions 'step-by-step guidance' but provides none. | 1 / 3 |
Progressive Disclosure | The content is a flat, uninformative document with no references to detailed materials, no links to examples or templates, and no structured navigation to deeper content about migration guide creation. | 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
0c08951
- 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.