Legacy root .cursorrules was a single mega wall—everything always on. In agent mode that wall feels like “rules stopped working”: long guides tax every turn, apply inconsistently, or get skipped for project rules / skills / AGENTS.md. Treat the old file as unreliable for modern agent workloads. That’s context tax plus a layering mismatch: always-on content that should have been a skill or a portable contract is competing with short durable rules. Target shape: thin always-apply (or glob) rules under .cursor/rules, on-demand skills for multi-step workflows, portable AGENTS.md as the multi-harness router. Confirm current product behavior against Cursor’s docs—no invented changelog dates here.
Symptom: agent ignores the wall
You pasted a useful internal guide into root `.cursorrules`. Agent mode feels slower or noisier than chat. Sometimes the constraint lands; sometimes it doesn’t. Teammates add another page to the wall. Nobody removes the old one.
That’s not a mysterious bug narrative—it’s context tax plus a layering mismatch. Always-on content that should have been a skill or a portable contract is competing with short durable rules. Decision companions: When should I use a skill instead of a rule? and Cursor rules vs skills — when to use each (and how Spec Kit fits). File map: AGENTS.md vs CLAUDE.md vs `.cursor/rules`.
Target shape (thin rules + skills + AGENTS.md)
| Layer | Job | Shape |
|---|---|---|
| Thin rule (`.cursor/rules/*.mdc`) | Short durable constraints | Style, safety, globs / alwaysApply |
| Skill (`.cursor/skills/**/SKILL.md`) | Multi-step workflow on demand | Invoke when the job matches |
| AGENTS.md | Portable operating contract | Commands, verify, guardrails across harnesses |
| Legacy `.cursorrules` | Deprecated mega wall | Split and retire duplicates |
Skills and Spec Kit packs cover on-demand workflows; they do not replace short always-on constraints. Coexist: thin rules + skills/pack + `AGENTS.md`. Don’t keep three copies of the same novel.
Migrate checklist (no ship dates)
- Inventory the root `.cursorrules` wall—mark always-true constraints vs multi-step guides.
- Move short constraints into `.cursor/rules` (alwaysApply or globs only where needed).
- Split multi-step procedures into skills (or Cursor’s documented migrate path when you’re converting bloated command/rule piles).
- Park shared harness truth in root `AGENTS.md`—Cursor-shaped layers don’t abandon multi-harness.
- Delete duplicates once the thin rules + skills + router are live.
- Verify one agent turn still sees safety/style rules without loading every old guide.
Official UI, flags, and migrate commands: Cursor docs. This post owns the ops split, not a help-center clone.
Pack coexistence note
A skills pack or Spec Kit skill ids can replace workflow chunks of the old wall. They won’t magically replace thin always-on safety/style. After you split, reconcile pack ids with install/pack posts rather than forking Spec Kit here: see cursor-rules-vs-skills-spec-kit and the keep/convert call in skill-vs-rule-when.
What the Agent Starter Kit is for
The Agent Starter Kit ($47) assumes rules + skills + an `AGENTS.md` router—not another mega `.cursorrules`. Soft path: /free for the starter desk; Cheat Sheet for the skim checklist; kit when you’re standardizing the split.
Contrast: cursor-rules-vs-skills-spec-kit. Decision: skill-vs-rule-when. Harness file map: agents-md-vs-claude-md-vs-cursor-rules.
Soft next step
Split one fat `.cursorrules` into thin always-apply rules + on-demand skills, keep `AGENTS.md` as the portable router, and retire duplicates. Soft ladder: /free, then the Agent Starter Kit ($47). Contrast: cursor-rules-vs-skills-spec-kit; decision: skill-vs-rule-when; harness map: agents-md-vs-claude-md-vs-cursor-rules.