Home / Compare / Cursor rules vs Claude skills
Cursor rules vs Claude Code skills
Both are markdown. Both shape how an agent behaves. They are not interchangeable.
The mental model
- A Cursor rule is a standing instruction. It applies to every conversation the agent has in your repo. "Use TypeScript strict mode." "Prefer composition over inheritance." "Tests live in
tests/." - A Claude Code skill is a procedure. It defines how to perform a specific task: writing tests, debugging a bug, generating a commit message. It loads only when the agent decides the task fits.
Rule: always-on context. Skill: on-demand procedure. The two layer cleanly.
Side-by-side
| .cursorrules | SKILL.md | |
|---|---|---|
| Tool | Cursor only | Claude Code (and other tools that adopt the spec) |
| Loads when | Every prompt | When the agent decides the task fits the skill's description |
| Length norms | 50–300 lines | 20–200 lines + optional bundled scripts |
| Holds code | Rare; mostly rules | Yes — bundled scripts/, examples, output schemas |
| Best for | Repo-wide style + workflow | Reusable procedures across repos |
When to write a Cursor rule
- Codebase conventions: typing strictness, test paths, naming, library preferences.
- Negative rules: "Don't add new dependencies without asking." "Don't create READMEs unless asked."
- Output preferences: terse PR descriptions, no emoji in code comments, specific commit message format.
When to write a Claude skill
- Repeatable procedure with a clear trigger: "Write tests for X." "Debug failing test Y." "Generate a postmortem."
- The procedure has steps the agent should follow in order.
- You want to share the procedure across repos. Skills travel; rules stay.
- You want bundled examples or scripts the agent can reference without re-deriving.
The description-line trick
The single most underrated lever in SKILL.md authoring: the description field. It's how Claude Code decides whether to load the skill at all. A vague description ("for testing") gets ignored. A specific description with example triggers ("Use when writing or fixing tests for the test suite under tests/") gets loaded reliably. Three rules:
- Lead with the trigger condition.
- List explicit phrases or filenames that should fire it.
- Keep it under 200 chars.
If you've never had to think about whether your skill loads, your descriptions are fine. If you find yourself manually invoking skills, fix the descriptions first.
Worked example: bug repro
"Make a minimal reproduction of bug X." This is a procedure. Skill, not rule.
- Skill description: "Use when reproducing a bug. Triggers on phrases like 'minimal repro', 'reduce this case', 'isolate the failure'."
- Body: 5 steps — reduce inputs, kill ambient state, lock versions, save as a runnable file, document the expected output.
- Bundled: a tiny
repro-template.test.cjsthe agent can copy.
You wouldn't put this in .cursorrules. It's not always-on; it's task-specific.
Browse MDs
- Cursor rules — production-grade .cursorrules
- Claude skills — SKILL.md files for common procedures
- agents.md vs cursor rules →
Last updated: 2026-04-25.