Guide
Agent Skills vs Cursor Rules
Use Cursor Rules for constraints that must apply to every edit in one repo, and agent Skills for methods the agent should invoke deliberately. Rules are always-on, cheap, and repo-scoped; Skills load only when a task matches their description, can bundle scripts and reference files, and work across Claude Code, Codex, and Gemini CLI as well as Cursor. They are complements, not alternatives — and where both speak to the same concern, the Rule wins because it is the more specific instruction.
Updated August 26, 2026 · first published August 19, 2026
At a glance
Side by side
| Cursor Rules | Agent Skills | |
|---|---|---|
| Loading | Always in context for matching files | On trigger, when the task matches the description |
| Scope | One repo (.cursor/rules) | Repo-local or user-wide, and portable between agents |
| Token cost | Paid on every request the rule matches | ~100 tokens of metadata; full instructions only when triggered |
| Can bundle scripts | No | Yes — scripts, templates, reference docs |
| Portability | Cursor only | Any SKILL.md host: Claude Code, Codex, Gemini CLI, Antigravity |
| Best for | Conventions, style, forbidden patterns | Workflows: review passes, document generation, deploys |
The actual difference: always-on vs on-trigger
A Cursor Rule is a file in .cursor/rules that Cursor injects into context whenever it applies — commonly scoped by glob to particular files. It does not decide whether to apply; you decide, once, by writing the rule and its scope. That makes rules ideal for things that are true all the time: this project uses tabs, never import from that directory, all API handlers validate input at the boundary.
A Skill is a folder with a SKILL.md whose frontmatter description tells the agent when to load it. The agent matches the task against that description and pulls in the instructions only then. That makes Skills ideal for things that are true sometimes: run a security review, generate a PDF, deploy to Cloudflare, write an ADR.
The practical consequence is cost and precision. A rule you always pay for should be short and unconditional. A Skill can afford to be long and detailed, because you only pay for it on the tasks where that detail matters — which is the whole point of the three-tier loading model.
When both could work, pick by frequency
If the instruction should shape every edit, it is a rule. If it should shape a particular kind of task, it is a Skill. A design-token list is a rule; a design-critique method is a Skill. A "never use any" TypeScript constraint is a rule; a refactoring playbook is a Skill.
Where you have written both for the same concern, keep the rule and narrow the Skill. Duplicated instructions do not reinforce each other — they compete, and the agent resolves the conflict unpredictably.
Why Skills win on portability
Rules are a Cursor feature. Skills are an open format that Claude Code, Codex CLI, Gemini CLI, and Antigravity all read, which matters more than it sounds: a team that standardises on Skills keeps its conventions when someone switches editors, and can run the same review method in CI through a terminal agent.
That portability is also why compatibility on this site is verified per Skill per agent rather than assumed. The file format is shared; what the instructions assume about their host is not.
FAQ
Common questions
Can I use Cursor Rules and Skills at the same time?
Yes, and most well-configured repos do. Rules carry the always-true constraints, Skills carry the invoked workflows. Avoid writing the same instruction into both — when they overlap the agent has two sources for one decision and the result is inconsistent.
Do Skills replace .cursorrules?
No. Skills cannot express "always do this", because they load on trigger by design. Anything that must hold for every edit belongs in a rule.
Which is cheaper in tokens?
It depends on frequency. A rule is paid on every matching request; a Skill costs about 100 tokens of metadata always and its full instructions only when triggered. For a long playbook used on 1 task in 20, the Skill is dramatically cheaper. For a three-line constraint used constantly, the rule is.
Do agent Skills work in Cursor at all?
Yes, through Cursor’s plugin layer — 78 of the 191 Skills catalogued on this site are verified working there. Because it is a compatibility layer rather than a native primitive, we list Cursor only for Skills actually tested on it.
Related
Keep reading
- Skills vs subagents vs MCP vs plugins →
The four primitives compared, with the decision rule for each.
- Best agent Skills for Cursor →
The Skills verified working in Cursor, in install order.
- Anatomy of a SKILL.md →
The frontmatter that decides whether a Skill ever triggers.