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

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 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 compares the directories across tools, and 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 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, and the Cursor platform hub for the current pricing and availability facts. Everything above was checked against Cursor's own documentation on 15 October 2026.