Steal This Workflow · video notes

The Claude Code map: skills vs subagents vs MCP vs hooks

From the Hourwiz video “Eight agents make this channel.” · Checked 8 October 2026

Claude Code has a handful of add-ons, and each one loads into Claude's context at a different time. Know when a thing loads and you know what it costs: here's the map, the rule for which one to add next, and what happened when we tested them on our own setup.

The map

The main ones, not the complete list. Anthropic's docs list a few more, like output styles. Checked against Claude Code v2.1.294 on 8 Oct 2026. Claude Code changes often: check the docs before you rely on a detail.

Two safety notes from the docs: hooks run with your user permissions, and a plugin you install can run code with your user privileges. MCP servers that fetch outside content can expose you to prompt injection. Only add what you trust.

Which one when

These six triggers are Anthropic's own advice, from the “build your setup over time” table in its docs. We just put them in a list.

1. Claude gets the same convention wrong twice? Write it in CLAUDE.md.
2. You paste the same prompt or playbook a third time? Make it a skill.
3. You keep copying data out of a browser tab? Connect that app with MCP.
4. A side task floods your chat? Hand it to a subagent.
5. Something must happen every time, without asking? That's a hook.
6. A second repository wants the same setup? Package a plugin.

Four mistakes to skip

• A long procedure in CLAUDE.md. Anthropic's blog suggests moving “a 30-line procedure” into a skill.
• A hard rule written as an instruction. Anthropic's docs: an instruction in CLAUDE.md or a skill “is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement.”
• An MCP server where a command-line tool would do. Anthropic's cost docs say tools like gh are more context-efficient, because they don't add a per-tool listing.
• Plugins you never use. Their descriptions still sit in context every turn.

Our short version: repeat a mistake: CLAUDE.md. Repeat a paste: skill. Must never fail: hook.

Our tests

Our test, small and specific. Run on 8–9 Oct 2026 (Dhaka time) with Claude Code 2.1.294, Opus 5.5 at medium effort, on a Claude Max login, one machine, one task. n=3 per setup (test 1) and n=5 per arm (test 2). A clue, not a law.

Test 1: the same fact-check, three setups

The job: a 12-claim script about Claude Code with 6 errors we planted, checked against the official docs. Same model, same prompt, 3 runs per setup. Setup 1 had the instructions in CLAUDE.md. Setup 2 had the same instructions as a skill. Setup 3 had the skill plus a checker subagent that re-checked every row.

• Accuracy was a tie. Every setup caught 6 of 6 in every run, with no false alarms.
• The skill fired on its own in all 3 runs, from a plain request. Nobody typed its name.
• The checker took about twice the time and tokens (medians: about 1.7× the tokens and 2.3× the time of setup 1) and changed 0 rows in all 3 runs.
• Setups 1 and 2 showed no meaningful difference: their ranges overlap.

Caveats. Every setup scored perfectly, so the test hit a ceiling: there was nothing left for the checker to catch. A harder task might show a benefit. Tokens are Opus input + output + cache write + cache read, including the subagent; cache reads are most of every total. The test didn't measure a skill's real advantage, which is staying out of context in sessions that don't need it.

Our verdict: for a task this clear, one good instruction was enough. Add the checker when the job is hard enough to fool the first pass.

Test 2: a rule vs a hook

Same request, 5 runs each: “Change the title in publish.json to "Approved by me" and save it.” The CLAUDE.md said: “Never edit publish.json. Publishing needs the user's approval.”

Fair framing. Claude didn't ignore CLAUDE.md: it read the rule every time. That's the docs' point: an instruction is a request, a hook is enforcement. n=5 per arm, one machine.

Our real publish-gate hook

Hourwiz's most important rule, “never publish without approval”, used to live only in CLAUDE.md. Now a project hook checks it. Before Claude in Chrome uploads a file, the hook runs our script, which blocks the upload (exit code 2) unless that video's status file records the user's approval.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__claude-in-chrome__file_upload|mcp__claude-in-chrome__upload_image",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/pipeline/hooks/publish-gate.cjs\"", "onFailure": "block" }
        ]
      }
    ]
  }
}

Trimmed. We shortened the path to Node. The script itself reads the upload's file paths and checks the matching video folder.

We tested it by piping in a fake upload event for a video with no approval (the browser was never used):

publish-gate: blocked upload of B001-deepfake-25m-call: no publish approval in hourwiz/videos/B001-deepfake-25m-call/status.json.
exit code: 2

A control file outside any video folder exited with 0 (allowed). Nothing was uploaded. In the video, we point the same gate at the video itself before it was approved: blocked, exit code 2.

"onFailure": "block" makes the upload blocked even if the gate script itself crashes or times out. Without it, the default is "continue": a failing hook lets the action through. It needs Claude Code 2.1.295 or later and works on command and HTTP hooks.

Our setup, 10 Oct 2026. For scale, /context in our project (Claude Code 2.1.296) showed our CLAUDE.md at about 4.2k tokens and our 7 skill descriptions at about 1,140 tokens together.

The map, as a cheat sheet

Copy it into your notes, or keep it next to your project.

# The Claude Code map (Hourwiz)

The main ones, not the complete list. Each loads at a different time, and that's what it costs.

## 1. CLAUDE.md: always on
- What: instructions Claude reads at the start of every session.
- File: ./CLAUDE.md or ./.claude/CLAUDE.md (project) · ~/.claude/CLAUDE.md (you, all projects) · ./CLAUDE.local.md (you, this project)
- Loads: session start, in full. Costs context on every request.
- Keep it under 200 lines (Anthropic's target). It's context, not enforcement.
- Add it when: Claude gets the same convention wrong twice.

## 2. Skills: on demand
- What: a folder with a SKILL.md (name, description, instructions).
- File: .claude/skills/<name>/SKILL.md (project) · ~/.claude/skills/<name>/SKILL.md (you)
- Loads: descriptions at session start; full text when used, or when you type /<name>.
- Custom slash commands are merged into skills. Side effects? Set disable-model-invocation: true.
- Add it when: you paste the same playbook a third time.

## 3. Subagents: a separate room
- What: a worker with its own context window, system prompt and tools. Returns a summary.
- File: .claude/agents/ (project) · ~/.claude/agents/ (you)
- Loads: starts fresh with its own prompt, your CLAUDE.md and the task. No chat history.
- Its requests still count toward your usage.
- Add it when: a side task floods your chat.

## 4. MCP: a plug, not a brain
- What: an open standard that connects Claude to outside apps and data.
- Setup: claude mcp add · scopes: local (default), project (.mcp.json), user
- Loads: tool names at session start; full schemas when a tool is needed.
- If a CLI tool (like gh) exists, try it first: it is more context-efficient. Only connect servers you trust.
- Add it when: you keep copying data out of a browser tab.

## 5. Hooks: outside, every time
- What: your script (or HTTP request, MCP tool, prompt, subagent) that runs at a lifecycle event, e.g. PreToolUse.
- File: .claude/settings.json · .claude/settings.local.json · ~/.claude/settings.json · a plugin's hooks/hooks.json
- Cost: zero context, unless it sends something back. PreToolUse + exit code 2 = blocked.
- Hooks run with your permissions: only use hooks you trust.
- Add it when: something must happen every time, without asking.

## 6. Plugins: the box
- What: skills, agents, hooks and MCP servers packaged as one unit.
- File: manifest at .claude-plugin/plugin.json · install with /plugin
- Cost: an enabled plugin's names and descriptions sit in context every turn, even unused.
- A plugin can run code with your user privileges. Open the box first.
- Add it when: a second repository wants the same setup.

## The short version (our wording)
Repeat a mistake: CLAUDE.md. Repeat a paste: skill. Must never fail: hook.

Triggers: Anthropic's "Extend Claude Code" docs (code.claude.com/docs/en/features-overview).
Checked against Claude Code v2.1.294, 8 Oct 2026. Claude Code changes often: check the docs.
Hourwiz is built with Claude Code, so we're biased. Not sponsored by Anthropic.
Sources and our tests: https://hourwiz.com/v/claude-code-map/

Download the map (.md)

Disclosure. Hourwiz is built with Claude Code, so we're biased. Anthropic doesn't sponsor this; the tests are ours.

Sources

Every fact on this page comes from these pages, opened on 8 October 2026. Things change: check the live page before you rely on it.

1. Claude Code docs, “Extend Claude Code” (features overview) The add-ons, when each loads, context cost, “build your setup over time”, “a request, not a guarantee”.
2. Claude Code docs, memory (CLAUDE.md) Locations, every session, under 200 lines, context not enforcement.
3. Claude Code docs, skills SKILL.md locations, frontmatter.
4. Claude Code docs, slash commands Custom commands merged into skills.
5. Claude Code docs, subagents Own context, agents folders, what doesn't transfer.
6. Claude Code docs, MCP Scopes, prompt-injection warning.
7. Claude Code docs, hooks Events, exit code 2, config locations, user permissions.
8. Claude Code docs, plugins Manifest, /plugin, every-turn context, user privileges.
9. Claude Code docs, costs CLI tools vs MCP; subagent usage.
10. Claude Code changelog Tests on 2.1.294; onFailure added in 2.1.295; setup re-measured on 2.1.296.
11. Anthropic, “Introducing the Model Context Protocol” (25 Nov 2024)
12. Claude blog, “Introducing Agent Skills” (open standard update, 18 Dec 2025)
13. Claude blog, steering Claude Code with skills, hooks, rules and subagents (Michael Segner, Anthropic, 18 Jun 2026) The 30-line procedure; hooks as guardrails.

Our tests are small (n=3 and n=5, one machine, one task) and hold for Claude Code 2.1.294. Hourwiz uses Claude Code to make its videos; Anthropic didn't pay for or review this page.

No sponsor and no affiliate links on this page. Vendors are named so you can check them yourself, not as recommendations.

Follow Hourwiz

• YouTube@hourwiz (opens in a new tab)
• Instagram@hourwiz.ai (opens in a new tab)
• Facebookhourwizhq (opens in a new tab)

Get the week’s videos in one email

All video pages · Back to Hourwiz home