Cursor Rules: How They Work and When a Rule Beats a Skill

Cursor rules are persistent instructions for Cursor's agent: markdown files stored in .cursor/rules that get injected at the start of the model's context, so the agent follows your conventions without you repeating them in every prompt. They answer a real problem. Models are stateless between requests, and anything you do not tell them, they will improvise: import styles, error-handling patterns, commit conventions, whether a UI change was actually checked before the agent declared it done. Rules turn those recurring instructions into version-controlled files that ship with your repo.

But rules are no longer the only way to package instructions, and that changes what belongs in one. Cursor now supports skills, on-demand instruction packages the agent loads only when a task calls for them, alongside MCP servers that add outright capabilities like controlling a browser or querying a database. Each mechanism has a different cost profile. A rule that always applies taxes every single request with its token weight, whether relevant or not. A skill costs almost nothing until invoked. An MCP tool costs nothing until called, but is the only one of the three that lets the agent do something new rather than merely know something new.

So the organizing question of this guide is placement: which instructions deserve the always-on treatment of a rule, which should move into skills, and which problems are not instruction problems at all but capability problems. Getting this wrong in one direction bloats your context and degrades every response. Getting it wrong in the other direction means the agent forgets your conventions exactly when you stopped watching. This guide covers the current rule format and its four activation types, the migration path from the legacy .cursorrules file, AGENTS.md, and a decision table for rule versus skill versus MCP, with a worked example from testing and verification workflows.

What Cursor rules are

A rule is a markdown file with the .mdc extension living under .cursor/rules in your project. When a rule applies, its contents are included at the start of the model context, before your prompt. Cursor's docs describe rules as system-level instructions to the Agent: persistent, reusable context at the prompt level.

Three properties matter:

• Version-controlled. Project rules live in the repo, so the whole team, and every agent session, gets the same instructions. Review them in PRs like code.
• Scoped. Rules can attach to the whole project, to file patterns, or to nothing until explicitly invoked. Subdirectories work: .cursor/rules/frontend/components.mdc is valid, and nested .cursor/rules directories can scope rules to parts of a monorepo.
• Prepended, not conversational. The agent does not "read" a rule the way it reads a file you attach. Rule content is context it starts from, which is what makes rules reliable for conventions and expensive when bloated.

Cursor also supports User Rules, global preferences set in your Cursor environment that apply across all projects in chat, and Team Rules on Team and Enterprise plans, applied organization-wide from the dashboard. Precedence runs Team Rules, then Project Rules, then User Rules. This article focuses on project rules, since those are the ones you design and commit.

The current format: .mdc files and four rule types

Each .mdc file starts with frontmatter using three fields: description, globs, and alwaysApply. The combination you set determines the rule's type:

A scoped rule looks like this:

---
description: Conventions for Express API routes
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate request bodies with zod schemas from src/schemas.
- Return errors through the ApiError helper, never raw res.status(500).
- Every new route gets an entry in docs/api-surface.md.

Globs use standard syntax and accept comma-separated lists (docs/**/*.md, docs/**/*.mdx). One sharp edge: the extension must be .mdc. A plain .md file dropped into .cursor/rules is ignored.

Two ways to create rules without hand-writing frontmatter: type /create-rule in Agent chat and describe what you want, and the agent generates the file with proper frontmatter into .cursor/rules; or simply ask the agent to write one after it has done a task the way you like. Rules generated from a real correction ("you did X wrong, here is the fix, now make that a rule") tend to be more precise than rules written from imagination.

AGENTS.md, the simpler alternative

Cursor also reads AGENTS.md, the cross-tool instruction file, from the project root and from subdirectories, with more specific locations taking precedence. It is plain markdown with no frontmatter and no activation types: everything in it applies. Use it when your instructions are short, universal, and shared with other tools that read the same file. Use .cursor/rules when you need scoping, because a 300-line AGENTS.md is an Always Apply rule wearing a different name, with all the cost that implies.

Migrating from .cursorrules

The original format was a single .cursorrules file in the project root. It has been superseded, and the current documentation no longer covers it at all, so treat it as legacy and migrate. The mechanical path:

1. Split .cursorrules by topic. A typical file mixes universal conventions, area-specific guidance, and step-by-step procedures.
2. Universal conventions become one .mdc with alwaysApply: true, kept brutally short, or move to AGENTS.md.
3. Area-specific guidance becomes scoped rules with globs.
4. Procedures ("how we do releases", "how to add a migration") should not become rules at all. That is skill territory, covered next, and Cursor's /migrate-to-skills command converts eligible dynamic rules into skills for you.
5. Delete .cursorrules once the split is committed, so nobody edits the dead file.

Rules versus skills: always-on context versus on-demand procedure

Cursor supports the Agent Skills open standard (agentskills.io). A skill is a folder under .cursor/skills or .agents/skills containing a SKILL.md with name and description frontmatter, plus optional scripts, references, and assets. The critical difference from rules is the loading model: the agent sees only each skill's name and description up front, and loads the full body when it judges the skill relevant or when you invoke it with /skill-name.

That gives you a clean division of labor:

• Rules are for how the agent should always behave. Constraints, conventions, prohibitions. "Never edit generated files under src/gen." Short, declarative, cheap enough to pay for on every request.
• Skills are for what the agent should do when a specific task comes up. Multi-step procedures with supporting scripts and reference files. "How to cut a release" as a 200-line runbook costs you nothing until release day.

The failure mode this prevents is real. Before skills existed, teams stuffed procedures into always-on rules because there was nowhere else to put them, and every "fix this typo" request carried the full weight of the deployment runbook. If a rule has numbered steps, it probably wants to be a skill. For a deeper treatment of the skill format itself, which Cursor shares with other agents, see our Claude Code skills guide.

Rule vs skill vs MCP: the decision table

The last row points at the boundary that trips people up most: instructions cannot grant abilities. A rule can tell the agent to do something; only a tool can make that something possible.

Rules for testing and verification workflows

Here is where the rule/capability boundary bites hardest in practice. A common and worthwhile rule: require the agent to verify UI changes before declaring them done.

---
description: Verify UI changes in a real browser before finishing
globs: app/**, src/components/**
alwaysApply: false
---

After modifying any UI code:
- Do not report done based on a successful compile.
- Open the affected page in the browser and exercise the change:
  click it, type into it, submit it.
- Confirm rendering and behavior match the intent of the change.
- If verification fails, fix the application code. Never weaken
  the check to make it pass.

That rule sets policy, and scoping it by glob means backend-only sessions never pay for it. But the policy is empty unless the agent can actually reach a browser, and that capability comes from MCP, not from the rule. Cursor's agent drives a browser only through an MCP server that exposes browser tools.

This is the layer Shiplight provides (Shiplight is our product). It installs into Cursor as a browser MCP server plus skills in one line, no account needed for local use. The rule above supplies the "always verify" policy; Shiplight supplies the eyes and hands, and its skills supply the procedure: /shiplight verify checks a change in a real browser, /shiplight create-yaml-tests turns verified behavior into intent-based YAML tests that live in your repo and transpile to standard Playwright, and /shiplight fix reports app bugs instead of rewriting tests to pass. Note how cleanly the work splits across all three mechanisms from the decision table. For the full setup, see the Cursor testing guide and the coding agents overview.

The honest section: rule bloat is the default failure mode

Rules fail by accumulation. Every Always Apply rule, and every glob rule matching the files you touch daily, spends tokens on every request. Past a point, more rules make the agent worse: instructions compete, the model's attention spreads thin, and responses drift generic. Cursor's own guidance is telling: keep rules focused, split large rules into composable pieces, reference files instead of pasting their contents, and do not duplicate style guides or document every command, because the model already knows common conventions. The docs cap guidance at 500 lines; in practice, treat your total always-on rule weight as the budget, and keep it far below that.

Rules are also the wrong fit when instructions are perishable (sprint-specific context belongs in the prompt), when they encode procedure (use a skill), and when they demand abilities the agent lacks (use MCP). A quarterly prune, deleting rules nobody can explain, is worth more than any new rule you might add. This is context engineering in miniature; the same budgeting logic applies across every agent you run, as covered in context engineering for coding agents.

Frequently Asked Questions

Related Reading

• Cursor testing guide: the full setup for browser verification and E2E testing inside Cursor.
• Claude Code skills: a deeper look at the skill format Cursor now shares.
• Context engineering for coding agents: the budgeting discipline behind the rule-bloat section.
• Cursor CLI: running Cursor's agent headless, where rules still apply.
• Claude Code vs Cursor: how the two agents compare on instructions, skills, and MCP support.

External references: Cursor docs, Rules and Cursor docs, Skills.