Migrating Existing Configuration
Most repositories do not start empty. They have a CLAUDE.md, a .cursor/rules/ tree, a .claude/skills/ directory, or all three. Migration is the part of initialization that needs judgment, which is why the skill handles it and the CLI does not.
What gets found, and where it goes
Section titled “What gets found, and where it goes”| Class | Look for | Disposition |
|---|---|---|
| Instructions | AGENTS.md, .agents/AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/**, .github/copilot-instructions.md, .github/instructions/**, GEMINI.md, .windsurfrules | Consolidate into AGENTS.md; confirm before replacing anything |
| Skills | .claude/skills/, .cursor/skills/, .codex/skills/, .github/skills/, .windsurf/skills/, .gemini/skills/ | Move to .agents/skills/, fix frontmatter, then link back |
| Commands | .claude/commands/*.md, .cursor/commands/*.md | Move to .agents/skills/<name>/SKILL.md |
| Subagents | .claude/agents/ | Canonical-only. No cross-harness format exists, so it is reported and left in place |
| Rules | .cursor/rules/**.mdc, .claude/rules/, .windsurf/rules/ | Canonical-only. .mdc and .md are not interchangeable, and path-scoping syntax differs |
| MCP servers | .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .claude/settings.json | Canonical-only. Never converted between formats |
| Hooks, output styles | hook blocks in settings files, .claude/output-styles/ | Canonical-only. Hook event names differ by case across harnesses, so no safe projection exists |
Instructions consolidate
Section titled “Instructions consolidate”Harness instruction files are prose, and prose merges. Their content moves into the root AGENTS.md with the author’s wording preserved, appended rather than restructured. The harness file is replaced with a pointer only where you approve it.
CLAUDE.md is the one instruction file where consolidating is not optional. Claude Code reads AGENTS.md itself, unless a CLAUDE.md sits beside it, so a leftover copy is read instead of everything you just consolidated. Its content moves into AGENTS.md and the file goes, or keeps an @AGENTS.md import above whatever genuinely has to stay Claude-only. A CLAUDE.md that is already nothing but that import, or a symlink, still works: removal is offered, never taken unasked. A CLAUDE.local.md is personal and is neither consolidated nor deleted, so it is offered the import instead.
Gemini CLI is the one harness left needing a bridge: it defaults to GEMINI.md, and AGENTS.md has to be added to context.fileName in .gemini/settings.json. The CLI does not write it. See Gemini CLI.
Commands become skills
Section titled “Commands become skills”.claude/commands/*.md and .cursor/commands/*.md migrate to .agents/skills/<name>/SKILL.md. Claude Code has merged commands into skills, so this follows the harness rather than fighting it. Migration uses git mv where possible so history follows the file.
Each migrated file needs frontmatter that satisfies the Agent Skills specification: at minimum a name matching its new directory and a description. A derived name and description are shown verbatim for approval before being written. See Portable Skills for what survives the trip across harnesses.
Rules do not convert
Section titled “Rules do not convert”The most common migration mistake is generating .cursor/rules/*.mdc from AGENTS.md, or deleting .cursorrules on the assumption that AGENTS.md now covers it.
It does not. .mdc and .md are not interchangeable, and path-scoped rules have no AGENTS.md equivalent — a rule carrying globs or a description loads only when those match, while AGENTS.md loads on every turn. Generating a rule from AGENTS.md invents scope the source never carried; deleting one trades conditional activation for always-on context. Cursor reads AGENTS.md in every mode, so nothing stops reading the words — what changes is when they load, and that is a cost every session pays.
The same reasoning covers subagents, hooks, and MCP servers. They are reported and left exactly where they are.
Conflicts
Section titled “Conflicts”A pre-existing harness skills directory containing real skills is a conflict by design. The CLI checks every target before changing any of them, and without --force a conflict stops the run with all targets unchanged.
Move those skills into .agents/skills/ first. Do not clear the conflict with --force, which discards them.