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

92%

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

85%Weight 40%Scale 1-5

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

A dense, highly actionable, well-sequenced workflow with strong validation and feedback loops. The one structural defect is progressive disclosure: the body defers detail to companion files (runtime-contract.md, deprecated-patterns.md, templates/*) that are not present in the bundle, leaving the references as dead links.

Suggestions

Ship the 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) or inline the essential parts they cover so the signaled references resolve.

Tighten the longest paragraphs (notably the 'requires' / packageJsonUpdates gating block in section 2) by splitting dense multi-rule prose into a short bulleted list, preserving the exemplar citations but trimming repetition.

Consider moving the per-rule exemplar file-path citations into a single 'worked examples' reference file to reduce token load in the main SKILL.md while keeping them discoverable.

Dimension	Reasoning	Score
Conciseness	Remarkably information-dense with no padding of concepts Claude already knows (no 'what is Nx/migration' filler), every line actionable; however at ~48KB some passages (the long 'requires' paragraph, multiple inline exemplar citations) carry more than the minimum needed and could be trimmed without losing clarity.	4 / 5
Actionability	Fully executable guidance throughout: concrete code patterns ('export default async function update(tree: Tree)', 'applyChangesToString', 'forEachExecutorOptions'), exact commands ('npx nx run-many -t test,lint -p <plugin>', 'pnpm local-registry', 'npm adduser --registry http://localhost:4873'), and real exemplar file paths covering common cases.	5 / 5
Workflow Clarity	Clear 7-step sequence (Decompose → Version/gating → Scaffold → Implement → Test/validate → Docs → Pre-PR checklist) with explicit validation checkpoints in section 5, feedback loops ('If validation fails: fix and re-validate'), and a full pre-PR checklist in section 7 for error recovery.	5 / 5
Progressive Disclosure	Structure and signaling are good — a concise overview pointing one level deep to clearly named references ([runtime-contract.md], [deprecated-patterns.md], [templates/migrations-json.md], etc.) — but the actual bundle contains only scripts/compute-target-versions.mjs; every referenced companion .md and the templates/ directory are absent, so the signaled navigation is broken in practice.	3 / 5
	Total	17 / 20 Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An exemplar description: third-person imperative voice, concrete action list, explicit trigger conditions covering both human-asked and proactive-invoke cases, and a tightly scoped niche. No verbosity or over-claims.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions with full specificity: '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' plus 'porting an upstream framework's own migrations into Nx' — comprehensive coverage of the action surface.	5 / 5
Completeness	Explicitly answers both 'what' ('Author or scope a first-party Nx migration... Covers writing...') and 'when' ('Use whenever... and someone asks whether existing workspaces need a migration', 'Invoke BEFORE writing, fixing, or editing any migration') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural, audience-appropriate triggers with synonyms and file-shape terms: 'removes, renames, or deprecates an option/flag/executor/generator-schema field, changes a default, or bumps a dependency', 'nx migrate', 'migration prompt/runbook', 'packageJsonUpdates group' — comprehensive including variations.	5 / 5
Distinctiveness Conflict Risk	Narrow, well-defined niche ('first-party Nx migration', 'migrations.json', 'packageJsonUpdates', 'nx migrate') with distinct triggers unlikely to fire for unrelated skills.	5 / 5
	Total	20 / 20 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: 9064aa9

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