Rules, agents and hooks: what they do and where to put them

Rules, agents and hooks are three ways to steer a coding agent without retyping your instructions every session. Rules say how to work, agents (or subagents) hand a task to a specialised assistant, and hooks run your own commands at set moments. Each tool keeps them in its own place.

Rules: instructions that stay

A rule is a text file the agent reads at the start of its work: code conventions, test commands, files never to touch. It applies all the time, or only for certain files.

• Claude Code: CLAUDE.md at the project root (or .claude/CLAUDE.md), ~/.claude/CLAUDE.md for your personal preferences, CLAUDE.local.md for local settings. To split instructions across files, use the .claude/rules/ folder, whose files can be limited to certain paths.
• Cursor: .mdc files in .cursor/rules/. A plain .md file in that folder is ignored. The file header sets when the rule applies: alwaysApply, globs (a file pattern) or description (the agent decides whether it is relevant).
• Codex: AGENTS.md, global in ~/.codex/, then at the repository root and in subfolders. Files closest to the working directory come last and take precedence. By default Codex stops reading once the combined files reach 32 KiB.

AGENTS.md works as a shared file: Cursor reads it at the root and in subfolders, and Claude Code reads it as project instructions. If your repository already has a CLAUDE.md, add @AGENTS.md to import the shared file, then put Claude-specific instructions below it.

Agents: a specialised assistant

A subagent works in its own context, with its own instructions and a limited set of tools, and returns only a summary. That keeps searches and logs out of your main conversation. Define one when you often hand over the same kind of task (review, debugging, read-only queries).

• Claude Code: a Markdown file with YAML frontmatter (name, description, often tools and model) in .claude/agents/ for the project, or ~/.claude/agents/ for all your projects. Claude decides whether to delegate from the description, so keep it short and precise.
• Cursor: Markdown files in .cursor/agents/ or ~/.cursor/agents/. Cursor also reads .claude/agents/, for compatibility.
• Codex: TOML files in .codex/agents/ or ~/.codex/agents/, with name, description and developer_instructions. Codex delegates when you ask, or when an AGENTS.md or a skill calls for it.

Hooks: your commands at set moments

A hook runs an action when an event happens: before or after a tool, at session start, when the agent finishes replying. Use one to block a dangerous command, run a formatter after each edit, or log what the agent does.

In Claude Code, hooks are declared in settings files: .claude/settings.json (project, shareable), .claude/settings.local.json (local) or ~/.claude/settings.json (all your projects). Example: block certain Bash commands with a script you write and review yourself.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh" }
        ]
      }
    ]
  }
}

The script receives the event data as JSON on standard input and answers with its exit code: 0 raises no objection, 2 blocks the action and its error message goes back to Claude. The /hooks command lists what is configured.

Cursor reads .cursor/hooks.json (project) or ~/.cursor/hooks.json (user), with events such as beforeShellExecution or afterFileEdit. For Codex, see its official documentation.

How is this different from a skill?

A rule and a skill are text the model reads. A hook is code that runs next to the model. For the same idea in more depth, see Resource or plain prompt? and the rules catalog.

Precautions with hooks

A command hook runs on your machine, with your permissions, without you approving it each time. Treat it like a script.

• Read the command and the script in full before enabling it, especially if it comes from someone else.
• Be wary of project hooks: they are versioned with the repository. Cursor itself warns that project hooks run in any trusted workspace. Review .claude/settings.json and .cursor/hooks.json after cloning an unfamiliar repository.
• Start with a hook that only logs, then add blocking.
• To enforce a strict ban, prefer the tool's permission rules: the Claude Code documentation notes that hook filtering is best-effort.
• Hooks on the same event run in parallel. A deny does not stop another hook's side effects.

The catalog does not accept third-party resources that ship scripts (only PalateKit's own house resources contain some, written and reviewed by us), and installing a PalateKit resource runs nothing. For the rest of the routine, read Safety: read a skill before you install it.