Cursor rules, skills, subagents and hooks: a team setup guide

Last checked: 21 Oct 2026. The facts below come from Cursor's own documentation for rules, skills, subagents and hooks, its release notes and changelog, the Agent Skills specification and the published studies named in the text.

Use rules for short standing guidance, skills for a repeatable procedure the agent can pull in when it needs it, subagents when a job outgrows one context window or can run in parallel, and hooks for a control that has to run every time. A hook only stops something if it is written to deny the action and, where the control matters, set to fail closed. This guide sets out how each one loads, what it costs and where it lives, so an engineering lead can decide who owns it.

The four mechanisms side by side

Cursor lists rules, skills, subagents and hooks as separate ways to customise how its Agent works.

Rules: short standing guidance

Cursor supports four kinds of rule. Project Rules sit in .cursor/rules and are version-controlled with the code. User Rules follow one person across projects. Team Rules are managed from the dashboard on Teams and Enterprise plans. AGENTS.md is a plain markdown alternative that can sit at the repository root or in subfolders, with the more specific file taking precedence.

Rules are often described as always on, which is true of only one of four modes. A rule can be applied to every chat, applied when the agent judges its description relevant, attached when a file matching a pattern is in context, or used only when someone @-mentions it. CLAUDE.md is the exception: Cursor reads it like AGENTS.md and applies it to every conversation.

Project rule files must use the .mdc extension, and a plain .md file in .cursor/rules is ignored. A file mentioned inside a rule is not pasted into the prompt, so anything that must always be present has to be in the rule body. And rules only steer Agent chat: Tab completion, Inline Edit and Bugbot pull request reviews ignore them, and Bugbot has its own review rules.

What to put in a rule, and what to leave out

Our advice is to keep rules short and specific, and to treat each one as a cost every conversation pays. Cursor's own guidance points the same way. Its guide to customising agents says rules "add up" and asks teams to add one only when they notice the agent making the same mistake repeatedly. The rules documentation sets an upper bound of 500 lines, and says to use a linter rather than pasting in a style guide, because the agent already knows common conventions. A rule written after the third time the agent ran the wrong test command earns its place. One written in advance, for a problem nobody has seen, does not.

Cursor publishes no token figure for rules, but you can measure your own: a context usage report added in June 2026 shows where tokens go across the system prompt, tool definitions, rules and skills. A preprint by Gloaguen and colleagues (version 3, 29 Sep 2026) found that AGENTS.md-style context files did not generally improve task success and raised inference cost by over 20% on average, while still being useful for non-standard coding practices. It tested other coding agents on Python tasks, not Cursor, but the lesson carries over: record what is unusual about your codebase and nothing more.

Skills: repeatable procedures the agent pulls in

A skill is a portable, version-controlled package that teaches the agent a particular task. It is a folder with a SKILL.md file and optional scripts/, references/ and assets/ folders. Skills follow the open Agent Skills specification, so Cursor also loads skills from Claude and Codex folders. Our post on governing Claude Skills across a firm covers the Claude side.

By default the agent sees the list of available skills and decides when one is relevant. A person can also invoke a skill by typing / in Agent chat. Setting disable-model-invocation: true makes a skill manual-only, paths scopes it to matching files, and a skill can be kept on for a session as a Custom Mode. Because the detail loads only when used, a skill costs less context than an always-on rule. The specification (not Cursor) suggests roughly 100 tokens per skill for the name and description, loaded at startup, and a body under 5,000 tokens.

Use a skill when the agent needs a detailed, repeatable process, such as cutting a release or running a migration checklist. Cursor's help pages draw the line the same way: a rule when a short instruction is enough, a skill when Agent needs a process to follow. Commit skills to the repository. Cursor's docs say unsynced local skills are not copied into Cloud Agents, remote sessions or self-hosted workers, so a skill on one laptop does not reach the rest of the team's environments.

Subagents: when the work outgrows one context

A subagent is a separate assistant the main agent delegates to. It runs in its own context window, starts with only what the parent passes it, and returns its result to the parent. It can run in the foreground or the background, and several can run at once.

Cursor is direct about the cost: "Running five subagents in parallel uses roughly five times the tokens of a single agent." A subagent can also be slower than the main agent on a simple task because it starts fresh. Use one for long research, parallel workstreams or an independent check of finished work. For a single-purpose job such as formatting imports, Cursor's docs suggest a skill instead, and they advise starting with two or three focused subagents with well-written descriptions, because the description is how the main agent decides when to delegate.

Custom subagents are markdown files in .cursor/agents/. Three settings matter for a team:

• readonly stops a subagent editing files or running state-changing shell commands.
• Parallel edits share one checkout by default, so subagents editing at once can overwrite each other. Ask for isolation and each works in its own copy of the project.
• model defaults to the parent's model. Pinning a named third-party model can change what a run costs, because each request bills at the list price of the model that ran.

Custom subagents also cost context before they run. A user on Cursor's community forum reported in May 2026 about 11,400 tokens at the start of a chat with 60 or more custom subagents, against about 1,400 with them removed, and a forum reply said every subagent's name and description is loaded so the agent knows who it can delegate to. That may change, but it is another reason to keep the set small.

Hooks: controls that must run every time

Hooks are scripts that observe, block or modify the agent loop at defined points. Cursor's listed uses include running a formatter after edits, scanning for secrets and gating risky operations such as database writes. Events include beforeShellExecution, afterFileEdit and beforeReadFile, which can keep sensitive files away from the model.

Cursor's page on safety and controls says the model will attempt to follow rules but "rules are suggestions, not guarantees", and recommends enforcement hooks for requirements that must be followed, such as blocking git push or database DROP statements. Users do report the agent skipping rule and skill files.

The same page calls hook-based controls "deterministic enforcement", which needs a qualification. A command hook runs your code every time its event fires, but it blocks only if it returns a deny or exits with code 2. The hooks reference says crashes, timeouts and other exit codes fail open by default, so the action goes through. Set failClosed: true on any hook that enforces a control, test that it denies what it should, and avoid prompt-based hooks for hard controls, because they ask a model to judge. Cursor's rules documentation also says AI guidance should not be your only security control.

Hooks can be defined at four levels, in this order of priority:

• Enterprise: a system-wide hooks.json at an operating-system path, deployed by your own device management.
• Team: configured in Cursor's web dashboard and synced to members, on Enterprise only.
• Project: .cursor/hooks.json in the repository, run in any trusted workspace.
• User: ~/.cursor/hooks.json on one person's machine.

Every matching hook from every level runs, and a deny from any of them overrides an allow. Cloud agents run command hooks from the repository but not user-level hooks, skip hooks during read-only early turns, and do not yet support session or MCP hooks, so controls that must cover Cursor's cloud agents and automations belong in the repository. Cursor can also run hooks written for Claude Code, and our guide to setting up Claude Code for a business team makes the same case for hooks over written instructions.

Treat the configuration folder as code

For a team, rules, skills, subagent definitions and hook files change what the agent does for everyone, and two of them can run code. Our view is that every change to .cursor/, AGENTS.md and the skills folders should go through a pull request with a named owner, like a change to CI.

The evidence supports that. A January 2026 study of more than 31,000 skills from two public skill marketplaces (not Cursor's) found that 26.1% had at least one vulnerability, and that skills bundling scripts were about twice as likely to. Hook files can run commands too: a vulnerability published in June 2026 let Cursor versions before 3.0.0 run hook commands from a workspace file without dedicated approval. It is fixed. Review hook changes as code and keep Cursor up to date.

Sharing the setup, and what it needs

Anything committed to the repository is shared with everyone who works in it. The pages we checked state no plan requirement for project rules, AGENTS.md, skills, subagents or project hooks. Central control depends on plan, according to Cursor's enterprise documentation:

• Team Rules are on Teams and Enterprise, and an admin can make one required so members cannot switch it off. Since September 2026, Team Rules scoped to a file pattern apply only when a matching file is in context.
• Team marketplaces for sharing rules, skills and plugins are on Teams (one) and Enterprise (unlimited).
• Hooks can be shared through the repository or your own device management on Teams. Dashboard distribution is Enterprise.

Cursor's plans changed on 12 Oct 2026, when it began selling Cursor as part of The X Subscription, one subscription for Grok, Cursor and X. Check the models and pricing page before choosing a plan. Our guide to SpaceX Super Intelligence (SpaceXSI) for UK business explains how Cursor, Grok and Grok Bot fit together, following Cursor's acquisition by SpaceX in August 2026.

Where we would start

We use Cursor in our own engineering, and the order we suggest is simple. Commit a short AGENTS.md or one Always Apply rule with the build and test commands and a pointer to your linter configuration. Add scoped rules only as repeated mistakes appear. Turn the procedures people keep explaining to the agent into skills in the repository. Write two or three read-only subagents for review and research before any that edit code. Put the controls that must not fail, such as secrets, destructive commands and production access, into project hooks set to fail closed. Ownership and sequencing are covered in our guide to rolling out Cursor to an engineering team, and the same four ideas across Claude Code, Codex and Cursor are in rules, skills, subagents and hooks: which to use when.

Common questions

What is the difference between Cursor rules and skills?

A rule is a short written instruction that, depending on its mode, is applied to every chat, attached when matching files are in context, pulled in when the agent judges it relevant, or used only when mentioned. A skill is a packaged procedure whose detail loads only when the agent or a person invokes it. Use a rule when a short instruction is enough and a skill when the agent needs a repeatable process.

Can Cursor ignore a rule, and what stops it?

Yes. Cursor's documentation says rules are suggestions to the model and not guarantees. For something that must happen every time, use a command hook that denies the action or exits with code 2, and set it to fail closed, because by default a hook that crashes or times out lets the action through.

When should I use a Cursor subagent instead of the main agent?

Use a subagent for long research that would flood the main conversation, for workstreams that can run in parallel, or for an independent check. Each subagent has its own context window and uses its own tokens, so five in parallel use roughly five times the tokens of one agent. For a simple single-purpose task, a skill is usually the better fit.

Which Cursor plan do I need to share rules and hooks across a team?

Anything committed to the repository is shared with everyone who works in it. Enforceable Team Rules and team marketplaces need a Teams or Enterprise plan. Distributing hooks from Cursor's dashboard needs Enterprise, while Teams customers can share hooks through the repository or their own device management. Cursor's plans changed on 12 Oct 2026, so check its current pricing page.

If you want a view of how your team's Cursor setup should look before you commit to a plan, start with a diagnostic, or see our SpaceXSI and Cursor implementation service and Request a Quote.

John Kelleher holds the SpaceX Super Intelligence Partner Network Accreditation: Forward Deployed Engineer.