# Cursor rules vs AGENTS.md vs skills vs subagents: which one should you use?

Canonical: https://clawdocx.com/blog/cursor-rules-vs-agents-md-vs-skills
Author: Theo Marsh
Published: 2026-10-15
Updated: 2026-10-15

> Cursor has four ways to steer its agent: .mdc rules, AGENTS.md, skills and subagents. What each one loads, when it loads, and which to reach for.

Use a **rule** for standing instructions the agent should not have to decide about, a **skill** for a self-contained job it should pick up only when the task calls for it, a **subagent** when the work would otherwise flood your main context, and a **hook** when you need something enforced rather than suggested. The quickest way to tell rules and skills apart: a rule is text Cursor places at the start of the model context when its trigger matches, while a skill is a folder the agent is merely told about and chooses to open. If you only remember one file fact, make it this one: a plain `.md` file in `.cursor/rules` is ignored, because project rules must carry the `.mdc` extension.

## What are the four mechanisms, side by side?

| Mechanism | File and location | When it loads | Best for |
|---|---|---|---|
| Project rule | `.mdc` file in `.cursor/rules/` | By frontmatter: always, on a `globs` match, when the agent reads its `description`, or on `@`-mention | Conventions and architecture decisions that apply to a known part of the codebase |
| AGENTS.md | `AGENTS.md` in the project root or any subdirectory | Applied for work in that directory and its children, combined with parent files | Short, readable project instructions with no frontmatter overhead |
| User rule | Customize in the sidebar, or files in `~/.cursor/rules` | Across all your projects, in Agent (Chat) | Personal style preferences that should not live in a shared repository |
| Team rule | The Cursor dashboard, on Team and Enterprise plans | Across all repositories for the team, optionally scoped by glob | Organisation standards you do not want each person to set up |
| Skill | `SKILL.md` in a folder under `.agents/skills/` or `.cursor/skills/` | The agent decides from the `description`, or you type `/skill-name` | A repeatable task with its own steps, scripts or templates |
| Subagent | Markdown file in `.cursor/agents/` | The agent delegates to it, or you invoke it | Long research, parallel work, independent verification |
| Hook | `hooks.json` in `.cursor/` or `~/.cursor/` | Before or after defined stages of the agent loop | Formatting, secret scanning, gating risky operations |

The first four rows are all "rules" in Cursor's vocabulary, which is the overloading this page is here to unpick. Cursor's rules reference lists exactly four types of rule: project rules, user rules, team rules and `AGENTS.md`. A skill, a subagent and a hook are three further mechanisms that sit outside that list.

## When does each one actually load?

This is the question that separates the four, and rules are the only one where you control the answer directly. The rules reference describes rule content as being "included at the start of the model context" when a rule applies, and three frontmatter fields decide when that happens:

| `alwaysApply` | `description` | `globs` | Behaviour |
|---|---|---|---|
| `true` | ignored | ignored | Always included |
| `false` | absent | provided | Auto-attached when a matching file is in context |
| `false` | provided | omitted | The agent reads the description and pulls the rule in when relevant |
| `false` | omitted | omitted | Included only when you `@`-mention the rule in chat |

In the Cursor interface those four rows are the type dropdown: Always Apply, Apply to Specific Files, Apply Intelligently and Apply Manually. Both Cursor pages give the same first thing to check when a rule does not seem to apply: the rule type, and for Apply Intelligently whether a `description` is defined at all, since without one the agent has nothing to judge relevance against.

Skills load on a different principle. Cursor discovers them at startup from the skill directories and, in the documentation's words, "the agent is presented with available skills and decides when they are relevant based on context". You can force the issue by typing `/` in chat and picking one, and the docs note that a skill invoked that way "attaches to one message"; to keep it on for a whole session you promote it to a Custom Mode with Option and Enter on a Mac, or Alt and Enter on Windows. Setting `disable-model-invocation: true` in a skill's frontmatter turns off the automatic half entirely, so the skill behaves like a traditional slash command.

Subagents load when work is delegated to them, and the important detail is what they do not get. Each one "operates in its own context window", and the docs are explicit that "subagents start with a clean context" and "don't have access to prior conversation history", so the parent agent has to pass anything they need. Hooks are different in kind again: they are "spawned processes that communicate over stdio using JSON in both directions", running before or after stages of the agent loop rather than contributing instructions to it.

## Rules or skills: how do you choose?

Start with the trigger you want, not with the content.

- **You want it in context every time.** That is a rule with `alwaysApply: true`, or an `AGENTS.md`. A skill cannot promise this, because the agent decides.
- **You want it only for certain files.** Both can do it. A rule uses `globs`; a skill uses the optional `paths` field, which the skills documentation says scopes a skill so that it "is only surfaced when the agent works with files that match".
- **You want the agent to judge.** A rule with a `description` and `alwaysApply: false` and a skill with a good `description` are nearly the same thing at this point. The difference is what they can carry.
- **The task needs more than prose.** Only a skill is a folder. Alongside `SKILL.md` it can hold `scripts/`, `references/` and `assets/`, which the agent acts on with its tools. A rule is one file of instructions.

That last point is the dividing line Cursor draws in its own tooling: the built-in `/migrate-to-skills` skill converts "dynamic rules", meaning rules with `alwaysApply` false or undefined and no `globs`, into skills, and converts slash commands into skills with `disable-model-invocation: true`. Rules with `alwaysApply: true` or specific `globs` are deliberately left alone, because, as the docs put it, "they have explicit triggering conditions that differ from skill behavior". User rules are not migrated either, since they are not stored on the file system.

One more thing worth knowing before you move guidance into a rule: file references do not inline. The rules reference says a mention like `@migration-template.sql` tells the agent where to look and it "reads the file with its tools when it needs the content", that "the file's contents are not inlined into the prompt", and that this behaves the same way "in the editor, the CLI, and Cloud Agents". So anything that genuinely must always be present belongs in the rule body, not behind a reference. Cursor also advises keeping rules under 500 lines and splitting larger ones.

## What about AGENTS.md, CLAUDE.md and the legacy .cursorrules?

`AGENTS.md` is the plain-markdown path. Cursor describes it as "a simple markdown file for defining agent instructions", placed "in your project root as an alternative to `.cursor/rules` for straightforward use cases", with no metadata or frontmatter. Nested files are supported in any subdirectory, and instructions "are combined with parent directories, with more specific instructions taking precedence". If your project already has an `AGENTS.md` written for another agent, Cursor will use it as it stands.

`CLAUDE.md` is handled too, and with one behaviour that will catch people out. Cursor's help page says it reads `CLAUDE.md` "the same way it reads `AGENTS.md`", and then adds that these files "are always applied to every conversation, regardless of any `alwaysApply` frontmatter setting", explicitly for compatibility with projects that also use Claude Code. In other words, you cannot make a `CLAUDE.md` conditional in Cursor; if you need conditions, the docs send you to `.cursor/rules`. Our [guide to CLAUDE.md in Claude Code](/blog/claude-code-memory-claude-md-guide) covers what that file is doing on the other side.

The legacy file is `.cursorrules` in the project root, and here the two Cursor pages differ in how much they say. The rules reference does not mention it at all. The rules help page does, calling it "legacy and will be deprecated" and giving the migration: create a new rule from the command palette, copy the `.cursorrules` content into it, set the type to **Always Apply** because that "matches the old behavior", and delete the old file. This article follows the help page, since it is the only one of the two that addresses the file, and notes that neither page gives a removal date. If you still have a `.cursorrules`, treat it as working but on notice.

Skills bring their own compatibility story, which matters if you share a repository across tools. Cursor loads skills from `.agents/skills/` and `.cursor/skills/` at project level and `~/.agents/skills/` and `~/.cursor/skills/` for your user, and "for compatibility" also from `.claude/skills/`, `.codex/skills/`, `~/.claude/skills/` and `~/.codex/skills/`. Subagents follow the same pattern with `.cursor/agents/`, `.claude/agents/` and `.codex/agents/`, where `.cursor/` wins when names collide. If you are deciding where a shared skill should live, our [guide to where skills go](/docs/agent-skills-where-skills-go) compares the directories across tools, and [skills explained](/docs/skills-explained) covers the format itself.

## What do subagents and hooks add?

Subagents are about context, not capability. Cursor ships two of them, Explore and Browser, and says both exist because the work they do "generates noisy intermediate output" that would otherwise fill the main context window. They run in the foreground, blocking until they return, or in the background. A custom one is a markdown file with frontmatter: `name`, `description`, `model` (defaulting to `inherit`), `readonly`, which when `true` means "no file edits, no state-changing shell commands", and `is_background`.

Cursor publishes its own rule of thumb, and it is worth quoting rather than paraphrasing. Use subagents when you need context isolation for long research, when running workstreams in parallel, when the task needs specialised expertise across many steps, or when you want independent verification. Use skills when the task is single-purpose, when you want a quick repeatable action, when it completes in one shot, or when you do not need a separate context window. The docs add that if you are reaching for a subagent to "generate a changelog" or "format imports", a skill is the better fit.

Hooks are the only mechanism on this list that can say no. They run before or after defined stages of the agent loop and can "observe, block, or modify behavior", with documented uses including running formatters after edits, scanning for secrets and gating risky operations. Where several hooks respond, Cursor merges the answers so that "any `deny` wins over `ask`, and `ask` wins over `allow`", whatever the source. Two limits are worth knowing before you plan around them: Cloud Agents load project, team and enterprise hooks but not your user-level `~/.cursor/hooks.json`, and they run command-based hooks only.

Nothing here is a security control on its own. Cursor says as much about enforced team rules, noting that AI guidance "should not be your only security control", and the same caution applies to anything you install from someone else. If you are pulling in a third-party skill, read our [skill security audit](/docs/skill-security-audit) first, and note that bringing rules or skills in from a GitHub repository is not a copy-and-go operation in Cursor: both have to be packaged in a plugin and published through a marketplace.

## What should you do today?

- **Audit `.cursor/rules` for `.md` files.** Any that are there are doing nothing. Rename to `.mdc` and add frontmatter, or move the content to `AGENTS.md`.
- **Check every Apply Intelligently rule has a `description`.** Without one there is nothing for the agent to match on, which is the first thing both Cursor pages tell you to check.
- **Run `/migrate-to-skills`** if you have accumulated dynamic rules and slash commands, then review what lands in `.cursor/skills/` rather than assuming the conversion was right.
- **Move anything with scripts or templates into a skill.** A rule that tells the agent to go and read four files is a skill that has not been written yet.
- **Retire `.cursorrules`.** It still works, it is documented as legacy, and the migration is four steps.

For how Cursor compares with the other agent IDEs, see our [Claude Code vs Cursor vs Copilot comparison](/blog/claude-code-vs-cursor-vs-copilot-2026), and the [Cursor platform hub](/ai-agents/cursor) for the current pricing and availability facts. Everything above was checked against Cursor's own documentation on 15 October 2026.

## Frequently asked questions

**What is the difference between Cursor rules and skills?**

A rule is instruction text that Cursor puts at the start of the model context whenever its trigger matches, and its trigger is set by frontmatter: always, by file pattern, by the agent reading a description, or only when you @-mention it. A skill is a folder containing a SKILL.md that the agent is told about and loads only when it judges the task relevant, and which can carry scripts, references and assets alongside the instructions.

**Why is my .md file in .cursor/rules being ignored?**

Because project rules must use the .mdc extension. Cursor's documentation says a plain .md file in .cursor/rules "is ignored by the rules system because it has no frontmatter to specify description, globs, and alwaysApply". If you want plain markdown with no frontmatter, use AGENTS.md in the project root instead.

**Does Cursor still support .cursorrules?**

Cursor's rules help page calls the project-root .cursorrules file "legacy and will be deprecated" and gives four migration steps: create a new rule from the command palette, copy the content across, set the rule type to Always Apply to match the old behaviour, and delete the old file. The main rules reference does not mention the file at all.

**Does Cursor read CLAUDE.md?**

Yes. Cursor's help page says it reads CLAUDE.md files the same way it reads AGENTS.md, and that CLAUDE.md files "are always applied to every conversation, regardless of any alwaysApply frontmatter setting". If you need conditional instructions, the docs point you at project rules in .cursor/rules instead.

**When should I use a subagent rather than a skill?**

Cursor's own guidance is that subagents are for context isolation on long research tasks, parallel workstreams, multi-step specialised work and independent verification, while skills are for single-purpose, one-shot, repeatable actions that do not need a separate context window. The docs say that if you are creating a subagent for something like generating a changelog, use a skill instead.

**Do Cursor rules affect Tab completion?**

No. The rules reference says rules do not impact Cursor Tab or other AI features, and the help page is more specific: rules apply only to Agent (Chat), not to Tab completion, Inline Edit, or Bugbot pull request reviews.

## Sources

- [Cursor docs: Rules](https://cursor.com/docs/rules)
- [Cursor docs: Agent Skills](https://cursor.com/docs/skills)
- [Cursor docs: Subagents](https://cursor.com/docs/subagents)
- [Cursor docs: Hooks](https://cursor.com/docs/hooks)
- [Cursor help: Rules](https://cursor.com/help/customization/rules)