How to Migrate from Cursor Rules to Agent Skills

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.