From project-references-migration
Use when a layered TypeScript workspace needs an incremental project-references migration without breaking package boundaries or editor resolution.
How this skill is triggered — by the user, by Claude, or both
Slash command
/project-references-migration:project-references-migrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
- The repository has multiple TypeScript packages or layers and needs faster, more reliable builds.
tsc -b project references incrementally.tsc -b, fresh declarations, and editor go-to-definition to agree.tsconfig.tsconfig cleanup rather than adopting composite, references, or tsc -b.Required before editing
tsconfig files.Helpful if present
tsconfig chain, and any obvious cycles.Solution config:
{
"files": [],
"references": [
{ "path": "./packages/core" },
{ "path": "./packages/ui" }
]
}
Pilot package config:
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"composite": true,
"declaration": true,
"declarationMap": true,
"rootDir": "src",
"outDir": "dist"
},
"references": [{ "path": "../core" }]
}
composite and the required declaration settings on the pilot package.references only where the dependency graph is already real.tsc -b or the repository's equivalent only after the referenced graph is coherent.rootDir, outDir, declaration, and package exports point at the same build layout.tsconfig inheritance before widening the reference graph.composite / references migration path.tsconfig-hardening when the task is mainly single-package compiler-option cleanup or strictness tuning.tsc-error-triage when the references migration has already landed and remaining work is source-level compiler failure triage.Run the repository's referenced build or the nearest equivalent after each migration batch.
Confirm declarations and outputs land in the expected locations.
Run the typecheck workflow that consumes cross-package imports, not just the referenced build.
Open a consuming file in the editor when possible, trigger go-to-definition on an imported symbol, and confirm it resolves to the expected referenced package source or fresh declarations rather than stale outputs.
Smoke test:
tsconfig-hardening)Before
{
"compilerOptions": {
"composite": false
}
}
After
{
"compilerOptions": {
"composite": true,
"declaration": true,
"declarationMap": true
},
"references": [{ "path": "../core" }]
}
tsc -b and editor go-to-definition resolve against the fresh declarations instead of stale outputs.references/migration-checklist.md - staged checklist for introducing project references without destabilizing the workspace.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub matt-riley/lucky-hat --plugin project-references-migration