Rules, skills, subagents and hooks: which to use when

Last checked: 21 Oct 2026. The vendor facts below come from the Claude Code, Codex and Cursor documentation sites and from the Agent Skills and AGENTS.md standards pages, with the research studies linked where they are cited.

Claude Code, Codex and Cursor now give a team broadly the same four ways to guide a coding agent: instructions it reads every session, skills it loads when a task needs them, subagents that take work into a separate context, and hooks that the tool itself runs at fixed points. Use instructions for conventions, skills for repeatable procedures, subagents to keep bulky side work out of the main conversation, and hooks (with each tool's permission settings) for anything that has to happen every time. The names differ, and "rules" means something different in each tool, so agree the vocabulary before anyone writes a configuration file.

The four mechanisms, sorted by who decides to use them

Birgitta Böckeler of Thoughtworks, writing on martinfowler.com in Feb 2026, sorted coding-agent context by who triggers it: always loaded, loaded by the model, loaded by a person, or triggered by the agent software "at deterministic points in time". Her per-tool remarks have dated, but the sorting still fits all three tools.

The first three are read and interpreted by the model. Hooks are run by the software, and all three vendors draw that line themselves. Anthropic's memory documentation says Claude treats CLAUDE.md files as "context, not enforced configuration". Cursor's enterprise guidance says "rules are suggestions, not guarantees" and recommends combining them with enforcement hooks. OpenAI tells Codex users to pair AGENTS.md with "pre-commit hooks, linters, and type checkers".

What each tool calls them

The table maps each job to the file or feature name in each tool, as documented on 21 Oct 2026.

Sources: the Claude Code features overview, OpenAI's Codex import guide (which maps each mechanism from Claude Code and Cursor onto Codex) and Cursor's customisation overview.

"Rules" means three different things

In Claude Code, rules are instruction files in .claude/rules/. A rule can be scoped to file paths, and rules without paths load at launch like CLAUDE.md. They are context the model reads.

In Cursor, rules are the main persistent-instruction system. There are four types (project, user, team and AGENTS.md) and four ways a rule can apply: Always Apply, Apply Intelligently (the agent decides from the rule's description), Apply to Specific Files and Apply Manually. Only the first is always on, so a Cursor rule is not necessarily in context for every request.

In Codex, rules are a command policy. OpenAI's documentation says "Use rules to control which commands Codex can run outside the sandbox", and marks the feature as experimental. When several rules match, Codex applies the most restrictive decision. The Codex counterpart of a Cursor or Claude Code rule is AGENTS.md.

So when someone says "add it to the rules", ask which tool they mean.

Persistent instructions: CLAUDE.md, AGENTS.md and Cursor rules

Each tool loads a project instruction file before the agent starts work. Codex reads AGENTS.md files from the Codex home directory and then from the project root down, with closer files overriding earlier ones. The combined size is capped by a setting that defaults to 32 KiB. Claude Code uses CLAUDE.md and can read AGENTS.md instead, by default only when there is no CLAUDE.md in the working directory or above it. Cursor reads AGENTS.md as one of its rule types, and its CLI also reads CLAUDE.md at the project root. AGENTS.md itself is an open format now stewarded by the Agentic AI Foundation under the Linux Foundation.

All three vendors ask for these files to stay short. Anthropic says to "target under 200 lines per CLAUDE.md file" because longer files reduce adherence, and to move multi-step procedures and guidance for one part of the codebase into a skill or a path-scoped rule. OpenAI says of AGENTS.md: "Keep it small." Cursor says to keep rules under 500 lines and to "Start simple. Add rules only when you notice Agent making the same mistake repeatedly."

Published research supports keeping these files lean. A preprint by Gloaguen and colleagues (arXiv, version 3, 29 Sep 2026) tested context files on Python tasks with Claude Code, Codex and Qwen Code. It found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average". Repository overviews did not help, while instructions for non-standard practices were followed well. Cursor was not tested. A separate study of 2,303 real context files found security (14.8%) and performance (14.5%) are rarely specified. Our reading: write down what an agent cannot work out from the repository, such as unusual conventions and non-functional requirements, and leave out the tour of the codebase.

Skills: procedures the agent loads when it needs them

Skills are the one mechanism built on a shared format. The Agent Skills format was originally developed by Anthropic and released as an open standard. Claude Code, Codex and Cursor all document support for it: a skill is a folder with a SKILL.md file that carries a name and description, plus optional scripts and reference files. The agent sees the description and loads the body only when it is used.

Skills are absorbing older features. Claude Code says "Custom commands have been merged into skills." OpenAI says "Custom prompts are deprecated" and points users to skills. Each tool can also make a skill manual-only: disable-model-invocation in Claude Code and Cursor, and allow_implicit_invocation set to false in Codex.

We cover what a skill is in Claude Skills explained, so here are just two findings for engineering teams. The SkillsBench study (arXiv, version 4, 14 Jun 2026) found hand-curated skills raised the average pass rate from 33.9% to 50.5% across 87 tasks, while skills the model wrote for itself landed below the no-skills baseline in all three configurations tested. Focused procedural guidance beat exhaustive documentation, and software engineering was among the smallest gains. And a scan of public skills marketplaces (Liu and colleagues, Jan 2026) flagged 26.1% of 31,132 skills as containing at least one vulnerability using the authors' own scanner. Review a third-party skill as you would any other code before installing it.

Subagents: a separate context for side work

A subagent starts with a fresh context window, does one job and reports back, which keeps the main conversation clear. In Cursor's words: "The benefit is context isolation, not speed."

In Claude Code, each subagent has its own context window, system prompt, tool access and permissions, and Claude chooses one by its description. Subagents are Markdown files in .claude/agents/, with Explore, Plan and a general-purpose agent built in.

In Codex, custom agents are TOML files in .codex/agents/, each with a name, description and developer instructions. Custom agents inherit the parent's permissions, and OpenAI notes that instructions asking an agent to avoid edits "don't create a separate read-only sandbox."

In Cursor, subagents are Markdown files in .cursor/agents/. A readonly setting restricts file edits and state-changing commands. Subagents share the parent's checkout by default, so parallel subagents editing files can overwrite each other.

Subagents cost more. OpenAI says subagent workflows "consume more tokens than comparable single-agent runs", and Cursor estimates that five in parallel use roughly five times the tokens of one agent. Anthropic's guidance is to "Use a subagent when you need context isolation or when your context window is getting full." Cursor suggests a skill instead for simple, single-purpose tasks, and OpenAI advises more care with parallel work that writes files.

Hooks: scripts the tool runs on an event

Hooks are the only one of the four that runs whether or not the model thinks it should. Anthropic describes them as giving "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." Anthropic's own example is a hook that stops the agent editing a .env file, where an instruction saying "never edit .env" would only be "a request, not a guarantee". In all three tools a hook can block an action by exiting with code 2.

Each vendor qualifies its own hooks.

• Claude Code: Anthropic advises "If a rule must hold every time, make it a hook rather than a prompt instruction." Its hooks reference adds that, because one filtering option is best-effort, you should use the permission system for a hard allow or deny.
• Codex runs command and MCP tool handlers only. Hooks that are not admin-managed must be reviewed and trusted before they run, and a changed hook is skipped until it is trusted again. OpenAI's advice: "Treat tool hooks as a useful guardrail, not a complete enforcement boundary."
• Cursor supports command and prompt hooks. A hook that crashes or times out lets the action proceed by default, unless it is set to fail closed. Team-wide hook distribution is an Enterprise feature. Cursor also loads Claude Code hooks when a third-party import setting is on, which it is by default.

We cover Claude Code's managed settings, including a hook that blocks edits to a .env file, in how to set up Claude Code safely for a business team. Our view across all three: put a requirement in a hook and in the permission settings when it must hold, test that the hook actually blocks what you expect, and do not treat it as your only control, because none of the vendors describes hooks as a complete security boundary.

A decision guide

Anthropic publishes a Claude Code version of this guide in its features overview. This one applies across all three tools.

Every piece costs context or tokens (Anthropic says as much), so add one when a repeated problem calls for it and remove it when it stops helping.

One repository, three tools

Many teams use more than one of these tools on the same codebase, and the overlaps help. AGENTS.md is read by Codex and Cursor, and by Claude Code when there is no CLAUDE.md. Cursor loads skills from the Claude Code and Codex folders and loads Claude Code hooks. Codex can import an existing Claude Code or Cursor setup, though OpenAI's import guide lists hooks among the things to review afterwards because their behaviour may differ.

The overlaps are not complete: Codex documents .agents/skills for project skills and Claude Code's documentation lists only .claude/skills, so test each tool against the repository. For Cursor in more depth, see our Cursor rules, skills, subagents and hooks team setup guide. For Codex as a business dependency, see Codex: when a developer tool becomes a business dependency.

Whatever the mix, treat these files as code. Give them an owner, review changes in pull requests, and commit the project versions to the repository so that new starters, and cloud sessions in Claude Code and Cursor, get the same setup. All three tools can bundle these pieces as plugins, so review what a plugin installs before turning it on. If your team is standardising on one tool, our pages on Claude implementation, OpenAI and Codex implementation and Cursor and Grok implementation cover each in more depth.

Common questions

What is the difference between AGENTS.md, CLAUDE.md and Cursor rules?

All three are persistent instructions the agent reads before it works. Codex reads AGENTS.md, Cursor reads it as one of its rule types, and Claude Code reads it only when there is no CLAUDE.md. Cursor rules have four modes, and only Always Apply loads for every request. None of them is a hard control: the agent treats them as guidance.

Should I use a skill or a subagent?

Use a skill when the agent needs a procedure or reference material for a task and should carry it out in the main conversation. Use a subagent when the work would fill the main conversation with output you do not need, because a subagent starts with a fresh context and returns only its result. Subagents use more tokens.

Which of these enforces a rule, and which only asks?

Instruction files, rules and skills are read by the model, so they guide the agent without guaranteeing anything. Hooks are run by the tool on a lifecycle event and can block an action, which makes them the right place for requirements that must hold. Each vendor qualifies its hooks, so back them with permission settings: Cursor hooks, for example, let an action proceed by default if the hook fails.

Can one set of skills work across Claude Code, Codex and Cursor?

Partly. All three document support for the Agent Skills format, a folder with a SKILL.md file. Cursor also loads skills from the Claude Code and Codex folders, but no single folder is documented for all three tools, so test each one.

How long should an instruction file be?

Each vendor gives a different measure. Anthropic says to target under 200 lines per CLAUDE.md file, Cursor says to keep rules under 500 lines, and Codex caps the combined AGENTS.md content at 32 KiB by default. One study of context files found they are useful for recording non-standard conventions, and that general overviews of the repository did not help.

If you want help deciding what should sit in instructions, skills, subagents and hooks for your engineering team, Request a Quote through our AI implementation page.