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

72%

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

77%

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

The content is a highly actionable, well-sequenced migration runbook with strong validation and error-recovery loops, but it is very long and monolithic, with sizable optional sections that would benefit from extraction into reference files. Tightening the prose and splitting off the optional lock-down sub-procedure would improve token efficiency and navigation.

Suggestions

Extract the optional Step 14b lock-down sub-procedure (~200 lines) into a reference file (e.g. references/internal-lockdown.md) and leave a concise pointer plus the when-to-defer guidance inline, improving progressive_disclosure and conciseness.

Trim the analogy-driven 'Summary of the pattern' section and convert multi-paragraph 'Why' rationales into one-line justifications where the failure mode is already self-evident from the surrounding command.

Consider moving the long per-step gotcha deep-dives (e.g. Step 15/15b failure-mode explanations) into a separate 'common-failure-modes.md' reference, keeping the main steps as a lean checklist.

Dimension	Reasoning	Score
Conciseness	The ~590-line body is information-dense and avoids teaching basics Claude already knows, but it is very long and includes tighten-able prose such as the 'output mailbox' analogy summary and several explanatory rationales; not score 3 due to verbosity, not score 1 because there is no conceptual padding.	2 / 3
Actionability	Provides fully executable guidance — exact before/after JSON blocks, concrete bash/grep commands, copy-paste code snippets, specific file paths and line numbers (e.g. 'scripts/nx-release.ts:76') — matching the copy-paste-ready anchor.	3 / 3
Workflow Clarity	A clearly sequenced 17-step process with explicit validation checkpoints (Step 6 jq verification, Step 17 nx run-many/affected) and error-recovery feedback loops (the Step 14b Validation section maps specific failures to fixes); not score 2 because validation is explicit and frequent.	3 / 3
Progressive Disclosure	No bundle files exist and all content is inline in one monolithic ~590-line file, with large sections (notably the ~200-line optional Step 14b lock-down procedure) that could be extracted to reference files; not score 3 (no one-level-deep references) and not score 1 (sections are clearly headed and organized, not a nested wall of text).	2 / 3
	Total	10 / 12 Passed

Description

67%

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 specific and distinctive, naming four concrete technical changes for a well-scoped Nx niche, but it omits any 'when to use it' trigger guidance and relies on a single specialized register of keywords. Adding an explicit 'Use when...' clause would lift completeness and trigger-term coverage.

Suggestions

Append an explicit 'Use when...' clause naming natural trigger phrases (e.g., 'Use when migrating an Nx package from the shared dist/packages layout to local dist, or when fixing publish/version-resolution errors after such a move').

Add a couple of natural-language trigger variants alongside the jargon (e.g., 'local dist build', 'exports map migration') so non-expert phrasings also match.

Dimension	Reasoning	Score
Specificity	Enumerates four concrete technical changes — 'build to a local dist/ directory', 'nodenext module resolution', 'exports map', and '@nx/nx-source condition' — matching the multiple-specific-actions anchor.	3 / 3
Completeness	Strongly answers 'what' (migrate an Nx package to a local dist build with the listed changes) but entirely omits 'when to use it' — no 'Use when...' clause, which per the guidelines caps completeness at 2; not score 3 (no explicit trigger) and not score 1 (the 'what' is specific).	2 / 3
Trigger Term Quality	Uses real terms an Nx maintainer would say ('nodenext module resolution', '@nx/nx-source condition') but only in one specialized register, with no natural-language variations; not score 3 because coverage lacks common phrasings, not score 1 because the terms are genuinely what the target user would say.	2 / 3
Distinctiveness Conflict Risk	The niche is tightly scoped to Nx packages with 'nodenext' and '@nx/nx-source condition', making overlap with other skills minimal and wrong-skill triggers unlikely.	3 / 3
	Total	10 / 12 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: 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.