TimCrooker · TimCrooker · May 28, 2026 · May 26, 2026 · May 26, 2026 · May 26, 2026
diff --git a/.changeset/migrate-cli-and-skill.md b/.changeset/migrate-cli-and-skill.md
@@ -0,0 +1,25 @@
+---
+"@timothycrooker/ai-context-core": minor
+"@timothycrooker/ai-context-cli": minor
+"@timothycrooker/ai-context-templates": minor
+"@timothycrooker/ai-context-config": minor
+---
+
+Add migrate CLI subsystem and ai-context-migrate skill (1.1.0).
+
+**New:**
+- `ai-context migrate plan` — audit legacy skill layout, generate `.ai/migration-plan.json`
+- `ai-context migrate status` — report plan presence + applied state
+- `ai-context migrate apply [--dry-run]` — execute the plan (per-entry git commits, git-clean precondition)
+- `ai-context migrate clean` — remove applied plan file
+- Bundled `ai-context-migrate` skill (SKILL.md + 4 reference docs: overlap-detection, family-routing, legacy-md-conversion, post-migration-verification)
+- EPMX-adapted gauntlet at `scripts/epmx-gauntlet/run.sh`
+- Self-test at `scripts/test-migrate-on-gauntlet.sh`
+
+**Backward compatibility:**
+
+Migrate is opt-in. Existing repos without legacy skills are unaffected. The new `ai-context-migrate` skill ships in templates alongside `ai-context-kit`. No breaking changes.
+
+**Validation:**
+
+Migrated EPMX Monorepo's 40-entry legacy layout to `.ai/skills/` source-of-truth. EPMX gauntlet passes all stages across Claude/Codex/Gemini ([EPMX PR #511](https://github.com/Empowering-People-More/EPMX-Monorepo/pull/511)).
diff --git a/README.md b/README.md
@@ -103,6 +103,17 @@ Set up the trusted publisher in npm for `TimCrooker/ai-context-kit` before runni
 
 ai-context-kit supports cross-CLI skills via the [agentskills.io](https://agentskills.io) open standard. Author once at `.ai/skills/<name>/SKILL.md`; the kit creates symlinks at `.agents/skills/<name>` (read by Codex, Gemini, Cursor, Goose, OpenCode, Aider, and 17+ other tools) and `.claude/skills/<name>` (read by Claude Code). See [docs/skills-guide.md](docs/skills-guide.md).
 
+## Migration (1.1+)
+
+Existing repos with legacy `.claude/skills/` layouts can migrate to ai-context-kit's `.ai/skills/` source-of-truth via:
+
+```bash
+ai-context migrate plan       # audit current layout
+ai-context migrate apply      # execute (requires clean git tree)
+```
+
+See [docs/migrating-existing-repos.md](docs/migrating-existing-repos.md) for the full workflow including agent-driven curation.
+
 ## License
 
 MIT
diff --git a/docs/cli-contract.md b/docs/cli-contract.md
@@ -97,3 +97,37 @@
 - Purpose: used together with `--upgrade`; forces overwrite of files under `.ai/skills/ai-context-kit/` even if they already exist.
 - Refreshes the meta-skill content from the latest `@timothycrooker/ai-context-templates` package.
 - All other existing files are still preserved (only the meta-skill directory is overwritten).
+
+### `ai-context migrate plan [--force]`
+
+- Purpose: scan `.claude/skills/` and generate a migration plan at `.ai/migration-plan.json`.
+- Flags:
+  - `--force`: overwrite an existing plan file.
+- Exit codes: `0` on success, `1` on precondition failure (manifest unreadable, etc.).
+- Success output: summary of entries found and actions by type, plus next-steps instructions.
+- The plan file is NOT committed automatically — you review and commit it if desired.
+
+### `ai-context migrate status`
+
+- Purpose: report the state of the current migration plan.
+- Exit codes: `0` always (no plan is not an error, just informational).
+- When no plan exists: prints "No migration plan present at .ai/migration-plan.json".
+- When plan exists: prints generated date, entry count, applied/total progress, and action breakdown.
+
+### `ai-context migrate apply [--dry-run]`
+
+- Purpose: execute the migration plan, one git commit per entry.
+- Flags:
+  - `--dry-run`: print what would happen without modifying files or making commits.
+- Preconditions (all must be met, else exit 1):
+  - Must be a git repository.
+  - Working tree must be clean (except for the plan file itself).
+  - Manifest must have a `skills` block.
+- Exit codes: `0` on success, `1` on precondition failure, `2` on partial apply failure.
+- Each entry creates one git commit with message `chore(migrate): <action> <name>`.
+
+### `ai-context migrate clean`
+
+- Purpose: remove an applied migration plan file.
+- Refuses to remove a plan that has not been applied (to prevent data loss).
+- Exit codes: `0` on success or when no file present, `1` when plan is unapplied.
diff --git a/docs/error-codes.md b/docs/error-codes.md
@@ -32,6 +32,25 @@
 - `AICTX_SKILL_MIRROR_BROKEN`
   - A mirror symlink points at a missing target (the source skill was deleted). Run `ai-context build --remove-orphans`.
 
+### Migrate subsystem (`AICTX_MIGRATE_*`)
+
+- `AICTX_MIGRATE_PLAN_EXISTS`
+  - A migration plan already exists at `.ai/migration-plan.json`. Use `--force` to overwrite, or `ai-context migrate clean` if the previous plan was applied.
+- `AICTX_MIGRATE_PLAN_NOT_FOUND`
+  - No migration plan found. Run `ai-context migrate plan` first.
+- `AICTX_MIGRATE_PLAN_INVALID`
+  - The migration plan file at `.ai/migration-plan.json` is not valid JSON. Delete it and regenerate with `ai-context migrate plan`.
+- `AICTX_MIGRATE_NO_SKILLS_BLOCK`
+  - The manifest does not have a `skills` block. Run `ai-context init --upgrade` to add one before applying a migration plan.
+- `AICTX_MIGRATE_DIRTY_TREE`
+  - The git working tree has uncommitted changes. Commit or stash all changes before running `ai-context migrate apply`.
+- `AICTX_MIGRATE_NOT_GIT_REPO`
+  - The current directory is not a git repository. Migration requires git for history-preserving file moves.
+- `AICTX_MIGRATE_ENTRY_FAILED`
+  - A migration entry failed to apply. The migration is halted at that entry. Fix the issue and re-run `ai-context migrate apply` (it will skip already-applied entries).
+- `AICTX_MIGRATE_ALREADY_APPLIED`
+  - Raised by `ai-context migrate clean` when the plan has not been applied yet. Apply the plan first, or delete the plan file manually.
+
 ## CLI Formatting
 
 When a `ContextError` reaches CLI handlers, it is rendered as:

diff --git a/docs/migrating-existing-repos.md b/docs/migrating-existing-repos.md
@@ -0,0 +1,71 @@
+# Migrating an Existing Repo to ai-context-kit Skills
+
+Step-by-step guide for adopting ai-context-kit 1.1+ in a repo that already has skills scattered across `.claude/skills/` or other legacy locations.
+
+## Prerequisites
+
+- Kit version 1.1.0+ installed: `pnpm add -D @timothycrooker/ai-context-cli`
+- Git working tree is clean (migration requires this)
+- Manifest at `.ai/context/manifest.json` exists (run `ai-context init --upgrade` first if not)
+
+## The 4-phase migration
+
+### Phase 1: Audit
+
+```bash
+ai-context migrate plan
+```
+
+This scans your `.claude/skills/` and other legacy locations, then writes `.ai/migration-plan.json`. The plan shows:
+- How many skills found
+- Which action will apply to each (move_dir, promote_bare_md, consolidate_symlink, keep_existing)
+- Any warnings (e.g., missing skills block in manifest)
+
+**Review the plan** before proceeding:
+
+```bash
+cat .ai/migration-plan.json
+ai-context migrate status
+```
+
+### Phase 2: Curate (optional)
+
+Open an AI session (Claude, Codex, or Gemini) and prompt:
+
+> "Please review the .ai/migration-plan.json file. Use the ai-context-migrate skill to audit for overlap and quality. Edit the plan if needed, then report your findings."
+
+The agent will use the bundled `ai-context-migrate` skill to examine your skills and decide whether to keep duplicates, factor shared content, etc.
+
+You can SKIP this phase if you trust the auto-generated plan.
+
+### Phase 3: Apply
+
+```bash
+ai-context migrate apply --dry-run    # see what would change
+ai-context migrate apply              # execute
+```
+
+Each plan entry becomes its own git commit. Partial rollback is possible via `git reset --hard <pre-migration-sha>`.
+
+### Phase 4: Verify
+
+```bash
+ai-context build       # regenerate AGENTS.md/CLAUDE.md + mirror symlinks
+ai-context verify      # confirm clean state
+ai-context doctor      # check for issues
+ai-context skills list # confirm all skills present with symlink mirrors
+```
+
+## Troubleshooting
+
+- **"Git tree is not clean"** — commit or stash your changes first
+- **"manifest.skills not configured"** — run `ai-context init --upgrade` to add the skills block
+- **"Plan already exists"** — use `ai-context migrate plan --force` to regenerate, or `ai-context migrate clean` if the previous one is applied
+- **A skill is now broken (missing references)** — the migration preserves files but doesn't update cross-skill path references. Search your skill bodies for the old `.claude/skills/<name>` paths and update to the new locations.
+
+## Reverting
+
+```bash
+git log --oneline | grep "chore(migrate)"   # find migration commits
+git reset --hard <pre-migration-sha>
+```
diff --git a/docs/skills-guide.md b/docs/skills-guide.md
@@ -2,6 +2,8 @@
 
 How `ai-context-kit` manages cross-CLI skills (Claude Code, Codex, Gemini, Cursor, Goose, OpenCode, Aider, and 17+ other tools on the agents.md compatibility list).
 
+> **Have an existing repo with skills already in `.claude/skills/`?** See [docs/migrating-existing-repos.md](migrating-existing-repos.md) for the migration workflow.
+
 ## TL;DR
 
 Author skills once at `.ai/skills/<name>/SKILL.md`. Run `ai-context build`. Every agent CLI sees them.