How to Migrate from Cursor Rules to Agent Skills

Agent Skills are the open standard (agentskills.io) for packaging team-specific instructions that any AI coding tool can discover.

Migrating from hand-maintained Cursor rules means moving from static markdown you write once to structured, evidence-ranked intelligence your team already enforced in PR review — and (optionally) letting tooling generate the skill automatically.

Why migrate?

Cursor rules live only in Cursor's tree. Copilot wants .github/copilot-instructions.md. Claude Code reads CLAUDE.md. Maintaining the same conventions in four places doesn't scale.

Agent Skills provide one portable package. See what are Agent Skills for the full picture.

What you're migrating from

• Legacy .cursorrules or .cursor/rules/*.mdc
• Ad-hoc pasted instructions in chat
• CONTRIBUTING.md sections nobody reads

What you're migrating to

• .codehabits/conventions.json — structured, confidence-ranked
• .cursor/skills/codehabits-team-intel/SKILL.md — Agent Skill auto-discovered by Cursor and compatible tools
• AGENTS.md — fallback for agents that read AGENTS.md

Migration path (manual audit + auto-generate)

1. Audit existing rules

Export your current .cursor/rules files. Mark each rule as either:

• Evidence-backed — appears in PR review
• Aspirational — you wish the team did it but PRs don't enforce it

Automated extraction handles evidence-backed patterns; keep aspirational rules as short manual additions if needed.

2. Run Codehabits enable

npx @codehabits/cli login
npx @codehabits/cli enable

Compare generated conventions against your audit. You'll often find rules you forgot to document — and gaps where your written rules didn't match PR reality.

3. Commit intelligence to git

git add .codehabits/ .cursor/skills/ AGENTS.md
git commit -m "chore: migrate team conventions to Agent Skills"
git push

4. Deprecate duplicate rule files

Remove or slim down hand-written rules that now live in the generated skill. Keep only temporary or project-specific rules in .cursor/rules/. Document the change in your team channel so engineers know to pull latest.

5. Keep intelligence fresh

Set up CI auto-sync so merged PRs update conventions and regenerate the skill. Manual rules drift; PR-derived intelligence compounds.

Before and after

Related guides

• Cursor rules not working? Common fixes
• Configure every major AI tool for team conventions
• Codehabits quickstart

Originally published at codehabits.dev.