Extending Claude Code: Hooks (Deterministic) vs. CLAUDE.md (Advisory), Skills, Subagents, Plugins, Wiring Up an MCP Server, CLI Tools First

Today's Goals

1. Explain why hooks are more reliable than rules in CLAUDE.md, and write one hook that blocks a dangerous action
2. Write a SKILL.md, and explain what each of skill, CLAUDE.md, and subagent is for
3. Wire an MCP server into Claude Code, and explain the case for preferring CLI tools

Yesterday you wrote the teammate an onboarding handbook. Today we answer what a handbook cannot: which rules must be enforced without exception, which workflows deserve a written procedure, and which work should be handed off. Once you have read this and finished the lab, scroll back up and tick off the three goals.

Plain-Language Walkthrough

Advice versus a gate: CLAUDE.md says "please do this," hooks guarantee "this always happens"

The handbook says badge in at the server room door. Most colleagues will; someone in a hurry will slip in the back. What actually guarantees the badging is not the handbook but the gate — no badge, no door, regardless of anyone's diligence.

CLAUDE.md is the handbook and hooks are the gate. That is not a figure of speech but a consequence of where each sits in the system: the content of CLAUDE.md goes into the model's context as text, and the model reads it and then decides — it is advisory, with a high compliance rate but not a perfect one, and compliance drops as the file grows, as we saw yesterday. A hook, by contrast, is a script that the Claude Code program executes unconditionally at a specific moment: before a tool call, after one, before a turn ends, at session start. Whether it runs and whether it blocks is decided by its exit code, and nothing the model says changes that. It is deterministic.

So the criterion is one sentence: anything that must happen every time, with not a single exception, becomes a hook; anything that usually ought to happen goes in CLAUDE.md. The official best practices page gives this its own section, plus the reverse advice: if Claude already follows a CLAUDE.md rule by default, delete it; if a rule must be followed 100% of the time, convert it into a hook. Shave both ends and CLAUDE.md gets short.

A typical must-happen list: auto-format after an edit; block anything that touches migrations/; do not let a turn end while tests fail; record every command in an audit log. A typical usually-ought-to list: prefer named exports; write commit messages in a particular style; ask before guessing at an ambiguous requirement. The first list goes to the gate, the second stays in the handbook.

Writing your first hook: event, matcher, script, exit code

A hook is made of four things: when it fires (the event), which tools it fires for (the matcher), what runs (the command), and how the result is expressed (an exit code or JSON). The configuration lives in the project's .claude/settings.json (travels with git, shared by the team) or ~/.claude/settings.json (yours alone), and /hooks lets you browse what is currently in effect.

The commonly used events are these: PreToolUse (before a tool call, and it can block), PostToolUse (after a call, so it can follow up), Stop (when the model is about to end a turn, and it can refuse to let it), UserPromptSubmit (when you submit a prompt), and SessionStart. In the example task we want to block writes to the migrations directory, so PreToolUse; the matcher takes tool names, and Edit|Write matches both editing tools:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.mjs"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-green.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

The script reads one JSON object from standard input: it holds hook_event_name, tool_name, tool_input (for Edit, fields such as file_path), cwd, and session_id. It expresses its decision through the exit code: 0 allows (and if stdout carried a JSON object, Claude Code parses the structured decision in it); 2 blocks, with whatever went to stderr handed back to the model as the reason it was blocked so it can take a different route; any other non-zero code means the script itself failed but nothing is blocked. The guard script in both languages:

// PreToolUse hook: block any write under migrations/.
// Reads JSON from stdin; exit code 2 = block, and stderr goes back to the model as the reason.
import { readFileSync } from 'node:fs'
 
const input = JSON.parse(readFileSync(0, 'utf8')) // 0 = stdin
const filePath = input.tool_input?.file_path ?? ''
 
if (/(^|\/)migrations\//.test(filePath)) {
  process.stderr.write(
    `Refused: ${filePath} is under migrations/. Migration files are generated by pnpm db:generate and must not be hand-edited.`
  )
  process.exit(2) // 2 = block this tool call
}
process.exit(0) // 0 = allow; continue through the normal permission flow

# PreToolUse hook: block any write under migrations/.
# Reads JSON from stdin; exit code 2 = block, and stderr goes back to the model as the reason.
import json
import re
import sys
 
payload = json.load(sys.stdin)
file_path = payload.get("tool_input", {}).get("file_path", "")
 
if re.search(r"(^|/)migrations/", file_path):
    print(
        f"Refused: {file_path} is under migrations/. Migration files are generated by "
        "pnpm db:generate and must not be hand-edited.",
        file=sys.stderr,
    )
    sys.exit(2)  # 2 = block this tool call
sys.exit(0)  # 0 = allow; continue through the normal permission flow

The script behind that Stop hook is shorter still: run the tests, and on failure exit 2 with a failure summary on stderr — the model receives "tests are red, you may not stop," keeps fixing, and continues until they pass. That is the third rung of yesterday's "make the check harder." One safety valve to know about: after being blocked by a Stop hook 8 times in a row, Claude Code lets the turn end anyway, so you cannot get stuck in an infinite loop.

Skills: package a repeated workflow as a procedure that loads on demand

Some work you brief the teammate on every week: "the flow for fixing an issue is read the issue, search the code, write a test, change it, run lint, open a PR." Put it in CLAUDE.md? You could, but that loads on every session while you only fix two issues a week — the rest of the time those few dozen lines are occupying the window for nothing. Better to write it as a printed procedure the teammate can pull off the shelf when it is needed.

That is a skill: .claude/skills/<name>/SKILL.md, a Markdown file with frontmatter. Its defining property is progressive loading — at session start only the single description line from the frontmatter stays resident, and the body is read in when Claude judges the current task relevant (or when you type /name). So the body can be long, with steps and examples, at almost no everyday cost. The skill for the example task:

---
name: add-validation
description: Add zod input validation to an Express route and write the matching vitest cases. Use when the user mentions adding validation, adding tests, or validating a request body.
argument-hint: [route path, such as POST /todos]
---
 
Add input validation and tests for $ARGUMENTS in the following order, finishing each
step before moving to the next:
 
1. Read the route file and the existing tests, and list how each field of the request body is handled today
2. Write the failing tests first: one each for empty value, over-long value, wrong type, and extra field
3. Define the schema with zod (always .strict()); on failure return 400 with { error, issues }
4. Run only this one test file: pnpm vitest run test/<file>
5. Once green, paste the test output in your reply, then stop and wait for confirmation

The description is the trigger, and there is craft to it: say what it does and how the user is likely to phrase the request, in a sentence or two. Too broad and it fires spuriously; too narrow and it never fires. $ARGUMENTS catches whatever you pass after /add-validation POST /todos. Two optional fields worth remembering: disable-model-invocation: true restricts it to manual /name invocation, which suits workflows with side effects such as deploying or sending messages; and allowed-tools can pre-authorize a few commands for this skill.

The division of labor among three things is now clear: CLAUDE.md holds short facts that are true every time, and a skill holds a multi-step workflow used only occasionally, while the subagent of the next section holds work that needs its own context. To decide where a piece of content belongs, ask two questions: is it useful on every session, and is it one rule or a set of steps?

Subagents: a colleague you send off to research, who comes back with the conclusion only

You ask the teammate to find out how your authentication handles token refresh. They go through thirty files — and if all thirty end up spread across the desk you share, the desk is full and the implementation you actually wanted has nowhere to go. Better to have them read in the office next door and come back with one conclusion.

A subagent is that office next door: a Claude with its own separate context window that takes a task, reads everything it needs, and returns only a summary to the main session. D2 and D3 kept insisting that context is the scarcest resource, and a subagent is the most direct way to protect it — isolating work that reads a lot and keeps little. Claude Code ships a few: Explore is read-only and built for finding files and understanding code; Plan does research in plan mode; general-purpose does anything. You can define your own in .claude/agents/<name>.md:

---
name: security-reviewer
description: Review code for security problems: injection, authorization flaws, leaked secrets. Use when the user asks for a security review.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
You are a senior security engineer. Review only; never modify. For every problem, give
the file and line number, an explanation of the risk, and a suggested fix.

tools limits what it may use (a reviewer should not have Edit), and model lets you give it a cheaper or a stronger model. Usage is direct: "use a subagent to investigate the token refresh logic in the auth module," or "have security-reviewer review this diff." It cannot see your main session's history — only the task you sent it on plus CLAUDE.md. That is both a limitation and a virtue: a reviewer uncontaminated by the memory of having just written that code finds flaws more readily. D5's adversarial review is built on exactly this property.

When should you not use one? Work that needs several rounds of back-and-forth discussion, work whose phases must share a great deal of context, and work that a single sentence would finish. Sending a task out costs one full briefing plus one summary, so it does not pay for something small.

Plugins and MCP: bringing in capabilities other people already built

Everything so far has been do-it-yourself: write the handbook, write the gate, write the procedure, write the subagent. But plenty of capabilities already exist, and wiring one in beats building it. Two routes.

A plugin is a packaged bundle of skills, hooks, subagents, and MCP configuration, installed with one command. Open the marketplace with /plugin and browse: a project in a strongly typed language, for example, can install a code intelligence plugin that gives Claude precise symbol navigation and automatic error reporting after a change.

An MCP (Model Context Protocol) server turns an external system into tools Claude can call: an issue tracker, a database, a monitoring platform, a design tool. Wiring one up takes:

# a remote server (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp
 
# a local server (stdio, one executable command)
claude mcp add my-db -- npx -y @some/postgres-mcp postgres://localhost:5432/app

Once connected, Claude has a new group of tools and can read the requirement from issue #123 and implement it, or check the recent slow queries on a table. MCP is a seven-day course of its own (mcp-7days, coming soon); today it is enough to be able to wire one up and use it.

One caution: every MCP server you connect brings all of its tool definitions into the context, so ten servers can mean tens of thousands of tokens of fixed overhead. Connect what you will genuinely use, and remove what you are done with.

CLI tools first: why gh beats calling the GitHub API

The last point looks the most low-tech and yet has its own section in the official best practices: if a command-line tool exists, do not have Claude call the API directly.

The reason is context again. Having Claude create an issue through GitHub's REST API means constructing the request, handling authentication, and parsing a large JSON response — and the input and output of every step enters the window. Switch to gh issue create --title ... --body ... and it is one command, one line of output, with login and pagination already handled by gh. The same holds for aws, gcloud, sentry-cli, docker, and kubectl: a CLI is the highest-information-density interface humans have spent years polishing, and it is what Claude knows best.

It can even teach itself a CLI it has not seen: "get to know the foo tool with foo --help, then use it to do A, B, and C" — one --help output is usually enough. So before you write your own MCP server, ask whether the system already has a CLI. If it does, install it and move on.

Taking today's six sections together, the ways to extend Claude Code line up by how deterministic they are: a hook is hardest (it always executes), CLI and MCP are capabilities (available once connected), a skill is an on-demand workflow, a subagent is an isolated context, and CLAUDE.md is softest (advice). The order in which you equip the teammate is the same: install the gates you cannot do without, and only then talk about making it more capable.

Source Reading

Hands-On Lab

The lab's starter and solution directories are themselves a demo project of a few dozen lines (Express + zod + vitest), with hooks and the skill under .claude/. The hook scripts and SKILL.md in starter/ have blanks; solution/ is complete. Both sides ship an event simulator — it needs no Claude Code, feeding fake event JSON straight into the hook scripts and printing exit codes so you can iterate quickly while writing them. The first three steps need no Claude Code; the last two do.

1. Run pnpm install in the starter directory, then pnpm start, and watch the simulator report all three events as allowed — because the hooks are still empty, which is what you are filling in.
2. Finish exercise 1: read the stdin JSON in guard-migrations.mjs, and when the path matches migrations/, write the reason to stderr and exit 2. Rerun the simulator and confirm the first event becomes blocked.
3. Finish exercise 2: in require-green.sh, run the demo project's single test file, and on failure write the last few lines of output to stderr and exit 2. Break an assertion on purpose, rerun the simulator to see the effect, then fix it back.
4. Finish exercise 3: complete the description and the five-step body of SKILL.md, making sure the description says how a user would phrase the request.
5. Open the solution directory in real Claude Code, check the configuration with /hooks, then ask it to rename a table in migrations/0001_init.sql and watch it get blocked; finally run /add-validation POST /todos through the whole flow.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward the reliability gap between hooks and CLAUDE.md, the progressive loading of a skill, and the context isolation of a subagent. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Explain why hooks are more reliable than rules in CLAUDE.md, and write one hook that blocks a dangerous action
• Write a SKILL.md, and explain what each of skill, CLAUDE.md, and subagent is for
• Wire an MCP server into Claude Code, and explain the case for preferring CLI tools
• Recite what each of the three hook exit codes means, and the 8-strike safety valve on Stop hooks
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D5) is the last day, and we turn Claude Code from a terminal sidekick into one stage of a pipeline: run it headless in CI with claude -p, parse the JSON result to judge success or failure, open parallel sessions with worktrees, run an adversarial review across Writer / Reviewer sessions, and finish with a 20-line minimal agent built on the Agent SDK. The gates you installed today only show their real value when nobody is watching — with no human present, a hook is the only rule still working.