How to Migrate from Cursor Rules to Agent Skills

**Agent Skills** are the open standard ([agentskills.io](https://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](https://codehabits.dev/blog/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 ```bash 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 ```bash 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](https://codehabits.dev/docs/ci) 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 | ## Related guides - [Cursor rules not working? Common fixes](https://codehabits.dev/blog/cursor-rules-not-working) - [Configure every major AI tool for team conventions](https://codehabits.dev/blog/ai-coding-tools-team-conventions) - [Codehabits quickstart](https://codehabits.dev/docs/quickstart) --- *Originally published at [codehabits.dev](https://codehabits.dev/blog/migrate-cursor-rules-to-agent-skills).*