Claude Code gives you seven ways to change how it behaves, and most confusion about them clears up with one question: who pulls the trigger? The model, you, or the program itself. Answer that and the choice between a skill, a subagent and a hook is usually made.

The short version
  • CLAUDE.md is always-on context. It loads every session and costs tokens on every request. Facts and standing rules go here.
  • A skill is on-demand instructions. The model loads it when a task matches the description, or you type /name. It runs in your conversation.
  • A subagent is a separate worker. Own context window, returns a summary. It buys isolation and costs a second set of tokens.
  • A hook is the only one that is deterministic. Claude Code runs it at an event whether or not the model agrees. Guardrails belong here.
  • MCP adds tools; it does not add judgement. A plugin is packaging for all of the above.
  • Our evidence: a rule about shared git checkouts sat in written guidance for months and still failed. The same day, it became a hook.

The mechanics below were checked against Anthropic's Claude Code documentation on 18 November 2026. Feature names and limits in this area change quickly, so treat version-specific details as true "as of November 2026". The examples are from our own configuration, with one client's name removed. For the wider context, see AI agents explained.

The question that sorts everything: who triggers it?

Every extension mechanism in Claude Code is started by one of three parties.

The harness. Claude Code, the program, does it at a fixed point with no decision involved. CLAUDE.md is loaded at session start. A hook fires on its event. MCP servers connect at startup.

The model. Claude decides, mid-task, that something is relevant. It loads a skill whose description matches. It delegates to a subagent. It calls an MCP tool.

You. You type /deploy, or you ask for a subagent by name.

the harnessfixed points, no decisionCLAUDE.mdloaded at session starthooksfire on their eventMCP serversconnect at startupthe modeldecides mid-taskskillsloads one whose descriptionmatchessubagentsdelegates a taskMCP toolscalls oneyouby typing or asking/deploya skill, invoked by namea named subagentasked for directlyHarness-triggered: rigid and reliable. Model-triggered: flexible, and can be wrong.
Who triggers each mechanism. After Anthropic's extension overview.

Model-triggered mechanisms are flexible and can be wrong. The model may not load the skill, or may load it and drift from it. Harness-triggered mechanisms are rigid and reliable. Anthropic's extension overview draws the line itself: a hook "fires on its event without Claude deciding", while with a skill "Claude interprets the instructions; outcome can vary."

So before asking "which feature?", ask "do I need this to happen every time, or do I need judgement applied?" Those are different tools.

Claude Code skills vs subagents vs hooks: the decision table

Mechanism What it is Who triggers it Where it lives Context cost Wrong tool when
CLAUDE.md A Markdown file of standing instructions Harness, at session start ~/.claude/CLAUDE.md, ./CLAUDE.md, ./CLAUDE.local.md Full file, every request The content is a long procedure, or a rule that must never be broken
Skill A folder with SKILL.md: instructions, optional scripts Model (description match) or you (/name) ~/.claude/skills/<name>/, .claude/skills/<name>/ Description every request; body when used It must run every time, or its output would flood the conversation
Slash command Now the same thing as a skill You, by typing it .claude/commands/*.md (older format, still works) As a skill You need supporting files; convert it to a skill
Subagent A worker with its own context, prompt and tools Model (delegation) or you (by name) ~/.claude/agents/*.md, .claude/agents/*.md Separate window; only the summary returns The task is small, or needs back-and-forth with you
Hook A command, HTTP request, prompt or agent run at a lifecycle event Harness, deterministically hooks block in a settings.json file Zero, unless it returns output The decision needs reasoning about context
MCP server A connection that gives Claude external tools and data Harness connects; model calls the tools .mcp.json (project) or ~/.claude.json (local, user) Tool names at start; full schemas on demand You only need to tell Claude how to do something it can already do
Plugin A package of skills, subagents, hooks and MCP servers You install it; its parts trigger as above ~/.claude/plugins/, enabled in settings Sum of its parts, in every session You need one skill on one machine

One more row exists that we mention only briefly. A dynamic workflow is a script Claude writes that runs many subagents; the workflow docs say the difference from a skill is "who holds the plan". With a skill, Claude does. With a workflow, the script does.

The sections below take each row in the order most teams should add them.

CLAUDE.md: what Claude should always know

CLAUDE.md is the cheapest thing to create and the most expensive thing to bloat. It loads in full at the start of every session, at up to four levels: an organisation's managed policy, your user file at ~/.claude/CLAUDE.md, the project file, and a personal CLAUDE.local.md. All of them stack.

Two facts from the memory docs set its limits. First, size: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Second, authority: "Claude treats CLAUDE.md files as context, not enforced configuration." The file is delivered as a message, and the docs admit "there's no guarantee of strict compliance."

Our own global file is a set of operating standards: verify claims against live systems, confirm before spending money or pushing to production, sweep the whole repo before calling a rename finished. Those are judgement rules. They belong in CLAUDE.md precisely because they need interpretation in situations nobody listed in advance.

Right when: it is a fact or a convention every session needs. Build commands, naming rules, "we use pnpm".

Wrong when: it is a 60-line procedure used once a week (make it a skill), or a rule where one failure is expensive (make it a hook). If the file keeps growing, that is usually the sign that part of it wants to be one of the next two mechanisms.

Skills: procedures the model picks up when relevant

A skill is a folder containing SKILL.md. At session start, Claude sees only each skill's name and description. The body loads when the model judges a description relevant or when you type /skill-name. The docs summarise the trade: a skill's cost is "low", descriptions on every request and "full content when used".

We keep 21 skill folders in ~/.claude/skills/ and have 11 switched off, because every listed description is a standing cost and overlapping descriptions make the model pick badly. One that stays on holds our browser-testing patterns. It would be absurd in CLAUDE.md, where its 193 lines would ride along with every question about a CSV file. As a skill, it costs one description until someone asks whether a page actually works.

A skill can also be marked so only you can run it, with disable-model-invocation: true. At that point it is a slash command in the old sense, and the docs confirm the merger: "Custom commands have been merged into skills." A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy.

Right when: you have pasted the same checklist into chat three times, or a section of CLAUDE.md has turned into a procedure.

Wrong when: the rule has to hold on every single tool call. A skill's body is read once when invoked, and the docs describe what to do when "Claude skipped a rule that must hold every time": move it into a hook. Writing one is covered step by step in our Claude skills guide.

Subagents: isolation, bought with tokens

A subagent is a Markdown file with YAML frontmatter, stored in .claude/agents/ or ~/.claude/agents/. The frontmatter names it, describes when to use it, and can restrict its tools and model. The body becomes its system prompt. The docs' example:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Claude delegates to one based on its description, or you ask for it by name. The subagent works in a fresh context window and hands back a summary. That is the entire value: the forty files it read never enter your conversation.

It is also the entire cost. The subagent docs note that a subagent "starts fresh and may need time to gather context", and advise staying in the main conversation when "the task needs frequent back-and-forth" or "you're making a quick, targeted change."

We learned the cost side directly, and wrote it into our global instruction file. The section is headed "Delegation" and its first line reads: "Subagents multiply cost and latency — each one re-establishes context, re-explores, reports back, and then you re-read the report." The rules under it:

  • Delegate only for work that is large, independent and can run in parallel.
  • Do not delegate what could be finished in a handful of tool calls.
  • Do not use a subagent to double-check your own work.
  • Once you delegate, commit to it. Do not redo the subagent's work.

Notice where those rules live. They are judgement calls about when delegation pays, so they sit in CLAUDE.md, not in a hook. A hook cannot tell a large task from a small one.

Right when: a side task would bury your conversation in output, several independent tracks can run at once, or a worker should be limited to read-only tools.

Wrong when: you could do it yourself in five tool calls. Our longer guide to Claude Code subagents covers definitions, tool limits and running them in the background.

Skills and subagents combine, which is why the comparison confuses people. A skill with context: fork in its frontmatter runs inside a subagent. A subagent with a skills: field starts with those skills fully loaded. One is content, the other is a place to run it.

Hooks: the only mechanism that does not ask the model

A hook is configuration, not prose. You add a hooks block to a settings file, pick an event, and give it a command. Claude Code runs that command when the event occurs. As of November 2026 the documented events include SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SubagentStop, PreCompact and SessionEnd, among others.

For a PreToolUse hook on the Bash tool, Claude Code passes a JSON object on stdin that includes the working directory and the command about to run. The hook answers with its exit code. From the hooks guide: exit 0 means no objection, and exit 2 blocks the action, with whatever the hook wrote to stderr sent back to Claude as the reason. The cost in context is nothing unless the hook returns output.

Here is why we have one.

A rule that lived as guidance, and failed anyway

We often run several Claude Code sessions at once. When two sessions share one git checkout, they share one staging area. On 20 August 2026 that bit us three times in a day on our own site's repository. The worst was a git add -A in one session that swept another session's unfinished files into a commit, which then merged and deployed without review.

We wrote the lesson down as a rule in the agent's memory: never git add -A in a shared tree; stage explicit paths. Good rule, clearly worded, loaded into every session.

On 10 November 2026, in a client's application repository, it happened again in a different shape. A session ran a plain git commit. Seconds earlier, another session had staged five files of its own. A plain commit takes everything in the shared index, so all five went in. It was caught and undone with a soft reset.

The rule had been sitting in guidance for nearly three months and the shared index was swept anyway. The obvious repair, adding "commit with --only -- <paths>" to the note, was one more thing for a model to remember under load. So the same day the rule became a hook. This is the block in ~/.claude/settings.json, with the script renamed to remove the client's initials:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/shared-checkout-guard.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

The script is about a hundred lines of Python. The core of it, trimmed and with the path anonymised:

# ~/.claude/hooks/shared-checkout-guard.py (excerpt)
SCOPE = os.path.join(os.path.expanduser("~"), "client-app")

def main():
    data = json.load(sys.stdin)
    command = (data.get("tool_input") or {}).get("command") or ""
    if "git" not in command:
        return 0                      # not our business
    cwd = data.get("cwd") or ""
    if not cwd.startswith(SCOPE):
        return 0                      # only this checkout
    for tokens in segments(command):  # split on && ; | and newlines
        call = git_call(tokens)
        if call:
            reason = problem(*call)   # commit without --only, add -A, add .
            if reason:
                print(f"Blocked: {reason}.", file=sys.stderr)
                return 2              # exit 2 = refuse the tool call
    return 0

Three design points are worth copying.

  • It is scoped. The guard applies in one checkout. Everywhere else, git add . passes untouched. A hook that blocks too widely gets disabled within a week.
  • It explains itself. The stderr message tells the model what to run instead: name the files, commit with --only. The model reads the reason and adjusts, so the session continues instead of stalling.
  • It ignores data. The script strips heredoc bodies before parsing, so a commit message that happens to contain the words "git add ." does not trip it.

The same pattern is in Anthropic's own advice: "An instruction like 'never edit .env' in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement." The docs add that a PreToolUse denial holds in every permission mode, including the ones that skip permission prompts.

We kept the written rule too. The memory note now says the discipline is enforced in that repository and explains why, which helps the model choose the right command first time rather than discovering the hook by hitting it.

Right when: the action must happen, or must never happen, the same way every time. Formatting after edits. Blocking a destructive command. A notification when Claude is waiting.

Wrong when: the right answer depends on context. A hook sees one tool call. It cannot weigh whether this particular commit is the exception. Setup, events and debugging are in our Claude Code hooks guide.

MCP servers: new tools, not new judgement

The Model Context Protocol connects Claude Code to systems outside your repository. You add a server with one command, for example the documented form for a remote server:

claude mcp add --transport http <name> <url>

Scope decides where the entry is stored: .mcp.json at the project root for a server shared with the team, or ~/.claude.json for local and user scope. Run /mcp in a session to see what is connected.

What an MCP server adds is capability: query the database, read the issue tracker, drive a browser. What it does not add is any knowledge of how your team wants those things done. The overview pairs the two: "MCP provides the connection; a skill teaches Claude how to use it well."

On context cost, the docs say tool names load at session start while full schemas "stay deferred until Claude needs a specific tool", so idle servers cost little.

Right when: Claude needs data or actions it cannot reach with files and a shell.

Wrong when: the system already has a command-line tool Claude can run, or what you really want is a procedure. That is a skill. Which servers are worth connecting is its own topic; see Claude Code MCP servers.

Plugins: packaging, not a seventh behaviour

A plugin does nothing a skill, subagent, hook or MCP server cannot do alone. The plugin docs say so: those all "work on their own, without a plugin." A plugin is a directory with a manifest that bundles them, so they can be installed with one command and updated from a marketplace.

Its triggers are its parts' triggers. A plugin's skills are picked up by the model or typed, with a prefix (/plugin-name:skill-name). Its hooks fire on their events. Its MCP servers connect at startup.

Two differences matter when choosing. A plugin's cost is paid in every session where it is enabled, "not only the sessions where you use it." And a plugin's hooks and servers run code with your user permissions, outside the sandbox that covers Claude's own tool calls. We run one plugin. claude plugin details reports it as 27 skills, no hooks and no servers, adding roughly 1,650 tokens to every session.

Right when: a second repository or a teammate needs the same setup.

Wrong when: it is one skill for one person. Use the folder.

How we choose, in order

When something goes wrong twice, we walk the same ladder Anthropic's docs suggest, with one adjustment from experience.

  1. Is it a fact or convention? Add a line to CLAUDE.md. Cheapest fix, try it first.
  2. Is it a procedure? Write a skill with a description full of the words we would actually type.
  3. Does it drown the conversation? Hand it to a subagent, and only if it is large and independent.
  4. Does it need something outside the repo? Connect an MCP server, then write a skill for how to use it.
  5. Did the written rule get followed and still fail, or would one failure be costly? Stop refining the wording. Write a hook.
  6. Does someone else need all of this? Package it as a plugin.

The adjustment is step 5. It is tempting to respond to a failed instruction by making the instruction longer, bolder, more emphatic. Our shared-checkout rule lived as written guidance from August to November. What worked was accepting that a rule which must hold every time is not an instruction at all. It is a check, and checks run in code.

The same split shows up outside the editor. The scheduled SEO audit agent we run scores the mechanical checks in plain Python and asks a model only for the content judgement. Model for the reasoning, code for the guarantees.

If you are setting this up for a team and want the instruction files, skills and guardrails designed together rather than accreted, that is what our AI integration service covers. Tell us what keeps going wrong, and we will tell you which of the seven it belongs in.

Common questions

Claude Code skills vs agents: what is the difference?

A skill is a file of instructions that loads into your current conversation when it is relevant or when you type its name. An agent, in Claude Code's terms a subagent, is a separate worker with its own context window, its own system prompt and optionally its own tool limits, which does a task and returns a summary. A skill changes how Claude works in the thread you are in. A subagent moves work out of that thread.

Claude Code subagents vs skills: when should I use a subagent?

Use a subagent when a task would fill your conversation with output you will not need again, such as reading dozens of files to answer one question, or when you want to restrict the tools a worker can use. Use a skill when you want a reusable procedure followed in the main conversation. Anthropic's docs add that the main conversation is better when a task needs frequent back-and-forth, because a fresh subagent has to gather context first.

Claude Code hooks vs skills: which one enforces a rule?

Only the hook. A hook is a command Claude Code itself runs at a lifecycle event, such as before every tool call, whether or not the model would have chosen to. A skill is instructions the model reads and interprets, so the outcome can vary. Anthropic's docs say an instruction in CLAUDE.md or a skill is a request, not a guarantee, and that a rule which must hold every time should be a hook.

Claude Code plugins vs skills: are they the same thing?

No. A plugin is packaging. It bundles skills, subagents, hooks and MCP servers into one installable, versioned unit that can be shared through a marketplace. A skill is one of the things a plugin can contain, and it also works perfectly well on its own as a folder in your skills directory. Use a plugin when a second repository or a teammate needs the same setup.

Claude Code workflow vs skill: what is a dynamic workflow?

A dynamic workflow is a script Claude writes that runs many subagents in the background and returns one result. The difference from a skill is who holds the plan. With a skill, Claude decides turn by turn what to do next while following the instructions. With a workflow, the script holds the loop and the branching. Anthropic's docs position workflows for jobs that outgrow a handful of subagents, such as a codebase-wide audit.

How do CLAUDE.md and skills work together?

CLAUDE.md holds what Claude should always know: conventions, build commands, never-do rules. It loads in full at the start of every session. Skills hold what Claude needs sometimes: reference material and procedures, loaded on demand. A common pairing is a one-line rule in CLAUDE.md that points at a skill containing the detail. Anthropic suggests keeping each CLAUDE.md under 200 lines and moving procedures out into skills.

Claude Code skills vs MCP: do I need both?

They do different jobs. An MCP server gives Claude new tools and data from an external system, such as a database or an issue tracker, with the connection and authentication handled by the server. A skill gives Claude knowledge, including how to use those tools well. Anthropic's docs describe them as working together: MCP provides the connection and a skill documents your schema, query patterns or message formats.