CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

77%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 deep, expert-grade authoring guide that is maximally concrete and sequenced with genuine validation loops — actionability and workflow clarity are top-anchor. Its weaknesses are an over-stuffed body that inlines material its own companion files should carry, and a broken progressive-disclosure chain: nearly every referenced .md companion (runtime-contract.md, deprecated-patterns.md, the four templates) is missing from the skill bundle as provided, leaving only the compute-target-versions.mjs script resolvable.

Suggestions

Ship the referenced companion files in the bundle: runtime-contract.md (cited four times and declared mandatory pre-reading), deprecated-patterns.md, and templates/{migrations-json,spec-skeleton,prompt-runbook,documentation-md}.md are all absent, so most of the body's pointers dead-end.

Move reference-grade detail out of the body into those companions — e.g. the packageJsonUpdates source-major ladder semantics and its historical bug anecdotes in section 2 — to cut the ~12k-token always-loaded body and relieve the 60-80 word sentences.

Reduce duplication between the pre-PR checklist and sections 2/4/5 (the version-train, requires-fit, and spec-coverage rules each appear twice); have checklist items cite the section instead of restating its conditions.

DimensionReasoningScore

Conciseness

The body (~215 dense lines, ~12k tokens) contains no padding and explains nothing Claude already knows — every sentence carries repo-specific contracts — so it is well above the verbose anchors. But it goes beyond 'minor instances' of trimmable material: section 2 inlines reference-grade gating semantics (the multi-rung packageJsonUpdates ladder with historical bug anecdotes in 60-80 word single sentences), exemplar citations are nested parenthetically into nearly every bullet, and the pre-PR checklist restates the section 2/4/5 rules it references. Anchor 3 ('mostly efficient... could be tightened') fits better than anchor 4 because a substantial fraction of this belongs in the companion reference files the skill already ships rather than in the always-loaded body.

3 / 5

Actionability

Fully executable throughout: a decision table mapping every change type to its exact treatment, concrete file layouts, exact commands (`npx nx run-many -t test,lint -p <plugin>`, `NX_SKIP_PROVENANCE_CHECK=true npx nx migrate <version>`, the `pnpm nx-release <next-prerelease> --local` local-registry recipe), named devkit APIs (`addDependenciesToPackageJson`, `visitNotIgnoredFiles`, `jsonc-parser` modify/applyEdits), and per-rule exemplar file paths. This matches the 'fully executable; specific examples cover the common cases' anchor.

5 / 5

Workflow Clarity

A clearly sequenced seven-stage pipeline (decompose → version/gating → scaffold → implement → test/validate → docs → pre-PR checklist) with explicit validation checkpoints: mandatory negative/idempotency/malformed-input/multi-edit/precedence spec cases, the repo validators that "must pass", real-repo migration validation before release, and feedback loops for error recovery (fixing a shipped migration re-stamps its version so workspaces re-run it). The closing checklist enumerates the exact judgment residue no validator covers — squarely the top anchor.

5 / 5

Progressive Disclosure

Structure and signaling are strong — companion files are listed up front with when-to-read guidance, and references are one level deep. But scored against the actual bundle: of the referenced paths, only `scripts/compute-target-versions.mjs` exists. `runtime-contract.md` (cited four times, and the body says to read it "before wiring an entry"), `deprecated-patterns.md`, `templates/migrations-json.md`, `templates/spec-skeleton.md`, `templates/prompt-runbook.md`, and `templates/documentation-md.md` are all absent, so the disclosure chain the body depends on is broken for most references. That is more than the 'minor organization gaps' of anchor 4; it lands at anchor 3 despite otherwise good organization.

3 / 5

Total

16

/

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 exemplary description: concrete, comprehensive action list, explicit two-part trigger guidance stated twice (a 'Use whenever...' clause and an 'Invoke BEFORE...' clause), natural domain vocabulary, and a distinct niche with no realistic overlap. Voice is imperative/impersonal throughout, consistent with the guideline.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions with comprehensive coverage: "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", the "AI-agent prompt/runbook .md", and "porting an upstream framework's own migrations into Nx". It names the actual artifacts and keys, not generic categories, so it fits the 'lists multiple specific concrete actions; comprehensive coverage' anchor rather than the 'minor gaps' anchor below it.

5 / 5

Completeness

Both questions are answered explicitly and concretely: what — author or scope a first-party Nx migration covering the .ts/.spec/.md set, migrations.json entry, packageJsonUpdates group, and prompt runbook; when — "Use whenever code removes, renames, or deprecates... and someone asks whether existing workspaces need a migration" plus "Invoke BEFORE writing, fixing, or editing any migration... and before concluding a breaking change needs no migration at all". This matches the top anchor; the score-4 anchor's 'when could be more explicit' does not apply to a description with two explicit trigger clauses.

5 / 5

Trigger Term Quality

Natural trigger vocabulary is comprehensive, including synonyms and file extensions: "removes, renames, or deprecates an option/flag/executor/generator-schema field, changes a default, or bumps a dependency", "nx migrate/upgrade", "breaking change", "migration prompt/runbook", and the .ts/.spec.ts/.md file forms. These are exactly the phrases someone in the Nx repo would say when this skill is needed; the only conceivable additions (e.g. 'codemod', 'schematic') are jargon the body itself treats as non-canonical, so this is comprehensive rather than 'a few natural terms missing'.

5 / 5

Distinctiveness Conflict Risk

The niche is unambiguous — first-party Nx migrations for the Nx monorepo, identified by artifacts (migrations.json keys, packageJsonUpdates, update-VER/NAME files) no other skill domain shares. Trigger phrases like "whether existing workspaces need a migration so they don't break on nx migrate" would not fire a generic docs/code skill, so conflict risk is minimal and the top anchor fits.

5 / 5

Total

20

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

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

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.