How to re-map your Cursor markdown rules, framework docs, and workflow guides into Copilot’s native instruction, prompt, skill, and agent formats – without losing any of the guidance your team built.
Why this change matters
Over the past year many of our teams have built up a serious body of Cursor configuration: global project rules, framework-specific markdown docs, task workflow templates, architecture decision records, and AI agent personas. These files are not just config – they represent months of accumulated knowledge about how we build software.
When the decision came to standardise the whole engineering organisation on GitHub Copilot, the immediate question was: can we bring any of this with us, or do we have to start from scratch?
The answer is: yes, we can migrate almost all of it – but not by copying files across and hoping for the best. Copilot has its own set of native formats that each serve a specific purpose, and understanding the mapping is what makes the difference between a migration that works and one that quietly degrades your AI output quality.
This post documents the approach we used, the file-type mapping we settled on, and the traps we ran into. It is meant to save your team the same trial-and-error.
| Key insight GitHub Copilot does not auto-load arbitrary markdown files. To be applied automatically, your guidance must live in specific supported locations and formats. This is the most important thing to understand before starting any migration. |
The core mapping: Cursor files → Copilot formats
Copilot recognises four distinct customisation layers. Understanding what each layer does – and what it is not for – is the foundation of a clean migration.
1. Repository-wide instructions (always-on)
The file .github/copilot-instructions.md is loaded for every Copilot Chat request in the repository. This is where your universal coding standards live: language choices, naming conventions, architectural patterns, security expectations, and testing requirements.
Migrate here: your global .cursorrules file, your general project.md, and any always-on coding standards that apply across the whole codebase regardless of framework.
| Warning Keep this file short and non-contradictory. If it grows beyond 60–80 lines, quality drops. Move long content into prompt or skill files instead. |
2. Path-specific instructions
Files placed at .github/instructions/*.instructions.md are activated only when files matching an applyTo glob are in scope. This is the correct home for framework-specific guidance that should never bleed across stacks.
A React-specific instruction file looks like this:
applyTo: "**/*.tsx,src/components/**/*.ts"Prefer functional React components.
Use composition over inheritance.
Reuse design-system components before creating new UI primitives.Migrate here: react.md, angular.md, testing.md, architecture-specific rules. Create one file per concern – never mix React and Angular rules in the same instructions file.
3. Prompt files (reusable task templates)
Files at .github/prompts/*.prompt.md are invoked manually in Copilot Chat. They are the native equivalent of your repeatable workflow documents: “create a React component”, “write unit tests”, “generate an ADR”.
Unlike always-on instructions, prompt files are triggered on demand – the developer explicitly invokes them. This makes them ideal for complex, step-by-step task templates that would be too noisy if applied to every request.
Migrate here: any Cursor doc that reads like a step-by-step recipe for a recurring task.
4. Skills (large knowledge packs and workflows)
The .github/skills/<name>/SKILL.md format handles richer capabilities: process documentation, architectural decision context, example libraries, and multi-step workflows that include helper files. A skill can reference other markdown files in the same folder, which makes it suitable for large, structured guidance packs that are too big for a prompt file.
Migrate here: your decisions.md, large handbook sections, workflow.md, and any multi-document guidance packs.
Quick reference migration table
| Cursor file | Copilot target | Effort |
| .cursorrules / project.md | .github/copilot-instructions.md | Low |
| react.md / angular.md | .github/instructions/*.instructions.md | Low |
| create-component.md | .github/prompts/create-component.prompt.md | Low |
| workflow.md | .github/skills/frontend-delivery/SKILL.md | Medium |
| decisions.md | .github/skills/architecture-context/SKILL.md | Medium |
| frontend-agent.md | .github/agents/frontend-implementer.md | Low |
| huge-cursor-handbook.md | Split → instructions + prompts + skills | High |
The target .github/ folder structure
For a TypeScript team working across React and Angular, a clean post-migration layout looks like this:
.github/
copilot-instructions.md ← global, always active
instructions/
react.instructions.md ← applyTo: **/*.tsx
angular.instructions.md ← applyTo: src/app/**/*.ts
testing.instructions.md ← applyTo: **/*.spec.ts
architecture.instructions.md
prompts/
create-component.prompt.md ← manually invoked
generate-adr.prompt.md
write-tests.prompt.md
skills/
frontend-delivery/
SKILL.md
examples.md ← supporting files
architecture-context/
SKILL.md
agents/
frontend-implementer.md
AGENTS.md ← optional top-level agent instructionsThe traps to avoid
Dumping a large handbook into copilot-instructions.md
This is the most common migration mistake. The always-on instructions file is loaded on every request – if it is too long or contains mixed content, Copilot’s output quality drops noticeably. Keep it focused on the five to ten most important universal rules. Everything else belongs in prompt or skill files.
Expecting rule influence on inline autocomplete
Custom instructions affect Copilot Chat and agent mode behaviour – not every inline completion as you type. If your team is used to Cursor’s approach where rules colour every keystroke completion, the Copilot experience will feel different. Set this expectation clearly before the migration so developers are not surprised.
Mixing React and Angular rules in one file
Even if you use applyTo globs, conflicting guidance in a single file can confuse Copilot when it processes shared utility files that touch both stacks. One file per concern, always.
Assuming VS Code and JetBrains work identically
VS Code supports the full set: .github/copilot-instructions.md, path-specific .instructions.md, and AGENTS.md. JetBrains Copilot support is more limited. Verify the supported feature set for your editors before committing to a structure that relies on features not available everywhere.
Recommended rollout approach
- Step 1 – Audit and tag all existing Cursor files
Build a simple spreadsheet: file name, size, category (always-on rule / framework rule / task template / knowledge pack / agent persona), and owner. This gives you visibility before you move anything.
- Step 2 – Deduplicate and resolve conflicts
Copilot combines multiple instruction sources. Contradictions between files reduce output quality. Merge overlapping guidance and reconcile anything that conflicts before you create a single new file.
- Step 3 – Build the .github/ structure
Create the folder structure, then migrate file by file using the table above. For large mixed files (the “huge handbook” case), treat the split as a refactor – not just a file move.
- Step 4 – Pilot on one repository
Pick a single React or Angular project and run the migration there first. In VS Code, check the References panel in Copilot Chat responses to confirm your instruction files are being loaded. Use the chat customisations diagnostics view to see what is active.
- Step 5 – Build a company starter pack
Once the pilot is validated, extract the baseline .github/ structure into a shared internal template. Teams starting new projects should get a pre-wired instruction set, not a blank slate.
Conclusion
Migrating from Cursor to GitHub Copilot is not a one-click import, but it is also not a rewrite. The guidance your team has accumulated is valid – it just needs to live in the right places and speak Copilot’s native language.
The biggest risk is not losing the content during migration. It is copying everything into a single instructions file and watching output quality quietly degrade because Copilot is being asked to hold too much conflicting context at once.
Treat the migration as a classification exercise first and a file-move second. Categorise, deduplicate, split appropriately, pilot on one repo, then roll out with a shared company template. Done in that order, the migration takes a few focused working days – not weeks.