Extensibility — Four Mechanisms

## Full reference: extensibility in production

Derived from architecture.md §Extensibility: MCP, Plugins, Skills, and Hooks and §Tool Pool Assembly, plus build-your-own-agent.md Decision 4, in the VILA-Lab/Dive-into-Claude-Code paper (arXiv 2604.14228). All section references below are to architecture.md unless noted.

### 1. The graduated context-cost hierarchy

The paper (§Four Extension Mechanisms) is explicit about the cost tiers:

| Mechanism | Context Cost | Key Capability |
|:--|:--|:--|
| Hooks | Zero | 27 events, 4 execution types (shell, LLM, webhook, subagent verifier) |
| Skills | Low | SKILL.md with 15+ YAML frontmatter fields, injected via SkillTool meta-tool |
| Plugins | Medium | 10 component types (commands, agents, skills, hooks, MCP, LSP, styles, channels, settings, user config) |
| MCP Servers | High | External tools via 7 transport types (stdio, SSE, HTTP, WebSocket, SDK, IDE) |

The cost tiers are not cosmetic. Every pool-assembly decision in the harness honors them — Hooks never touch the context window, Skills inject only on demand, Plugins consume budget proportional to their active components, and every MCP tool carries schema and resource tokens on every turn it is active.

### 2. Decision tree — which mechanism to reach for

Traverse top-down. Stop at the first mechanism that satisfies the requirement.

```
Does the behaviour happen AROUND tool calls (before, after, on stop)?
├─ Yes → Hook.
└─ No  → Is it project-specific guidance the agent should consult on demand?
         ├─ Yes → Skill.
         └─ No  → Does it bundle multiple component types (commands + agents + hooks + MCP)?
                  ├─ Yes → Plugin.
                  └─ No  → Does it expose a NEW tool surface (API the harness doesn't know)?
                           ├─ Yes → MCP Server.
                           └─ No  → You don't need an extension. Use CLAUDE.md or a chat message.
```

The most common mis-reach: starting at MCP when a Hook or Skill would suffice. A server that runs Prettier is a Hook, not an MCP. A recipe for Prisma migrations is a Skill, not an MCP. Reach for MCP when and only when the capability is a tool the harness does not already have — and even then, check whether a `Bash` invocation from a Hook would carry less context cost.

### 3. Hooks — 27 events, 4 execution types

From architecture.md §Four Extension Mechanisms:

- **27 hook events** across 5 categories (PreToolUse, PostToolUse, Stop, SubagentStop, and lifecycle phases). The paper references this exact count — resist the urge to invent new events.
- **4 execution types**: shell commands, LLM-evaluated expressions, webhook calls, subagent verifiers. Shell is the default; LLM-evaluated fires a small model call against the hook's condition.
- Configured in `.claude/settings.json`. Matcher syntax is a regex against tool names (`Edit|Write`) or path globs.
- Stdout is fed back to the agent as tool output; non-zero exit on a PreToolUse hook blocks the call.

Canonical uses:

```json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "node .claude/deny-generated.js \"$CLAUDE_FILE_PATHS\"" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "pnpm lint --fix \"$CLAUDE_FILE_PATHS\"" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "pnpm test --run" }] }
    ]
  }
}
```

Hook anti-patterns documented by the paper and community:

- Firing a hook that triggers another hook without idempotency — a loop.
- Matcher `.*` on PostToolUse, causing every Read/Grep to spawn side effects.
- Hooks that mutate files the agent is mid-editing; PostToolUse runs before the next Read.

### 4. Skills — low context, on-demand injection

Skills live at `.claude/skills/<name>/SKILL.md`. The paper (§Extensibility) cites "15+ YAML frontmatter fields." Minimum viable frontmatter is `name` + `description`; practical sets include `tools`, `disallowedTools`, `version`, `model`, and `scope`.

Injection semantics (architecture.md §Three Injection Points — `assemble()`):

- The frontmatter `description` is indexed.
- The body loads on demand when the description matches the current task.
- SkillTool is the meta-tool that performs the injection.
- The subdirectories `scripts/` and `references/` are available to Read but do not enter context on invocation.

Classifier drift is the dominant failure mode (see failure modes below): if the frontmatter `description` says one thing and the body does another, the SkillTool classifier mis-routes. Write descriptions as "Use this skill when <concrete trigger phrase>" and mirror the trigger language in the body's first heading.

### 5. Plugins — 10 component types

The paper cites 10 component types in a plugin manifest: commands, agents, skills, hooks, MCP servers, LSP servers, output styles, channels, settings, user config. A plugin is the right mechanism when multiple component types must install together as a coherent bundle.

Sizing rule of thumb:

- 1-2 components → ship them directly (a hook in `.claude/settings.json`, a skill in `.claude/skills/`). No plugin wrapper.
- 3+ components that share a theme → plugin.
- Plugin with only hooks, nothing else → still a plugin only if the hooks need to be versioned and distributed; otherwise commit them to the repo.

The failure mode to watch: plugin bloat. An installed plugin's components all count toward the pool even when not triggered. Trim aggressively.

### 6. MCP Servers — 7 transport types

From architecture.md §Four Extension Mechanisms, MCP transports are `stdio`, `SSE`, `HTTP`, `WebSocket`, `SDK`, and `IDE` (the paper cites 7; implementations may pack variants into a single label). The paper is explicit that MCP is the highest-cost mechanism and should be reserved for genuinely new tool surfaces.

Practical MCP discipline:

- Each MCP server's tool schemas count against the context window every turn they are active.
- The harness's built-in tool count is already up to 54 (architecture.md §Tool Pool Assembly). Adding 20 MCP tools on top meaningfully shrinks usable context.
- MCP tools run under the same permission gate as built-ins — deny rules apply across the whole pool.
- The 7 transport variants matter for latency and reliability, not for what the model sees; pick stdio locally and HTTP/SSE for remote.

### 7. Tool pool assembly — 5 steps

From architecture.md §Tool Pool Assembly (5-step pipeline):

1. **Base enumeration** (up to 54 tools)
2. **Mode filtering** (active permission mode decides which classes are visible)
3. **Deny rule pre-filtering** (blanket-denied tools removed entirely)
4. **MCP integration** (MCP tools added after deny-filter)
5. **Deduplication**

Two consequences worth internalising:

- Deny rules are enforced BEFORE the model ever sees the tool. Denied tools are not in the pool; the model cannot ask for them. This is the paper's paragraph on "strip denied tools from the model's view entirely" (§Permission System).
- MCP tools come in AFTER the deny-filter pass. If you want to block an MCP tool, add an explicit deny rule — the MCP server's own allow-list does not run first.

### 8. Three injection points

The paper (§Three Injection Points) names the three places a mechanism can intervene:

- **assemble()** — What the model sees. Hooks inject context here, skills load SKILL.md bodies here, CLAUDE.md gets read here.
- **model()** — What the model can reach. Tool pool assembly happens here; MCP tools and skill-tool meta-tools become visible.
- **execute()** — Whether/how an action runs. Permission rules, PreToolUse / PostToolUse hooks, Stop hooks.

Mapping mechanisms to injection points:

| Mechanism | assemble | model | execute |
|:--|:--:|:--:|:--:|
| Hooks | yes (context injection) | - | yes (pre/post) |
| Skills | yes (SKILL.md body) | yes (SkillTool meta) | - |
| Plugins | inherits from components | inherits | inherits |
| MCP Servers | yes (tool schemas) | yes (tools) | - |

This map is the reason Hooks are zero-cost at assemble() and Skills are low-cost — they do not pre-populate the context.

### 9. Cost-budgeting rule of thumb

For a session that is expected to last >10 turns:

- Hooks: unlimited.
- Skills: hundreds are fine; only frontmatter descriptions are indexed baseline.
- Plugins: enumerate active components; budget per MCP server, per always-on Skill.
- MCP: budget as if every tool schema adds ~200-400 tokens to every turn. 20 MCP tools means ~4-8k tokens per turn before the conversation starts.

### 10. Common misunderstandings

1. "MCP is 'the' extension mechanism." No. MCP is the highest-cost one and the last one to reach for.
2. "Skills all load at startup." No. Only the frontmatter descriptions are indexed; bodies load on demand via SkillTool.
3. "Hooks fire in the model's turn and cost tokens." Hooks run externally; their stdout enters context as tool output but the hook execution itself is free.
4. "Plugin component counts are additive with no penalty." Every plugin component contributes to pool assembly; unused plugins still claim budget.

### 11. Relationship to other packs

- `claude-code-guide` — the broader reference; extensibility is one of its sections.
- `subagent-delegation-three-isolation-modes` — subagents are spawned via AgentTool (a tool-pool entry); this pack explains where it sits in the pool.
- `injection-surface-audit` — MCP and hook-injected context are injection surfaces; this pack places them, that pack audits them.