Claude Code Harness Guide: Skills, Hooks, Subagents, MCP

Open the CLAUDE.md of a team six months into Claude Code and you will usually find the same artifact: 400 lines of rules, half of them stale, all of them loaded into the model on every single request. The team keeps adding lines because the agent keeps missing instructions. The agent keeps missing instructions because the file is too long. Anthropic’s own guidance now says the quiet part out loud: bloated CLAUDE.md files cause Claude to ignore your actual instructions, and the official ceiling is about 200 lines.

That failure mode is what this guide is about. Claude Code stopped being a CLI with one config file sometime in 2025. As of July 2026 it is a full harness with seven distinct extension primitives: CLAUDE.md and rules files, skills, hooks, subagents, agent teams, MCP servers, and plugins. Each loads at a different time, costs a different amount of context, and gives you a different grade of guarantee. Engineering the harness means knowing which primitive to reach for, and the wrong choice is rarely fatal but always expensive.

The config layer is the harness you actually own

A Claude Code harness configuration is the set of files that shape what the agent knows, what it can touch, and what happens automatically around it: CLAUDE.md and rules for always-on context, skills for on-demand knowledge and workflows, hooks for deterministic automation, subagents for isolated work, MCP for external connections, and plugins to package it all. The model is rented. This layer is yours.

The general economics of that split, why the wrapper around a rented model sets both the bill and the completion rate, is the subject of the harness scaffolding guide on this site. This post is the applied version for the most widely deployed harness there is. Claude Code ships new versions near-daily (v2.1.197 on June 30, 2026 made Sonnet 5 the default model with a native 1M-token context window), and the extension surface has grown faster than most teams’ mental model of it.

The primary source for most of what follows is Anthropic’s documentation, in particular Extend Claude Code and Best practices for Claude Code. Vendor docs, so read the recommendations as the vendor’s position. But they now include something genuinely useful that earlier versions lacked: a per-feature accounting of what loads into context and when. That table is the skeleton key for the whole system, and this guide leans on it hard.

The seven primitives at a glance

Two questions sort every primitive: when does it enter the context window, and is it a suggestion or a guarantee?

Primitive	What it is	When it loads	Context cost	Advisory or deterministic
CLAUDE.md / rules	Always-on project instructions	Session start, full content	Every request	Advisory
Skills	On-demand knowledge and workflows	Descriptions at start, body on use	Low until used	Advisory
Hooks	Scripts fired on lifecycle events	On trigger, runs outside context	Zero unless output returned	Deterministic
Subagents	Isolated workers with own context	When spawned	Isolated from main session	Advisory
Agent teams	Multiple coordinated full sessions	When spawned	Highest: each teammate is a full instance	Advisory
MCP servers	Connections to external services	Tool names at start, schemas deferred	Low until a tool is used	Deterministic (tools)
Plugins	Packaging for all of the above	Depends on contents	Sum of contents	n/a

The rest of the guide walks these in the order a real repo tends to need them, with the sharp edges the summary table hides.

CLAUDE.md and rules: the always-on layer

CLAUDE.md is the file Claude reads at the start of every conversation, and the official memory documentation is blunt about what that means: full content, every session, on every request. It is the only primitive with no lazy loading at all. That makes it simultaneously the most powerful place to put an instruction and the most expensive.

Anthropic’s best-practices documentation gives an include/exclude test that most teams fail: for each line, ask whether removing it would cause Claude to make mistakes. If not, cut it. Build commands Claude cannot guess, conventions that differ from defaults, repository etiquette, and known gotchas stay. Anything Claude can figure out by reading the code goes. Standard language conventions go. File-by-file codebase descriptions go.

Two mechanisms keep the file under the 200-line ceiling without losing the content:

1. Imports. CLAUDE.md can pull in other files with @path/to/file syntax, so a monorepo can keep per-area instructions where they belong.
2. Rules files. .claude/rules/ holds instruction files that can be scoped with paths frontmatter, so your Terraform guidelines load only when Claude touches Terraform files. Scoped rules are the escape valve for the single biggest CLAUDE.md failure: paying for language-specific instructions on every request in a repo where most sessions never touch that language.

Placement is hierarchical and additive: a home-directory file applies to every session, the project root file is the one you check into git, CLAUDE.local.md stays gitignored for personal notes, and nested files in subdirectories load on demand as Claude works there. When instructions conflict, more specific files typically win, but all of them contribute context cost simultaneously.

Skills: knowledge that loads when needed

A skill is a markdown file (a SKILL.md in .claude/skills/) holding knowledge, a workflow, or reference material. The loading model is the whole point, per the skills documentation: at session start Claude sees only each skill’s name and one-line description. The full body enters context only when you invoke it with /name or when Claude decides the description matches the task.

That two-stage load makes skills the correct home for exactly the content that bloats CLAUDE.md files: the API style guide, the deployment checklist, the migration playbook, the incident runbook. Always-relevant rules ride in CLAUDE.md; sometimes-relevant knowledge rides in skills and costs almost nothing while dormant.

Two frontmatter switches matter more than the rest:

• disable-model-invocation: true hides a skill from the model entirely until you invoke it by hand. Context cost drops to zero, and it is the documented safety pattern for workflows with side effects (deploys, releases) that only a human should trigger.
• context: fork runs the skill in an isolated context via a subagent instead of in your main conversation, which turns a heavyweight workflow into something that returns only its result.

The subtle failure mode is description quality. Claude picks skills by matching your task against those one-line descriptions, so vague or overlapping descriptions produce misfires in both directions: the wrong skill loads, or the right one never does. Treat the description line as an interface contract, not a comment.

Hooks: the only guarantees in the harness

Everything above is advisory. CLAUDE.md is read by a model; skills are interpreted by a model; and a model can, on a bad day, ignore both. Hooks are different in kind: they fire on lifecycle events (before and after tool calls, on session start and stop, on prompt submission) and run a script, HTTP request, prompt, or subagent every single time the event occurs.

Anthropic’s feature-comparison documentation states the distinction as directly as a vendor ever does: an instruction like “never edit .env” in CLAUDE.md or a skill is a request, not a guarantee, while a PreToolUse hook that blocks the edit is enforcement. If a rule must hold every time, it belongs in a hook rather than prompt text. That single sentence should reorganize most teams’ config: guardrails migrate to hooks, and CLAUDE.md shrinks to conventions.

The economics reinforce it. Hooks execute outside the conversation and add zero context unless they return output. A PostToolUse hook that runs your linter after each edit feeds failures back as text Claude reads and fixes, which is the cheapest verification loop in the whole system: silent when the code is clean, precise when it is not.

Hooks also gate the end of a turn. A Stop hook can run your test suite and block Claude from finishing until it passes, with a documented backstop: Claude Code overrides the hook and ends the turn after 8 consecutive blocks, so a broken check cannot trap a session forever. Paired with plan mode and permission rules, this is how an unattended session finishes correctly instead of just finishing. The verification-first framing (give the agent a check it can run, then make the check gate the stop) is the strongest single recommendation in the best-practices documentation.

Subagents and agent teams: paying for isolation

Context is the scarce resource in every session, and it degrades before it runs out: the best-practices documentation is built around the observation that model performance drops as the window fills. Subagents are the pressure valve. A subagent runs in its own fresh context, does the file-heavy work (codebase exploration, or a review pass over a large diff), and returns only a summary to your main conversation.

The trade is explicit: a subagent spends its own input and output tokens, so total spend can go up while main-context quality goes up with it. On a metered API plan that is a real line item; what a session actually bills is broken down in the Claude Code cost-per-task analysis, and the /cost command explainer covers how to see it live. The two built-in exploration agents (Explore and Plan) skip loading CLAUDE.md and git status entirely, which is a detail worth knowing: your carefully tuned instructions do not follow the agent into every delegated task.

Custom subagents are markdown files in .claude/agents/ with their own system prompt, tool allowlist, and optionally a skills: field whose listed skills are fully preloaded at launch. That is the composition pattern to remember: a security-reviewer agent that preloads your security checklist skill is a specialist you can spawn on demand.

Agent teams are the step past subagents: multiple full Claude Code sessions that share a task list and message each other directly, rather than reporting to one lead. The documentation is candid on both the fit (competing hypotheses, parallel review, feature work split by owner) and the price: each teammate is a separate full instance, making teams the most token-expensive primitive in the harness. They also remain experimental and disabled by default as of July 2026. The documented transition point is when parallel subagents start hitting context limits or need to talk to each other.

MCP, code intelligence, and plugins: the connection layer

MCP servers (MCP is the Model Context Protocol, the open standard for exposing external tools to a model) connect Claude to systems outside the repo: your database, your issue tracker, a browser. The 2026 loading model removed the classic objection. Tool names load at session start, full schemas stay deferred until a tool is actually needed, and tool search is on by default, so idle servers cost little. The /mcp command shows per-server token cost, which makes the audit trivial: run it, and disconnect what you are not using.

A common confusion the official comparison table addresses head-on: MCP is not a smarter skill. MCP provides tools and data access; a skill provides the knowledge to use them well. The documented pattern is to pair them, with the MCP server supplying the database connection and a skill supplying your schema and query conventions.

Two newer pieces round out the layer. Code intelligence plugins wire Claude to a language server, replacing broad file reads with symbol-level lookups, and the docs note the net context cost can go down as a result. And plugins are the packaging format for everything in this guide: a single installable unit bundling skills, hooks, subagents, and MCP servers, namespaced so multiple plugins coexist, distributable through marketplaces. The trigger for building one is unambiguous: a second repository needs the same setup.

The context ledger: what each primitive costs

Strip the features away and the harness is a budget problem. Every primitive either rides in the window permanently, loads on demand, or stays outside entirely, and Anthropic’s context-cost table in the feature documentation prices each lane: CLAUDE.md at full content per request, skills at a description line per request plus body on use, MCP at tool names with schemas deferred, subagents isolated, hooks at zero.

What each Claude Code primitive loads into context, and when

Primitive	Every request	Only when used	Outside the window
CLAUDE.md	full content	nothing loads	nothing loads
Rules files	unscoped rules	path-scoped rules	nothing loads
Skills	description line	full body	nothing loads
MCP servers	tool names	full schemas	nothing loads
Subagents	nothing loads	nothing loads	own context window
Agent teams	nothing loads	nothing loads	own sessions
Hooks	nothing loads	nothing loads	zero unless output

The engineering discipline falls out of the lanes. The permanent lane (CLAUDE.md, rules without path scoping, skill descriptions) is the one to police hardest, because its cost recurs on every request of every session forever. The on-demand lane is close to free until used, so volume matters much less than description quality. The outside lane (hooks, and skills hidden with disable-model-invocation) is where anything deterministic or dangerous should live.

One number puts the stakes in perspective. Sonnet 5’s native 1M-token window, default in Claude Code since late June 2026 per the Anthropic announcement, sounds like it retires the whole problem. It does not. The documented degradation pattern (quality drops as the window fills, well before it overflows) means a bigger window raises the ceiling without changing the discipline. Filling a million tokens with a 400-line CLAUDE.md, fifty skill descriptions, and every MCP schema you own reproduces the old failure at a larger scale and a larger price.

A build order that pays for itself

The best part of the current documentation is that it prescribes a sequence, not a shopping list. Each primitive has a trigger, and the documented adoption order is trigger-based:

1. Claude gets a convention or command wrong twice: add a line to CLAUDE.md.
2. You keep typing the same prompt or pasting the same playbook: save it as a skill.
3. You keep copying data from a system Claude cannot see: connect it as an MCP server.
4. Claude reads many files just to locate a symbol: install a code intelligence plugin.
5. A side task floods your conversation with output you will not reference again: route it through a subagent.
6. Something must happen every time without asking: write a hook.
7. A second repository needs the same setup: package it as a plugin.

Read as an investment schedule, the sequence is ordered by payback. The CLAUDE.md line costs seconds and pays on the next session. The skill costs minutes and pays the third time you would have typed the prompt. The hook costs an hour of scripting and pays forever, because it removes a class of failure rather than a single instance. Nothing in the list is speculative: every entry is a response to a pain you have already felt twice.

Permissions deserve a closing note because they are the harness decision with the sharpest downside. Claude Code now offers three documented ways to cut approval fatigue: allowlists for known-safe commands, auto mode (a classifier model reviews each command and blocks the risky ones; recent releases added blocking of destructive git operations that were not requested), and OS-level sandboxing, including a sandbox.credentials setting that blocks sandboxed commands from reading credential files. Which coding agents make these controls table stakes, and which do not, is part of the 2026 agent landscape survey; the short version is that permission engineering has become as much a part of the harness as the prompt ever was.

Advanced configuration: the layer past the defaults

Everything above works on a stock install. Three documented mechanisms sit underneath it, and they are where experienced setups diverge from default ones.

Settings scopes and live reload. All configuration flows through settings.json files, and the official settings reference defines a strict precedence: managed (org-deployed, cannot be overridden), then command-line flags, then .claude/settings.local.json (gitignored, personal), then .claude/settings.json (committed, shared with the team), then ~/.claude/settings.json (user-wide). The practical rule falls straight out of the hierarchy: anything the team depends on belongs in project scope where git reviews it, personal experiments stay in local scope, and machine-wide defaults live at user scope. Two details reward knowing. Claude Code watches these files and hot-reloads most keys (permissions, hooks, and credential helpers apply to the running session without a restart), while model and outputStyle are read at startup. And credential helpers (apiKeyHelper and its AWS, GCP, and OpenTelemetry siblings) let a script mint short-lived credentials per session instead of parking a static key in a file.

A status line as a context gauge. The statusLine setting runs any shell script you point it at, feeds it JSON session data on stdin, and displays whatever the script prints in a persistent bar. The status line documentation names the canonical uses: live context-window usage, session cost, and git state. For a post arguing that context is the budget, this is the instrument panel. A one-line script turns the invisible recurring cost of the permanent lane into a number you watch drain in real time.

Hooks well past the linter. The hooks reference documents more than 30 lifecycle events and five handler types: shell command, HTTP endpoint, MCP tool, a single-turn prompt evaluation, and an experimental read-only subagent. The advanced patterns worth stealing:

• Exactly three events feed a hook’s stdout straight into Claude’s context: SessionStart, UserPromptSubmit, and UserPromptExpansion. That makes them the documented channel for context injection, such as printing the current branch, recent commits, and open-ticket state at session start so every conversation begins oriented.
• A PreToolUse hook does not just allow or block. Its permissionDecision field takes four values (allow, deny, ask, defer), and a separate updatedInput field can rewrite the tool call’s arguments before execution. A hook can silently correct a risky command rather than merely rejecting it.
• async: true runs a hook in the background without blocking the turn, and the asyncRewake variant wakes Claude when the background job fails, with the error fed back as a system reminder. Long test suites stop holding the loop hostage.

None of this changes the two axes the guide runs on. The advanced layer just gives each one finer resolution: scopes and reloads decide when configuration takes effect, and the hook decision fields make the deterministic lane more surgical than a plain block.

This guide defines the primitives; composing them into repeatable procedures is a separate skill, covered in the Claude Code agentic workflows playbook (plan mode first, subagent research, parallel worktrees, verification loops). For the wider comparison of what these agents cost to run, see the AI coding agents hub.

Frequently asked questions

Should I put an instruction in CLAUDE.md or in a skill?

CLAUDE.md if Claude should always know it: build commands, conventions, never-do rules. A skill if it is reference material or a workflow needed only sometimes. CLAUDE.md loads fully on every request; a skill loads a one-line description until used. When a CLAUDE.md file passes roughly 200 lines, move the rarely used parts into skills or scoped rules files.

What is the difference between a hook and a skill in Claude Code?

A hook fires deterministically on a lifecycle event and runs outside the conversation; a skill is instructions the model reads and interprets. Use a hook when the action must happen every time with zero exceptions, such as linting after edits or blocking writes to a protected path. Use a skill when the task needs reasoning or judgment.

Is MCP the same as a skill?

No. An MCP server connects Claude to an external system and provides tools and data access. A skill provides knowledge and workflows, including how to use those tools well. The documented pattern is to combine them: MCP supplies the database connection, a skill supplies your schema and query conventions.

When should I use an agent team instead of subagents?

When parallel subagents start hitting context limits or need to communicate with each other. Subagents report summaries back to one lead session; agent team members are full independent sessions that share a task list and message each other. Teams cost the most tokens of any primitive and remain experimental and disabled by default as of July 2026.

Do hooks consume context window tokens?

Not by default. Hooks execute outside the conversation and add zero context unless they return output, in which case the output enters the conversation as text Claude reads. That makes hooks the cheapest verification mechanism in the harness: a passing check adds nothing, a failing check adds exactly the error.

Sources

Anthropic. Extend Claude Code. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/features-overview

Anthropic. Best practices for Claude Code. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/best-practices

Anthropic. Manage Claude’s memory. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/memory

Anthropic. Agent Skills. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/skills

Anthropic. Automate workflows with hooks. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/hooks-guide

Anthropic. Hooks reference. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/hooks

Anthropic. Claude Code settings. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/settings

Anthropic. Customize your status line. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/statusline

Anthropic. Subagents. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/sub-agents

Anthropic. Agent teams. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/agent-teams

Anthropic. Model Context Protocol. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/mcp

Anthropic. Plugins. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/plugins

Anthropic. Sandboxing. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/sandboxing

Anthropic (2026). Claude Code changelog. Claude Code documentation and GitHub releases (vendor changelog). https://code.claude.com/docs/en/changelog

Anthropic (2026). Introducing Claude Sonnet 5. Anthropic announcement (vendor announcement). https://www.anthropic.com/news/claude-sonnet-5