Convert .cursorrules to CLAUDE.md, AGENTS.md & Copilot

Why you end up converting at all

Almost nobody runs a single AI coding tool anymore. You write in Cursor, you let Claude Code handle the big multi-file refactors from the terminal, and your CI reviews come from Copilot. Each one reads its own instructions file, and none of them reads the others’ by default. So the same three sentences — “strict TypeScript, no any, functions under 50 lines” — have to physically exist in .cursorrules, CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md.

That’s the conversion tax. You encode a convention once, then port it three more times, and from that point on every edit is a four-way sync you’ll forget to do. The first half of this guide is the honest mapping between formats. The second half is how to stop paying the tax. If you want the conceptual comparison first, see SKILL.md vs CLAUDE.md vs .cursorrules vs AGENTS.md.

The mapping: what translates and what doesn’t

Before any copy-paste, get the conceptual map straight. The four formats agree on “always-on instructions” and disagree on almost everything else — scoping, on-demand activation, and file references all diverge. Here is concept by concept where each format lands:

Three rows do most of the damage. Glob-scoped rules translate cleanly only to Copilot. On-demand procedures aren’t a rules-file concept in Claude Code at all — they’re skills. And @file references survive into CLAUDE.md but evaporate in AGENTS.md and copilot-instructions.md. Keep those three in mind through every worked example below.

.cursorrules → CLAUDE.md

This is the easy direction. A legacy .cursorrules file is plain Markdown with no frontmatter, and CLAUDE.mdis also plain Markdown loaded into every turn. The text moves over essentially unchanged — you’re renaming the file and dropping its contents into the project memory file Claude Code reads automatically.

# .cursorrules  (Cursor, repo root)
# Project: Acme API
## Standards
- Strict TypeScript. No `any`, no unguarded `as` casts.
- Functions under 50 lines, files under 800.
## Testing
- Vitest for unit, Playwright for E2E. 80% line coverage.
## Don't
- Don't run `pnpm install` without asking.

becomes, with no real edits:

# CLAUDE.md  (Claude Code, repo root)
# Project: Acme API
## Standards
- Strict TypeScript. No `any`, no unguarded `as` casts.
- Functions under 50 lines, files under 800.
## Testing
- Vitest for unit, Playwright for E2E. 80% line coverage.
## Don't
- Don't run `pnpm install` without asking.

@docs/architecture.md   # CLAUDE.md supports @imports

.cursorrules → AGENTS.md

AGENTS.mdis the “README for agents”: plain Markdown, no required frontmatter, read by roughly two dozen tools — Codex, Cursor, Copilot, Gemini CLI, Aider, Zed, and more. Porting .cursorrules into it is the same near-verbatim copy as the CLAUDE.md case. The payoff is portability: one file most of your tools already read.

# AGENTS.md  (repo root — read by ~24 tools)
# Acme API — agent instructions

## Standards
- Strict TypeScript. No `any`, no unguarded `as` casts.
- Functions under 50 lines, files under 800.

## Testing
- Vitest for unit, Playwright for E2E. 80% line coverage.

## Conventions
- Don't run `pnpm install` without asking.

.cursorrules → copilot-instructions.md

GitHub Copilot reads repo-wide instructions from exactly one path: .github/copilot-instructions.md. Get the path wrong and Copilot silently ignores it. The body is plain Markdown again, so the always-on parts of your .cursorrules port directly.

# .github/copilot-instructions.md  (exact path required)
# Acme API

- Strict TypeScript. No `any`, no unguarded `as` casts.
- Functions under 50 lines, files under 800.
- Vitest for unit, Playwright for E2E; 80% line coverage.
- Don't run `pnpm install` without asking.

Copilot also has a second tier that Cursor users will recognize: path-specific instructions in .github/instructions/*.instructions.md, each with an applyToglob in its frontmatter. This is the direct analog to Cursor’s glob-scoped .mdc rules:

# .github/instructions/tests.instructions.md
---
applyTo: "**/*.test.ts"
---
- Use Vitest. One `describe` per unit under test.
- Arrange-Act-Assert; no logic in the assert block.

What about glob-scoped rules?

This is where conversion gets lossy, so be honest about it. Cursor’s globs: field — the thing that fires a rule only when you touch src/**/*.ts— has exactly one clean target: Copilot’s applyTo. Same concept, same glob syntax, a true one-to-one port.

For CLAUDE.md and AGENTS.md there is no per-glob field. Your only real tool is the filesystem: drop a nested CLAUDE.md or AGENTS.mdinto the directory you wanted to scope, and let the “closest file wins” rule do the scoping by location instead of by pattern. It works for packages/api/-style boundaries; it does not work for cross-cutting globs like **/*.test.tsthat span many directories. Those rules either become always-on (and cost you context everywhere) or get duplicated into each relevant nested file. There is no clean answer — which is the first sign you shouldn’t be hand-converting at all.

The one-source-of-truth workflow

Step back and count the work. Four formats, three of them needing manual edits for scoping, and a permanent obligation to re-sync all four every time a convention changes. Doing the conversion once is annoying. Doing it forever is the actual problem — and it’s the problem every small tool in this space (rulesync, rule-porter, and friends) is circling.

The structural fix is to stop treating any IDE’s file as the source. Keep one canonical library of rules and skills, and compileit to each tool’s format on demand. Edit a convention once; regenerate .cursorrules, CLAUDE.md, AGENTS.md, and copilot-instructions.md from the single source. The glob-vs-no-glob lossiness becomes a compiler concern instead of a thing you re-reason about by hand every time.

That’s exactly what Skillwright does: author your rules and skills once in a canonical library, then compile and deploy them to Cursor, Claude Code, Windsurf, and Copilot — across every project at once. Conversion stops being a recurring chore and becomes a build step. For the full strategy, read how to manage AI coding rules across tools, and for the conceptual comparison of the formats themselves, see SKILL.md vs CLAUDE.md vs .cursorrules vs AGENTS.md. If you just want a head start, grab a set of MIT-licensed starter rules from the templates library and compile from there.

Frequently asked questions