Index of every page on this site: llms.txt
All skills
Run it yourself

Use when bulk-migrating import paths, renaming workspace packages, or reorganizing modules across many files in a monorepo. Uses scripted bulk operations with verification gates and atomic commits. Keywords: migrate imports, rename package, bulk import path change, module reorganization, monorepo refactor. Triggers on "migrate imports" or "rename package".

Use this Skill: https://skilld.dev/gh/acedergren/agentic-tools/migrate

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈92 tokens for metadata: the name and description. ≈1.3k when used: this file.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈368 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Migrate

When to Use

Load this skill when the user request matches the frontmatter description for Migrate.

Orchestrates monorepo migrations: import path changes, package renames, module moves. Uses scripted bulk operations (never file-by-file edits), deduplicates against existing work, verifies types at each step, and commits atomically.

Do NOT load this skill when the change only touches one or two files, the user wants exploratory refactoring, or the package boundary decision is still unresolved.

NEVER

  • Never use the Edit tool file-by-file for bulk migrations — use grep | xargs sed instead (10x faster, no missed files).
  • Never start without a deduplication check — duplicate migrations cause import conflicts that are hard to debug.
  • Never commit without typecheck — silent import breakage is worse than a failed commit.
  • Never skip the residual check — 2 files left pointing to the old path cause subtle runtime errors.
  • Never migrate without a manifest — you must know the blast radius before touching anything.
  • Never run bulk sed without confirming the manifest count with the user if > 20 files or if packages/ is touched.

Decision Tree

Does the new import path already exist in the codebase?
├── Yes (many files) → Already migrated; verify or skip
├── Yes (some files) → Partial migration; check what's left
└── No → Proceed with full migration

How many files are affected?
├── 1-2 files → Don't use this skill; use Edit tool directly
├── 3-20 files → Proceed with manifest + scripted sed
└── > 20 files → Show manifest, get user confirmation before sed

Does the change touch packages/ (shared across workspaces)?
├── Yes → Get user confirmation before running sed
└── No → Proceed

Scripts

bash scripts/build-manifest.sh @old/pkg/name
bash scripts/replace-imports.sh @old/pkg/name @new/pkg/name /tmp/migration-manifest.txt

Pipeline

Step 1: Deduplication Check

git log --oneline -20
grep -r "<new-import-path>" apps/ packages/ --include="*.ts" --include="*.svelte" -l | head -10

If migration is already complete or partial: report what exists, ask whether to verify/clean up or skip.

Step 2: Build Migration Manifest

grep -rl "<old-import-path>" apps/ packages/ --include="*.ts" --include="*.tsx" --include="*.svelte" > /tmp/migration-manifest.txt
echo "Files to migrate: $(wc -l < /tmp/migration-manifest.txt)"
cat /tmp/migration-manifest.txt

Print summary grouped by workspace. Ask user to confirm before proceeding if > 20 files or packages/ is affected.

Step 3: Scripted Bulk Replacement

grep -rl "@old/pkg" apps/api/ --include="*.ts" | \
  xargs sed -i '' "s|@old/pkg|@new/pkg|g"

grep -rl "@old/pkg" apps/frontend/ --include="*.ts" --include="*.svelte" | \
  xargs sed -i '' "s|@old/pkg|@new/pkg|g"

macOS note: sed -i '' (empty string required for in-place edit without backup). Linux uses sed -i without the empty string.

Step 4: Verification Gate

cd apps/api && npx tsc --noEmit 2>&1 | head -30
cd apps/frontend && npx svelte-check --threshold error 2>&1 | tail -20
cd packages/server && npx tsc --noEmit 2>&1 | head -20

Common causes of type errors after migration:

  • Import path changed but exported symbol name also differs → check the actual export
  • Package not yet built → pnpm --filter <package-name> build
  • Circular dependency introduced → pnpm run check:circular

Step 5: Residual Check

grep -r "<old-import-path>" apps/ packages/ --include="*.ts" --include="*.svelte" -l

Remaining occurrences may be in:

  • Dynamically constructed import strings → manual inspection required
  • Test fixture data (strings, not imports) → may be intentional
  • Comments or docs → update if they describe the API

Step 6: Run Tests

npx vitest run apps/api --reporter=dot
npx vitest run apps/frontend --reporter=dot

If tests fail: check if mock paths still point to the old module path (common missed case in test files).

Step 7: Atomic Commit

git commit -m "refactor(imports): migrate @old/pkg → @new/pkg

Affects N files across apps/api, apps/frontend, packages/server.
All typechecks pass. Full test suite green.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

Stage only migrated files — never git add -A.

Common Migration Patterns

Pattern From To
Package rename @company/old-pkg @company/new-pkg
Path restructure @app/shared/utils @app/core/utils
Index consolidation ./auth/helpers ./auth/index
Framework alias $lib/server/* src/lib/server/*

Arguments

  • $ARGUMENTS: Migration description
    • "@old/pkg/utils → @new/pkg/utils" — import path migration
    • "move packages/server/src/auth.ts to packages/server/src/auth/index.ts" — file move
    • "rename @company/old-shared → @company/core" — package rename
    • If empty: ask for source and target

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert7mo5 checks · Risk SAFE
  • Gen Agent Trust Hub8mo

    This skill provides a set of scripts and guidelines for performing bulk code migrations within a monorepo, such as renaming packages or updating import paths. It uses standard command-line tools like grep, sed, and perl for file operations and includes verification steps like type-checking and running tests.

  • Socket8mo

    No alerts

  • Snyk8mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 641a79b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago

README badge

README badge for acedergren/agentic-tools/migrate