Instruction File Migrator
Convert and synchronize agent instruction files between formats: CLAUDE.md with @imports and CLAUDE.local.md, AGENTS.md nested per directory, Cursor rules (.cursor/rules/*.mdc with description, globs, and alwaysApply frontmatter, plus the legacy .cursorrules), GEMINI.md, GitHub Copilot's copilot-instructions.md and *.instructions.md with applyTo, Windsurf rules, and .clinerules. It preserves each rule's wording, keeps always-on rules separate from path-scoped ones, and reports every rule that has no one-to-one equivalent in the target. Use when a team runs more than one coding agent and the files have drifted, or when switching tools.
This skill parses an instruction file into rules with their scope (always-on, path-scoped, on-demand, or manual), renders them in the target format, keeps personal files out of shared ones, and lists every rule the target cannot hold one-to-one. It covers CLAUDE.md, AGENTS.md, Cursor rules, GEMINI.md, Copilot, Windsurf, and Cline, and diffs files for drift.
Install to ~/.claude/skills/instruction-file-migrator/SKILL.md
npx agentscamp add skills/instruction-file-migratorTeams rarely run one coding agent. Someone uses Claude Code, someone uses Cursor, the CI job runs Codex, and each tool reads its own instruction file. Within a month the files disagree about the test command. This skill treats the rules as the source and the files as renderings: it parses every rule out of a source file with its scope (always loaded, loaded for matching paths, loaded on request, or manual), writes the target format with the same wording, and tells you which rules could not be carried over because the target has no place for them. It converts in both directions and can diff two existing files to show drift.
When to use this skill
- You adopted a second agent and want its instruction file to say what the first one says.
- A
.cursorrulesfile from before Cursor's rules directory needs to become.cursor/rules/*.mdcor aCLAUDE.md. CLAUDE.mdandAGENTS.mdboth exist, both are edited by hand, and nobody knows which is current.
When NOT to use this skill
- You have no instruction file yet: the agent-memory-designer skill explores the repository and writes a CLAUDE.md from its real commands and gotchas.
- One file, one target, right now: the /convert-rules command.
- Permission rules, hooks, and MCP servers live in settings files, not instruction files; the claude-settings-auditor skill covers those.
Instructions
-
Inventory the source files and their load semantics. The formats differ in where they live and how a rule becomes active:
Format Always-on Path-scoped On demand or manual Nesting and imports CLAUDE.md CLAUDE.mdbody;~/.claude/CLAUDE.mdfor the user.claude/rules/*.mdloaded for matching pathsnone nested CLAUDE.mdper directory;@pathimports;CLAUDE.local.mdfor personal, uncommitted rulesAGENTS.md file body none none nested per directory, closest file wins; plain Markdown, no frontmatter Cursor rules .cursor/rules/*.mdcwithalwaysApply: trueglobs:in frontmatterdescription:only (the agent decides), or neither (manual mention)nested .cursor/rulesper directory; legacy single.cursorrulesGEMINI.md file body, global and project none none hierarchical per directory; @fileimportsCopilot .github/copilot-instructions.md.github/instructions/*.instructions.mdwithapplyTo:none none Windsurf .windsurf/rules/*.mdwith an always-on triggerglob trigger model-decision or manual trigger legacy .windsurfrules; per-file size capsCline .clinerulesfile or every file in.clinerules/none none none -
Parse the source into rule units. Split on headings and list items. For each rule record the text verbatim, its section, its scope from the table, its globs if any, and whether it came from a personal file (
CLAUDE.local.md, a user-level file) or a shared one. Keep code blocks and commands byte-for-byte; a rewritten command is a bug. -
Decide the mapping before writing. Always-on rules go to the target's always-on surface. Path-scoped rules go to the target's path mechanism when it has one (Cursor
globs, CopilotapplyTo, a Windsurf glob trigger, Claude's.claude/rules/); when it has none (AGENTS.md, GEMINI.md, Cline), render them under a heading that names the paths ("## Rules forpackages/api/**") so a reader still sees the scope, and list them in the report as "scope became advisory". Cursor's description-only rules have no equivalent elsewhere: ask whether to promote them to always-on or pin them to paths. Never make them always-on silently. -
Handle imports and personal files. Inline
@pathimports when the target has no import syntax, with a comment naming the origin file. Never mergeCLAUDE.local.mdor a user-level file into a shared, committed target; write those rules to the target's personal equivalent if one exists, otherwise leave them out and say so. -
Write the target. Same section order, same wording, same commands. Frontmatter per the target: Cursor
description,globs,alwaysApply; CopilotapplyTo; Windsurf trigger and globs. For nested formats, write one file per directory that had scoped rules. For targets with size caps, split by section and report the split. -
Sync mode. When both files already exist, parse both into rule units, match by normalized text, and report rules present in one but not the other, rules whose wording differs, and rules whose scope differs. Propose a direction based on which file git history shows as newer, and apply only after the user picks.
-
Report what did not map. For each: the rule, its source scope, what the target offered, and what you did. This list is the point of the skill; a conversion that hides it cannot be trusted.
WARNING
Personal files carry local paths, machine names, and sometimes credentials. A migration that folds CLAUDE.local.md into a committed AGENTS.md publishes them. Keep the personal and shared layers separate in every target, and say when a target has no personal layer at all.
TIP
Pick one canonical source and generate the rest. If the team edits CLAUDE.md, treat AGENTS.md and the Cursor rules as build outputs and re-run this skill when the source changes. What belongs in the source is covered in CLAUDE.md best practices; what belongs in a tool-neutral AGENTS.md is in Codex and AGENTS.md.
Output
The target file or files, written to their conventional paths; a mapping table with columns Rule (first line), Source scope, Target placement, and Status (mapped, advisory, asked, left out); the list of rules that did not map one-to-one; and, in sync mode, the drift report with a proposed direction.
Filed under
claude · claude-md · agents-md · cursor-rules · configuration · developers
Related
- Convert RulesConvert one agent instruction file to another format (for example .cursorrules to CLAUDE.md, or CLAUDE.md to AGENTS.md), preserving wording and path scoping, and list the rules that did not map.
- AGENTS.mdAGENTS.md is a versioned instruction file that tells coding agents how to work in a repository — including commands, conventions, boundaries, and checks.
- AGENTS.md for Codex: Project Instructions That Actually WorkWrite an effective AGENTS.md for OpenAI Codex — what belongs in it, how nested overrides work, and how to verify the instructions Codex loaded.
- Claude Code Settings & Permissions: settings.json ExplainedEvery Claude Code settings file and which one wins, the permission-rule syntax with its Bash matching gotchas, modes, and a safe starter settings.json.
- CLAUDE.md Best PracticesHow to write a CLAUDE.md that actually helps — what to include, what to leave out, and how to keep it current.
- Agent Memory DesignerDesign a project's CLAUDE.md and memory hierarchy by exploring the repo to learn its real build/test/lint commands, architecture, and non-obvious gotchas, then writing a concise, skimmable memory that keeps only what belongs in context. Use when onboarding a repo to Claude Code with no CLAUDE.md, or when an existing one is bloated, stale, or being ignored.
- Claude Settings AuditorAudit every Claude Code settings layer — user, project, local, and managed — and report the effective merged configuration with its risks: over-broad Bash allows, missing deny rules for secrets, bypassPermissions defaults, unvetted MCP servers and hooks, and rules that never match. Use before trusting a new repo's checked-in settings, or to harden your own before handing the agent more autonomy.
- Cursor RulesCursor rules are persistent instructions for Cursor's AI agent: project rules as .cursor/rules/*.mdc files with frontmatter, plus User Rules and Team Rules.