next-upgrade

Upgrade Next.js to the latest version following official migration guides and codemods

1.25x

Quality

53%

Does it follow best practices?

Impact

93%

1.25x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/next-upgrade/SKILL.md

Quality

Content

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

Description

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

Validation

90%

Warnings & errors only

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: about 1 month ago

Table of Contents

Discovery Implementation Validation

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.