55  55. Extending Claude Code: The Big Picture

Out of the box, Claude Code can already read and edit files, run commands, and search the web with its built-in tools (see How Claude Code Works). This part of the book covers the extension layer: features you add to teach Claude your rules, connect it to other services, and automate routine steps. This page is the map. The pages that follow cover each piece in detail.

55.1 The extension points at a glance

As of Oct 6, 2026 · Official docs: Extend Claude Code

Think of Claude Code as a capable new employee. The extensions are the things a company gives a new hire:

Extension What it is New-employee analogy Details
CLAUDE.md A Markdown file of standing instructions, loaded at the start of every session The handbook they reread every morning CLAUDE.md and Memory
Skill A folder with a SKILL.md file of instructions for one kind of task. Loaded only when needed, or run as a command such as /explain-code A binder of procedures on the shelf Skills
MCP server A program that connects Claude to an outside service (GitHub, a database, a web browser…) and gives Claude new tools for it Logins for the company’s other systems MCP Servers
Subagent A helper that Claude starts with its own, separate context window. It does a side task and returns only a summary An assistant sent off to research and report back Subagents
Hook Your own command (or other handler) that Claude Code runs automatically at a certain moment, for example after every file edit A rule built into the building: the doors always lock at 6 p.m. Hooks
Plugin An installable bundle of skills, subagents, hooks, MCP servers, and more. A marketplace is a catalog of plugins A starter kit in one box Plugins and Marketplaces
Mod A plugin containing JavaScript or TypeScript code that runs inside Claude Code and changes how it looks and behaves (new panes, instant commands, rules for tool calls) Remodeling the office itself Mods

Two smaller customizations are also worth knowing:

  • An output style changes Claude’s role, tone, and response format for a whole session. For example, the built-in Learning style explains its choices and leaves small pieces of code for you to write yourself. List or switch styles with /output-style.
  • The status line is a customizable bar at the bottom of the screen that shows whatever a script of yours prints, for example how full the context window is. Set one up with /statusline.

55.2 Where each piece plugs in

As of Oct 6, 2026 · Official docs: How Claude Code works · Tools reference

Recall the agentic loop: Claude gathers context, takes an action with a tool, checks the result, and repeats. Claude Code is the harness around the model: it supplies the tools and decides what goes into the model’s context. Each extension plugs into a different part of this picture:

             ┌─────────────── Claude Code (the harness) ───────────────┐
  Your  ───► │ Loaded at the start of the session:                     │
  prompt     │   CLAUDE.md, the output style, the list of skills       │
             │   (names + descriptions), the names of MCP tools        │
             │                                                         │
             │ Claude (the model) decides what to do and calls TOOLS:  │
             │   built-in tools: Read, Edit, Bash, WebFetch, ...       │
             │   Skill ............ loads one skill's full instructions│
             │   Agent ............ starts a subagent                  │
             │   mcp__server__tool  asks an MCP server to do something │
             │                                                         │
             │ Hooks run automatically at events:                      │
             │   session start, before/after a tool call, ...          │
             └─────────────────────────────────────────────────────────┘
   Plugins package any of the above. Mods are plugin code that runs
   inside Claude Code itself.

Three ideas to take from this picture:

  1. Some things are always on, some load on demand. CLAUDE.md is part of every request. A skill’s full text loads only when it is used, and the full details of an MCP tool load only when Claude needs that tool.
  2. Only some extensions add new tools. An MCP server adds tools (with names like mcp__playwright__browser_navigate). A skill does not add a tool: Claude loads it through the built-in Skill tool. Subagents are started through the built-in Agent tool.
  3. Hooks are not Claude’s choice. Claude Code runs a hook every time its event happens, whether or not Claude “wants” it to.

55.3 Which one should I use?

As of Oct 6, 2026 · Official docs: Extend Claude Code: build your setup over time

You don’t need all of these on day one. The official docs suggest adding each feature when a recognizable “trigger” shows up:

When this happens… Add…
Claude gets a project convention or command wrong twice a line in CLAUDE.md
You keep asking for shorter answers, more explanation, or the same format an output style
You keep typing the same prompt to start a task, or pasting the same checklist a skill
You keep copying data from a browser tab or app that Claude can’t see an MCP server
A side task floods your conversation with output you won’t need again a subagent
You want something to happen every time, without asking a hook
A second project needs the same setup, or you want to share it a plugin

Some pairs are easy to confuse:

  • CLAUDE.md vs. skill: CLAUDE.md loads every session (“always do X”). A skill loads on demand (reference material, or a workflow you trigger with /name). The docs suggest keeping CLAUDE.md under 200 lines and moving long reference material into skills.
  • Skill vs. hook: a skill is a request that Claude interprets; a hook is a guarantee. “Never edit .env” written in CLAUDE.md or a skill can be overlooked. A hook (or a permission rule) that blocks the edit can’t.
  • Skill vs. MCP server: an MCP server gives Claude a connection to an outside system. A skill gives Claude know-how, such as how your team uses that system. They work well together.
  • Skill vs. subagent: a skill’s content joins your main conversation. A subagent works in its own context window and sends back only a summary.

55.4 Every extension costs some context

As of Oct 6, 2026 · Official docs: Extend Claude Code: understand context costs

Extensions use part of Claude’s context window, its working memory (see Context, Models, Effort, and Usage). Too much always-loaded material wastes space and adds noise: Claude may pick the wrong skill or lose track of your conventions.

Feature When it loads Context cost
CLAUDE.md Session start, full text Every request
Skills Names and descriptions at start; full text when used Low until used
MCP servers Tool names at start; full tool details when needed Low until a tool is used
Subagents When started, in their own separate context Kept out of your main conversation
Hooks When their event fires; they run outside the conversation Zero, unless the hook returns output

Run /context in a session to see what is using space, and remove skills, servers, and plugins you no longer use.

55.5 Where the files live, and how they layer

As of Oct 6, 2026 · Official docs: Explore the .claude directory · Extend Claude Code: how features layer

Most extensions are just files. Project files are usually committed to Git so your teammates get them. Files in your home directory are personal and apply to all of your projects. (Full details: The .claude Folders and Settings Files. Remember that names starting with a dot are hidden; use ls -a to see them.)

my-project/                      <- one project (shared through Git)
├── CLAUDE.md                    project instructions
├── .mcp.json                    MCP servers shared with the team
└── .claude/
    ├── settings.json            permissions, hooks, ...
    ├── skills/<name>/SKILL.md   project skills
    └── agents/<name>.md         project subagents

~/   (your home directory)       <- personal, all projects
├── .claude.json                 app state and your personal MCP servers
└── .claude/
    ├── CLAUDE.md                your personal instructions
    ├── settings.json            your default settings
    ├── skills/   agents/        your personal skills and subagents
    └── plugins/                 installed plugins

When the same kind of thing is defined in more than one place:

  • CLAUDE.md files add up. The instructions from every level are loaded together.
  • Skills, subagents, and MCP servers with the same name override each other. Only one definition wins. For example, an MCP server defined for just this project on your machine wins over one with the same name that you defined for all your projects.
  • Hooks merge. Every matching hook runs, wherever it was defined.

As of Oct 6, 2026 · Official docs: Plugins overview · Tools reference · Hooks reference · Configure permissions

Mental models of these features circulate online (some written by chatbots). Here is what the official docs say about the most common mix-ups:

  1. “Skills, hooks, and MCP servers come from plugins.” Each one works on its own: a skill saved in ~/.claude/skills/, an MCP server added with claude mcp add, a hook in settings.json. A plugin is just a convenient way to install or share several at once. Plugins can also carry mods, output styles, themes, and code intelligence (language server) support.
  2. “A skill is a kind of tool.” A skill is instructions. The docs say skills run “through the existing Skill tool rather than adding a new tool entry.” Skills can also be run by you as commands (/name).
  3. “MCP servers only provide tools.” Tools are the main thing, but a server can also offer resources (data you can attach with @) and prompts (which show up as commands).
  4. “A hook is a shell script that runs before or after a tool call.” A hook can also be an HTTP request, an MCP tool call, a prompt for a Claude model, or a subagent, and hooks fire at other events too, such as session start or when you submit a prompt.
  5. “Writing a rule in CLAUDE.md is the same as enforcing it.” CLAUDE.md, rules, skills, and output styles are guidance that Claude reads. Permission rules and hooks are enforced by Claude Code itself, whatever Claude decides.

Because skills and subagents are reached through the built-in Skill and Agent tools, permission rules can switch them off: denying the Skill tool disables skills for Claude. Hooks are not tools at all.

55.6 Key takeaways

  • Built-in tools do the work; extensions add knowledge (CLAUDE.md, skills), connections (MCP servers), helpers (subagents), automation (hooks), and packaging (plugins, mods).
  • Add each extension when its trigger shows up, not all at once.
  • Use hooks or permission rules, not instructions, for anything that must happen every time.
  • Everything you add costs some context; check with /context and prune.

Practice Questions

Easy

Question 1 · Matching

Match each extension with its description.

Extension Description
1. CLAUDE.md A. An installable bundle of skills, subagents, hooks, MCP servers, and more
2. Skill B. A helper with its own context window that returns a summary
3. MCP server C. Standing instructions loaded at the start of every session
4. Subagent D. A command that Claude Code runs automatically at a lifecycle event
5. Hook E. Instructions for one kind of task, loaded only when needed
6. Plugin F. A connection to an outside service that gives Claude new tools

1 → C, 2 → E, 3 → F, 4 → B, 5 → D, 6 → A.

Question 2 · Multiple choice

Which extension is loaded in full at the start of every session?

  1. A skill
  2. CLAUDE.md
  3. A subagent
  4. An MCP server’s full tool details

b. CLAUDE.md is loaded in full every session, which is why it should stay short. A skill loads only its name and description until it is used (a), a subagent starts only when needed and in its own context (c), and MCP tool details load only when Claude needs that tool (d).

Question 3 · True or false

You must install a plugin before you can use skills, hooks, or MCP servers.

False. Each of these works on its own, for example a skill saved in ~/.claude/skills/ or a server added with claude mcp add. A plugin is only a convenient package for installing or sharing several of them at once.

Question 4 · Short answer

What is a plugin marketplace?

A catalog that lists plugins and where to get each one. You add a marketplace once and then install plugins from it by name.

Question 5 · Multiple choice

You want Claude to explain its choices and leave small pieces of code for you to write, for the whole session. Which feature fits best?

  1. A hook
  2. An MCP server
  3. An output style
  4. The status line

c. An output style sets Claude’s role, tone, and response format for a whole session; the built-in Learning style does exactly this. A hook runs a command at an event (a), an MCP server connects outside services (b), and the status line only displays information at the bottom of the screen (d).

Question 6 · True or false

Creating a skill adds a new tool to Claude’s list of tools.

False. A skill is a set of instructions. Claude loads it through the existing built-in Skill tool (or you run it with /name). MCP servers are the usual way to add new tools.

Medium

Question 7 · Matching

Match each situation with the extension you should add.

Situation Extension
1. You paste the same 30-line release checklist into chat every week A. Hook
2. Prettier must run after every single file edit, no exceptions B. MCP server
3. You keep copying ticket details from Jira into the chat C. Subagent
4. A research task reads 40 files, and you only need the conclusion D. Skill
5. Claude keeps using npm although the project uses pnpm E. CLAUDE.md

1 → D, 2 → A, 3 → B, 4 → C, 5 → E.

A repeated procedure is a skill; “every time, guaranteed” is a hook; data from a system Claude can’t see calls for an MCP server; a side task that would flood the conversation belongs in a subagent; a project convention that Claude gets wrong goes in CLAUDE.md.

Question 8 · Multiple choice

Which feature costs zero context unless it returns output?

  1. CLAUDE.md
  2. Skills
  3. Hooks
  4. MCP servers

c. Hooks run outside the conversation, so they add nothing unless they return output. CLAUDE.md is in every request (a). Skill names and descriptions (b) and MCP tool names (d) are loaded at the start of every session, even though their full content loads only when used.

Question 9 · Write the path

Maria wants a skill named weekly-report that is available in all of her projects. Sam wants one named deploy that everyone working on his team’s project gets through Git. Write the path of each SKILL.md file.

  • Maria (personal skill): ~/.claude/skills/weekly-report/SKILL.md
  • Sam (project skill, committed to Git): .claude/skills/deploy/SKILL.md, inside the project folder.

Question 10 · Short answer

A classmate clones your project from GitHub. Which of these will they get? CLAUDE.md in the project, .mcp.json in the project, .claude/skills/review/SKILL.md in the project, and ~/.claude/skills/notes/SKILL.md on your laptop.

They get the first three, because those files are inside the project and (assuming you committed them) are part of the repository. They do not get ~/.claude/skills/notes/SKILL.md: files in your home directory are personal and never part of any repository.

Question 11 · Short answer

Explain the difference between “loaded at the start of the session” and “loaded on demand”, using CLAUDE.md and a skill as examples.

CLAUDE.md is loaded in full at the start of every session, so it is always in Claude’s context (and always costs space). For a skill, only its name and description are loaded at the start; its full instructions are loaded on demand, when you run it with /name or when Claude decides your request matches its description.

Question 12 · Predict

You defined a skill named deploy in ~/.claude/skills/deploy/ and your project also has .claude/skills/deploy/. Which one runs when you type /deploy? What would happen instead with two hooks for the same event, one in each place?

The personal skill in ~/.claude/skills/ runs. Skills with the same name override each other, and personal (user-level) skills take priority over project skills. Hooks work differently: they merge, so both hooks would run.

Hard

Question 13 · Long answer

Your CLAUDE.md says “Never edit the .env file.” One day Claude edits it anyway. Explain why this can happen and what you should use instead.

CLAUDE.md is guidance that Claude reads and interprets; it is a request, not a guarantee. In a long session, or when following other instructions, Claude can overlook it. Rules that must hold every time should be enforced by Claude Code itself: a permission deny rule for edits to .env, or a hook that runs before each edit and blocks changes to that file. Claude Code applies these whatever Claude decides. (See Hooks and Permissions, Modes, and Safety.)

Question 14 · Scenario

Your team wants Claude to query the project’s database and follow the team’s rules for writing queries (naming, which tables are off-limits, how to paginate). Which two extensions would you combine, and what does each one contribute?

An MCP server for the database provides the connection: tools Claude can call to run queries. A skill provides the know-how: the schema notes and the team’s query rules, loaded when Claude works on database tasks. The official docs list “Skill + MCP” as a standard pattern: MCP provides the connection, a skill teaches Claude how to use it well. (Putting the full rules in CLAUDE.md would also work, but would cost context in every session, even ones that never touch the database.)

Question 15 · Find the bug

A chatbot gave a student this mental model. Identify two things in it that are wrong or misleading according to the official docs.

Plugin
 ├── Skills
 ├── Hooks          (shell scripts that run before/after tool calls)
 ├── Agents
 └── MCP servers
       └── Tools    (the only things Claude can call)

Any two of these:

  • It suggests skills, hooks, agents, and MCP servers exist only inside plugins. Each also works on its own; plugins are optional packaging.
  • Hooks are not only shell scripts (they can be HTTP requests, MCP tool calls, prompts, or subagents), and they fire at other events too, such as session start.
  • MCP tools are not the only things Claude can call: Claude Code has many built-in tools (Read, Edit, Bash, …, plus Skill and Agent, through which skills and subagents are used).
  • MCP servers can also provide resources and prompts, not just tools.
  • It leaves out mods and output styles, which plugins can also contain.

Question 16 · Scenario

Sam installed 10 MCP servers and wrote 40 skills with long descriptions. Now Claude sometimes loads the wrong skill and his conversations fill up sooner. Explain what is going on and suggest three fixes.

Every model-invocable skill puts its name and description into context every session, and every MCP server adds its tool names and instructions. With many overlapping descriptions there is both less room and more noise, so Claude can match the wrong skill. Fixes (any three):

  • Run /context to see what is using space.
  • Remove skills and servers he doesn’t use (or disable servers in /mcp).
  • Make skill descriptions shorter and more specific so they don’t overlap.
  • Mark skills he only runs by hand with disable-model-invocation: true, which keeps their descriptions out of context.
  • Move rarely needed work into subagents so its output stays out of the main conversation.

Question 17 · Compare

Explain the difference between a skill and a subagent in terms of where the work happens and what ends up in your main conversation. Give one task that suits each.

A skill’s instructions are loaded into your main conversation, and Claude follows them there, so everything it does is visible and uses your context. A subagent runs in its own separate context window; it may read dozens of files, but only its final summary comes back to your conversation.

  • Suits a skill: a code-review checklist or an API style guide you want Claude to apply while working with you.
  • Suits a subagent: “Find every place the app handles payments and summarize how it works” (lots of reading, short answer).

Question 18 · Long answer

Sort these into “guidance Claude reads” and “rules Claude Code enforces”, and explain why the difference matters: CLAUDE.md, a permission deny rule, a skill, a hook, an output style.

  • Guidance Claude reads: CLAUDE.md, a skill, an output style.
  • Enforced by Claude Code: a permission deny rule, a hook.

Guidance shapes what Claude tries to do, but Claude interprets it and can get it wrong. Enforced rules apply no matter what Claude decides, so anything safety-related or that must happen every time (blocking a dangerous command, formatting after every edit) belongs in permission rules or hooks.

© 2025-2026 Y. Rosenthal. All rights reserved.