dist-build-migration

Migrate an Nx package to build to a local dist/ directory with nodenext module resolution, exports map, and @nx/nx-source condition.

Quality

80%

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

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/dist-build-migration/SKILL.md

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.

An exceptionally actionable, well-sequenced migration runbook with strong validation and error-recovery loops. Its main structural weakness is that it is a monolithic 590-line SKILL.md with zero progressive disclosure — the optional 14b lockdown and the deep audit steps 15/15b/16 are prime candidates for separate reference files.

Suggestions

Split the optional 14b internal-lockdown procedure (roughly 200 lines, with its own steps 1-9) into a dedicated reference file (e.g. references/internal-lockdown.md) and keep a short decision summary inline pointing to it.

Move the detailed audit walkthroughs for steps 15, 15b, and 16 into a references/ file, keeping only the search command and the failure symptom in SKILL.md.

Trim the closing "output mailbox" analogy and consolidate the repeated why-explanations across steps 6, 7, and 11 into one shared rationale note.

Dimension	Reasoning	Score
Conciseness	The body is dense and almost entirely project-specific, non-obvious rationale (why preserveLocalDependencyProtocols breaks workspace:* publishing, why ESM import() ignores Module._initPaths) rather than concepts Claude already knows. Minor trimmable padding — the "output mailbox" analogy and some repeated rationale — keeps it below 5, but it is noticeably above the 3 anchor since the length is justified rather than padded.	4 / 5
Actionability	Exact before/after JSON and TypeScript snippets, exact pnpm nx and grep commands, concrete file paths, and error-message-to-fix mappings (e.g., TS2339 -> step 7) make the guidance copy-paste ready across all common cases. The few comment-only codemod blocks in 14b are explicitly justified as script sketches, not vague pseudocode.	5 / 5
Workflow Clarity	Steps 0-17 are explicitly sequenced with validation checkpoints (pnpm nx run-many -t test,build,lint; nx affected) and genuine feedback loops that map observed failures back to the responsible step ("If nx affected fails with 'Cannot find module @nx/<name>/internal', that's step 9"). The risky batch operations (workspace-wide codemod, release scripts) are covered by an explicit validation section.	5 / 5
Progressive Disclosure	There are no bundle files at all: the entire ~590-line procedure, including the ~200-line optional 14b lockdown deep dive, is inlined in SKILL.md. Section headers are clear (so not a 2), but substantial content that clearly belongs in separate reference files is inline with no one-level-deep references, matching the 3 anchor.	3 / 5
	Total	17 / 20 Passed

Description

70%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.

A highly specific, distinctive description with concrete technical terms, weakened only by the absence of any "Use when..." trigger guidance. Adding an explicit trigger clause would raise completeness without touching its other strengths.

Suggestions

Append a trigger clause such as "Use when migrating an Nx package's build output to a local dist/ layout, adding an exports map, or setting up the @nx/nx-source condition." to answer the "when" explicitly.

Include a couple of natural synonyms users might say, e.g. "local build output" or "package publish layout", to broaden trigger coverage.

Keep the description in third person and avoid adding fluff when extending it — the current length is well-judged.

Dimension	Reasoning	Score
Specificity	"Migrate an Nx package to build to a local dist/ directory with nodenext module resolution, exports map, and @nx/nx-source condition" names the domain and several concrete technical actions. It falls short of 5 because it describes a single migration action rather than comprehensive multi-action coverage, and exceeds 3 because it lists more than 1-2 concrete specifics.	4 / 5
Completeness	The description clearly answers "what" but contains no "Use when..." clause or equivalent explicit trigger guidance, which the rubric caps at 3. The "what" is concrete, so it is not a 2.	3 / 5
Trigger Term Quality	"Nx", "dist/", "build", "module resolution", and "exports map" are natural terms a maintainer would use when requesting this migration. A few natural synonyms (e.g., "local build", "publish layout") are missing, keeping it below the 5 anchor.	4 / 5
Distinctiveness Conflict Risk	"@nx/nx-source condition" and "nodenext module resolution" pin a very narrow Nx-monorepo niche; it is clearly distinguishable from other skills with minimal overlap risk.	5 / 5
	Total	16 / 20 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (591 lines); consider splitting into references/ and linking	Warning
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
referenced_paths_exist	Referenced path issues: 5 missing	Warning

	Total	13 / 16 Passed

Repository: nrwl/nx
Path: .claude/skills/dist-build-migration/SKILL.md
Commit: ab845a8

Reviewed: 9 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.