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

Hand-written Cursor rules	Codehabits Agent Skills
You write and maintain	Extracted from PR evidence
Cursor-only	Portable across 16+ tools
Static until someone edits	Syncs after each merged PR
No confidence scores	Ranked by review frequency