author-migration

Author or scope a first-party Nx migration. Use whenever code removes, renames, or deprecates an option/flag/executor/generator-schema field, changes a default, or bumps a dependency, and someone asks whether existing workspaces need a migration so they don't break on `nx migrate`/upgrade. Covers writing the colocated update-VER/NAME.{ts,spec.ts,md} set, the migrations.json entry (version, requires, implementation, prompt, documentation) or packageJsonUpdates group, and the AI-agent prompt/runbook .md for prompt-only or hybrid (generator + prompt) migrations. Also covers porting an upstream framework's own migrations into Nx. Invoke BEFORE writing, fixing, or editing any migration, migration prompt/runbook, or packageJsonUpdates group, and before concluding a breaking change needs no migration at all.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable and well-sequenced with strong validation checkpoints, but it is overly dense for its length and its progressive-disclosure structure is only promised, not delivered: every referenced companion file is absent from the bundle.

Suggestions

Add the missing companion files (runtime-contract.md, deprecated-patterns.md, and templates/migrations-json.md, templates/spec-skeleton.md, templates/prompt-runbook.md, templates/documentation-md.md) so the signaled progressive disclosure is real, or remove the dangling references and inline only what SKILL.md needs.

Move the large treatment-classification table and the dense gating rules (section 2 `requires`/packageJsonUpdates) into runtime-contract.md / templates/ to make SKILL.md a leaner overview.

Break the long multi-clause sentences in sections 2 and 4 into short bulleted rules so the dense operational guidance is scannable instead of a wall of text.

Dimension	Reasoning	Score
Conciseness	It avoids explaining concepts Claude already knows and is information-dense, but the 217-line body is a wall of very long multi-clause sentences (e.g. the `requires`/gating rules in section 2) and frequent parenthetical exemplar citations that could be tightened into scannable bullets.	2 / 3
Actionability	Fully concrete guidance: real commands ("node .claude/skills/author-migration/scripts/compute-target-versions.mjs", "npx nx run-many -t test,lint -p <plugin>", "pnpm nx-release <next-prerelease> --local"), named APIs (forEachExecutorOptions, applyChangesToString, readNxJson), exact file-path conventions, and copy-from exemplar files.	3 / 3
Workflow Clarity	A clear seven-step sequence (Decompose → Version/gating → Scaffold → Implement → Test → Docs → Pre-PR checklist) with explicit validation commands in section 5, feedback loops (re-validate, re-stamp version, fix-and-re-run), and a literal pre-PR checklist.	3 / 3
Progressive Disclosure	References are well-signaled and one level deep, but the six referenced companion files (runtime-contract.md, deprecated-patterns.md, templates/migrations-json.md, templates/spec-skeleton.md, templates/prompt-runbook.md, templates/documentation-md.md) do not exist in the bundle, so the content those files should hold is crammed inline and the references dangle.	2 / 3
	Total	10 / 12 Passed

Description

100%

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 is excellent: concrete actions, natural trigger terms, explicit what-and-when guidance, and a distinct niche. It is concise despite its specificity and uses correct third-person voice throughout.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Author or scope a first-party Nx migration", "writing the colocated update-VER/NAME.{ts,spec.ts,md} set, the migrations.json entry (version, requires, implementation, prompt, documentation) or packageJsonUpdates group", and "porting an upstream framework's own migrations into Nx" — not vague language.	3 / 3
Completeness	Explicitly answers both what (author/scope a migration; the file set, migrations.json entry, packageJsonUpdates group, prompt runbook) and when ("Use whenever code removes, renames, or deprecates..." and "Invoke BEFORE writing, fixing, or editing any migration...").	3 / 3
Trigger Term Quality	Good coverage of natural terms a developer would say: "migration", "nx migrate", "upgrade", "removes, renames, or deprecates an option/flag", "bumps a dependency", "breaking change".	3 / 3
Distinctiveness Conflict Risk	A clear niche — first-party Nx migration authoring — with highly specific triggers unlikely to fire for any other skill.	3 / 3
	Total	12 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
relative_links	Relative link issues: 12 missing, 1 suspicious	Warning

	Total	14 / 16 Passed

Repository: nrwl/nx
Path: .claude/skills/author-migration/SKILL.md
Commit: 0abf7a4

Reviewed: 4 days 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.