next-upgrade
Upgrade Next.js to the latest version following official migration guides and codemods
68
53%
Does it follow best practices?
Impact
93%
1.25xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/next-upgrade/SKILL.mdQuality
Discovery
57%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a clear, specific niche (Next.js upgrades) and mentions relevant tooling (codemods, migration guides), giving it good distinctiveness. However, it lacks an explicit 'Use when...' clause and could benefit from more specific concrete actions and additional trigger term variations that users might naturally use.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to update or upgrade their Next.js project to a newer version, mentions Next.js migration, or asks about breaking changes between Next.js versions.'
Include additional natural trigger terms users might say, such as 'update', 'migrate', 'version bump', 'breaking changes', or specific version transitions like 'Next.js 13 to 14'.
List more specific concrete actions, e.g., 'Runs official codemods, updates next.config.js, resolves breaking API changes, updates deprecated imports, and adjusts routing patterns.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Next.js upgrade) and mentions some actions (following migration guides, codemods), but doesn't list multiple specific concrete actions like updating config files, handling breaking changes, running specific codemods, etc. | 2 / 3 |
Completeness | Describes what it does (upgrade Next.js following migration guides and codemods) but lacks an explicit 'Use when...' clause specifying when Claude should select this skill. The 'when' is only implied. | 2 / 3 |
Trigger Term Quality | Includes relevant keywords like 'Next.js', 'upgrade', 'migration guides', and 'codemods', but misses common variations users might say such as 'update', 'migrate', 'version bump', 'breaking changes', or specific version numbers. | 2 / 3 |
Distinctiveness Conflict Risk | Clearly scoped to Next.js upgrades specifically, which is a distinct niche unlikely to conflict with other skills. The combination of 'Next.js', 'upgrade', 'migration guides', and 'codemods' creates a well-defined trigger space. | 3 / 3 |
Total | 9 / 12 Passed |
Implementation
50%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 reasonable framework for upgrading Next.js with concrete commands and a logical sequence, but it leans heavily on runtime fetching of external documentation rather than encoding specific actionable knowledge. The workflow lacks validation checkpoints and error recovery steps, which is a significant gap for a multi-step upgrade process that can easily break a project. The content is moderately concise but includes some filler that doesn't add value.
Suggestions
Add explicit validation checkpoints and error recovery: after running codemods, verify changes with `git diff`; after `npm run build`, specify how to diagnose and fix common errors; include a rollback strategy (e.g., 'commit before each step so you can revert').
Make the 'Review breaking changes' step more actionable by encoding the most common breaking changes per version rather than just saying 'check the guide'.
Add a feedback loop: if `npm run build` fails after upgrade, specify concrete debugging steps (check error output, re-run relevant codemods, consult specific sections of the migration guide).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient but includes some unnecessary explanation. Phrases like 'Detect current version' and 'Determine upgrade path' are somewhat obvious steps Claude would infer. The structure is reasonable but could be tightened—e.g., the 'Review breaking changes' bullet points are vague filler. | 2 / 3 |
Actionability | Provides concrete commands (npx codemod, npm install) and specific URLs, which is good. However, the codemod transforms listed are only for v15, guidance for other versions is vague ('adjust version as needed'), and the 'Review breaking changes' step is abstract rather than instructive. The skill relies heavily on fetching external docs at runtime rather than encoding actionable knowledge. | 2 / 3 |
Workflow Clarity | Steps are clearly sequenced and the incremental upgrade path advice is useful. However, there are no explicit validation checkpoints or feedback loops—step 8 says 'test the upgrade' but doesn't specify what to do if the build fails, how to roll back, or how to iterate. For a potentially destructive multi-step upgrade process, this gap is notable. | 2 / 3 |
Progressive Disclosure | The skill references external URLs for detailed migration guides, which is appropriate. However, with no bundle files and all content inline in a single file, there's no actual progressive disclosure structure. The content is reasonably organized with numbered steps but could benefit from separating version-specific details into referenced files. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- vercel-labs/next-skills
- Commit
dc1de9c
- 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.