Claude Code Extensie-Taxonomie
Skill · Subagent · Hook · Plugin · MCP-server — wat werkt wanneer, en waarom.
Opgesteld 15 november 2026 · alle uittes verbatim uit sources/ (gecacht 2026-11-15)
1Het kernidee in één zin
Claude Code is een agentic loop. Alles wat je toevoegt, hangt aan een van vier assen: wat het model moet weten (skills), wat het model mag doen (MCP), wat het model moet doen zonder keus (hooks), en hoe je dat deelt (plugins). Een subagent is geen vijfde as — het is een geïsoleerde instantie van de loop zelf.
De officiële docs formuleren het precies zo:
“Extensions plug into different parts of the agentic loop.”
De bruikbaarste één-regel-verdeling komt van Shrikar Archak, en elk onderscheid in dit naslagwerk volgt uit deze vijf zinnen:
Skills are instructions the model reads.
MCP servers are functions the model calls.
Hooks are commands the harness runs.
Subagents are workers the main agent spawns.
Plugins are how you distribute the first four.
“Every other distinction follows from those five sentences.”
Wie maar één zuil onthoudt, kiest de correctiekloot van Ken Imoto:
“Hooks remove a decision from the model, Skills add one, Subagents quarantine one.”
2De matrix: vijf primitieven, acht dimensies
Samengesteld uit de officiële docs (rijen loadmoment en contextkost), de axes-van-Shrikar (lifetime/trigger/ownership) en de trust-boundary-analyse van mcp.directory. Elke cel is terug te vinden in sources/.
| Dimensie | Skill | Subagent | Hook | Plugin | MCP-server |
|---|---|---|---|---|---|
| Wat | Markdown-procedure (SKILL.md + optionele scripts/referenties) | Claude-instantie met eigen contextvenster, systeemprompt en tool-lijst | Script / HTTP / MCP-tool / prompt / agent op een lifecycle-event | Installatiebare bundel met manifest (.claude-plugin/plugin.json) | Langlopend proces dat externe tools exposeert |
| Wie triggert | Model (auto bij matchende description) of jij via /naam | Hoofdagent delegeert (Task/Agent-tool) | De harness, op event — het model heeft er geen weet van | Jij: /plugin install | Model roept een tool van de server aan |
| Lifetime | Leeft binnen één conversatie (bestand persists, de geladen skill niet) | Één afgebakende taak, dan sterft de context | Één event, draait tot completion, exited | Persistent pakket op schijf; de inhoud heeft eigen lifetimes | Daemon die sessies en editors overleeft |
| Garantie | Geen — het is een verzoek; het model kan weigeren of ernaast grijpen | Isolatie + samenvattende terugkeer; geen determinisme | Afgedwongen — exit code 2 blokkeert; exit 2 op Stop verbiedt stoppen | Zelfde setup in elk project; versie = rollback-hendel | Verbinding, geen beleid |
| Loadmoment (docs) | Beschrijvingen bij session start; volledige body bij gebruik | Bij spawn: verse geïsoleerde context | Op trigger; de handler draait buiten het contextvenster | Install-time; componenten laden als hun primitief | Toolnamen bij session start; full schema on demand |
| Contextkost (docs) | Laag (beschrijvingen elke request) | Geïsoleerd van de main session | “Zero, unless hook returns additional context” | De som van zijn delen | “Low until a tool is used” (tool search staat aan) |
| Waar het leeft | .claude/skills/, ~/.claude/skills/ of in plugin | .claude/agents/ | settings.json (hooks-key) of plugin hooks/hooks.json | Marketplace, git-repo of lokale map → ~/.claude/plugins/ | .mcp.json of claude mcp add; apart proces |
| Trust boundary (mcp.directory) | Vertrouwd pad, draait in agent-context | Geïsoleerd; tool-lijst is scoping, geen security boundary | Draait met jouw shell-rechten, volledige filesystem-access | Vertrouwd bij install — audit vóór adoptie | Afzonderlijk proces; authenticatie bij de server |
De context-kostentabel in features-overview en de 5-dimension matrix in mcp.directory.
3Skill — onderwijzen
“Skills extend what Claude can do. Create a
SKILL.mdfile with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with/skill-name.”
De economie van skills zit in progressive disclosure: alleen naam + beschrijving zijn altijd in context (enkele tientallen tokens per skill); de body laadt bij gebruik; scripts en referentiebestanden pas als ernaar verwezen wordt. Daarom geldt: “a skill's body loads only when it's used, so long reference material costs almost nothing until you need it” (zelfde doc). Een skill mag dus best lang zijn — de beschrijving niet.
De beschrijving is een routing-key, geen samenvatting
Het model beslist per beurt op basis van de description. Imoto's mislukking is de leerzame:
“My original ‘always lint’ Skill failed because I was asking a probabilistic router to behave deterministically. The router did its job: it routed. Sometimes away from me.”
En mcp.directory formuleert de vuistregel die de hele taxonomie snijdt:
“Hooks are for things the model cannot be trusted to follow; Skills are for things the model needs to know.”
Skills-doc (frontmatter-referentie, disable-model-invocation, context: fork) en de Agentskills-openstandaard (agentskills.io) voor portabiliteit over editors heen.
4Subagent — isoleren
Een subagent is geen “collega-agent” maar een eenmalig contextvenster. De officiële formulering:
“The subagent then runs in its own fresh context window, and the only thing that returns to your main session is the subagent's final message (often the aggregated result of many subtasks) plus metadata.”
Shrikar geeft de beste intuïtie: “a subagent is to the main agent what subprocess.run() is to a parent process.” Het draait met eigen systeemprompt, eigen tool-lijst, optioneel ander model; de 40 bestandslezingen die het deed om tot het antwoord te komen, betreden je hoofdcontext nooit. Het patroon schaalt: subagents kunnen tot vijf nesting-niveaus diep, en dynamic workflows orkestreren er tientallen tot honderden vanuit een script.
Wanneer skill vs. subagent
| Aspect | Skill | Subagent |
|---|---|---|
| Wat | Herbruikbare instructies, kennis, workflows | Geïsoleerde worker met eigen context |
| Context-impact | Voegt toe aan je main window | Eigen window; alleen de samenvatting keert terug |
| Best voor | Referentiemateriaal, aanroepbare workflows | Taken die veel bestanden lezen, parallel werk, gespecialiseerde workers |
(bron: features-overview, Skill-vs-Subagent-tabel · cache)
Ze zijn geen rivalen maar gelaagden: “A subagent can preload specific skills (skills: field). A skill can run in isolated context using context: fork” (zelfde doc). De stuurregel uit de steering-blog: wil je de procedure in de hoofdthread zien en bijsturen → skill; maakt de tussenwerk-output je niets uit → subagent.
tools-allowlist overschrijven — “treat the tool list as scoping, not a security boundary.”Sub-agents-doc (fork-gedrag, names, preloading) en Workflows-doc voor de volgende schaal-trap.
5Hook — dwingen
“Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle.”
Het wezenlijke verschil met alles anders: de trigger is de harness, niet het model. “The model has zero awareness that hooks exist” (shrikar). Daarom is een hook de enige primitief met een garantie. De Anthropic-blog maakt het principieel:
“A real guardrail needs to be deterministic, and the enforcement methods are hooks and permissions.”
Contextkost: “Zero, unless hook returns additional context” (features-overview). De handler draait buiten het contextvenster; alleen bij een blokkerende hook gaat stderr terug zodat Claude weet waarom iets werd geweigerd.
De vijf hook-types
| Type | Wat | Deterministisch? |
|---|---|---|
command | Shell-commando; stdin = JSON-payload, beslis via exit-code of JSON op stdout | Ja |
http | POST van de event-JSON naar een endpoint | Ja |
mcp_tool | Maak een tool-call op een geconfigureerde MCP-server; tekstoutput als stdout | Ja |
prompt | Stuur een prompt naar een Claude-model voor single-turn evaluatie; besluit komt als JSON terug | Nee — model-judgment |
agent | Spant een subagent die met Read/Grep/Glob voorwaarden verifieert vóór zijn besluit | Nee — model-judgment |
(bron: hooks reference · cache; de eerste drie types “execute deterministically”, prompt en agent gebruiken “Claude's judgment rather than a set of rules” — steering-blog)
De events: 33 stuks, vier cadensen
Let op: onze eerdere notitie spreekt van 27 events; de referentie noemt er op dit moment 33. De docs groeperen zelf in drie cadences; de vierde (async) is onze ordening naar de praktijk:
Sessie-cadans — eenmaal per sessie
Beurt-cadans — per assistent-beurt
Tool-cadans — per tool-aanroep in de agentic loop
Async / context-hygiëne — naast de hoofdflow
Rood omlijnd = events waarbij exit code 2 blokkeert (PreToolUse: de tool-call; Stop/SubagentStop: het stoppen zelf; UserPromptSubmit: de prompt; PreCompact: de compactie).
Exitcodes: de enige API die ertoe doet
Een command-hook krijgt de event-JSON op stdin en antwoordt: exit 0 = geen bezwaar; exit 2 = blokkeren, stderr gaat naar Claude als reden; exit 0 + JSON op stdout = gestructureerd besluit (permissionDecision: "deny" + permissionDecisionReason) — de geprefereerde vorm voor besluiten die meer zijn dan een snel “nee” (hooks reference).
Stop hook that checked for uncommitted changes and exited 2 if it found any. The agent dutifully refused to stop, tried again, still had uncommitted changes, refused to stop again. I had built a loop with my own hands. The lesson: a Hook that can block is a Hook that can deadlock. Test the exit-2 path before you trust it.”timeout: zonder timeout kan een hook oneindig hangen en de agent blokkeren; een hook die wel stilt op een timeout time-out geeft géén deny-besluit en de tool draait alsnog (mcp.directory, pitfall 6). Stel 5–10 s in en exit zelf clean.Hooks reference (alle event-schema's, decision control, async hooks) en Hooks guide (praktijkinstap). Visueel: “Hooks event pipeline” op cc.bruniaux.com/diagrams.
6Plugin — distribueren
“A Claude Code plugin is a directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit. Most plugins come from a marketplace, which is a catalog that lists plugins and where to fetch each one.”
Het belangrijkste inzicht: een plugin voegt niets toe aan wat de andere vier kunnen. Shrikar: “A plugin adds zero new capability that the underlying primitives don't already have. What plugins give you is distribution.” De vraag “plugin of skill?” is dus misvormd; de echte vraag is “skill, hook of MCP — en daarna: als plugin shippen?” Zijn uitspraak verdient een place mat: “it's a skill, and the plugin is just the postage.”
Standaard-layout
my-plugin/ ├── .claude-plugin/ │ └── plugin.json # manifest (optioneel bij default locaties) ├── skills/ #/SKILL.md — genamespaced: /mijn-plugin:review ├── commands/ # flat .md-bestanden (legacy; skills/ is de toekomst) ├── agents/ # .md subagent-definities ├── hooks/ │ └── hooks.json # top-level "hooks"-key met event map ├── .mcp.json # MCP-serverconfiguraties ├── .lsp.json # taalserverconfiguraties ├── monitors/monitors.json # achtergrondmonitors ├── bin/ # executables op PATH tijdens plugin ├── scripts/ # hook- en utilityscripts (${CLAUDE_PLUGIN_ROOT}/scripts/…)
(bron: Plugin manifest reference — “Save the manifest at .claude-plugin/plugin.json … Put every other plugin file at the plugin root” · cache)
Twee eigenschappen die plugins tot productie-gereedschap maken: het version-veld is je rollback-hendel, en plugin-componenten zijn genamespaced (/mijn-plugin:review) zodat bundels naast elkaar kunnen bestaan.
~/.claude/plugins/ wordt bij de volgende /plugin update overschreven. Override locaal (een eigen skill met dezelfde naam wint) — “Never edit Plugin files in place” (mcp.directory, pitfall 7). En: hooks meesturen in een plugin betekent dat ze op elke teammate's machine met diens rechten draaien — test op minimaal twee omgevingen.Manifest reference, Plugin components (plugin explorer) en Plugin security and trust.
7MCP-server — verbinden
“Claude Code can connect to hundreds of external tools and data sources through the Model Context Protocol (MCP), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.”
MCP is de enige primitief die uitvoerbaarheid toevoegt in plaats van kennis of beleid: “Run a query, hit an API, modify external state” (shrikar). Het is een apart, langlopend proces (stdio, HTTP of SSE) die tools, resources en prompts adverteert alsof het native tools zijn. De garantie is een verbinding, geen beleid — wat het model met de tools mag doen, hangt aan permissies en hooks.
Context-hygiëne is recent sterk verbeterd: “Tool search is on by default, so idle MCP tools consume minimal context” — toolnamen laden bij sessiestart, volledige JSON-schema's blijven achter tot Claude een specifieke tool nodig heeft (features-overview). Check met /mcp en /context all.
MCP vs. skill: de scheidslijn
MCP-server
Executeerbare capaciteit, implementatie is van nature code; moet state buiten één sessie kunnen houden en over vele sessies/gebruikers beschikbaar zijn.
Skill
Advies aan het model over hoe een situatie aan te pakken; natuurlijke taal is de betere encoding. “The ‘instructions’ are really about calling an external service? That's an MCP server's job.”
Combinatie is normaal: een UserPromptSubmit-hook die in de prompt herkende ticket-keys via de Linear-MCP-server ophaalt en in context injecteert — “The Hook does the deterministic fetching; the MCP server does the authenticated network work” (mcp.directory, composability-pattern 5).
MCP-doc (transports, auth, tool search) en modelcontextprotocol.io voor de standaard zelf; architectuur-diagrammen op cc.bruniaux (“MCP architecture: Client-Server protocol”, “MCP rug pull attack chain”).
8De orthogonale assen
Vergelijk primitieven nooit op wat ze doen — “All five of those sentences are true and individually useless” (shrikar). Gebruik drie assen; de beslissing wordt mechanisch:
| As | Vraag | Uitslag |
|---|---|---|
| Lifetime | Hoe lang moet het ding bestaan? | Twee sessies onthouden → géén skill/subagent: MCP-server of hook die naar schijft schrijft. Eén beurt → hook. Eén taak → subagent. |
| Trigger | Moet het model hiervan weten? | Nee → hook. Ja, als advies → skill. Ja, als functie → MCP-tool. “Een andere agent moet het weten, de main niet” → subagent. |
| Ownership | Wat is het verpakkings-unit? | Projectspecifiek → .claude/; team-breed → plugin (postzegel, geen primitief). |
Extra as van de officiële docs: autoriteit. De steering-blog vat elke methode samen als ruil tussen contextkost en autoriteit — zeven instructiemethoden (CLAUDE.md, rules, skills, subagents, hooks, output styles, system-prompt-append) met eigen loadmoment, compressie-gedrag en autoriteit. “Each method trades context cost against authority.” (cache)
En de twee onafhankelijke knoppen erboven: welk model en welk effort-level bepalen hoe capabel het is; de zeven methoden bepalen hoe het zich gedraagt. Verwar die niet.
De zeven-methoden-tabel in de steering-blog; het “Memory hierarchy”- en “Rule placement decision tree”-diagram op cc.bruniaux.
9De beslisboom (vijf vragen)
Gedestilleerd uit mcp.directory (hun flowchart) en onze eigen analyse. Werk van boven naar beneden; stop bij de eerste “ja”. De volgorde is de consequentie:
“Enforcement is the strongest constraint (a Hook can't be opted out of), isolation is the next strongest (a Subagent guarantees a clean context), teaching is third (Skills rely on the model recognizing relevance), and distribution is orthogonal to all three. If you skip the order and reach for a Skill where you needed a Hook, you'll rebuild it as a Hook within a week.”
Onze Sogyo-variant met blog-plugin-vraagstukken staat in Claude-Code-Extensie-Taxonomie.md §7.
10Composability: zes patronen uit de praktijk
De primitieven zijn bewust orthogonaal en stapelen. De zes patronen die mcp.directory uit productie terugvindt:
1 · Plugin = skill + hook
Het brand-pdf-voorbeeld: de skill is de leslaag, de PostToolUse-hook de observatielaag. Gescheiden geïnstalleerd = halve dataset; gebundeld = één install, twee gedragingen.
2 · Subagent loaded een skill
code-reviewer met strakke tool-allowlist (Read, Grep, Glob) laadt de code-review-skill, past de checklist toe, stuurt alleen het rapport terug. De parent ziet de 30 lezingen nooit.
3 · SessionStart seedt voor skills
Hook haalt branch, ticket en on-call op; de deploy-runbook-skill refereert later “naar het huidige ticket” zonder tool-call. Hook = de deterministische omgeving, skill = de workflow.
4 · PreToolUse harden subagents
Subagents erven de hooks van de parent: “The Hook is your last line of defense, and it covers the whole agent tree by default.”
5 · Hook + MCP als duo
UserPromptSubmit scant op ENG-1234, de Linear-MCP-server levert; “the ticket arrives in context the same turn the user mentioned it.”
6 · Skill documenteert de plugin-slash
“The Plugin ships the command; the Skill ships the knowledge about the command.” Zo kan het model /ship ook uitleggen, debuggen en aanpassen.
(alle zes: mcp.directory · cache)
11De rand van de kaart: CLAUDE.md en de nieuwe primitieven
De kaart groeit. Buiten de vijf primitieven noemen de docs inmiddels:
- CLAUDE.md — altijd-aan context; vuistregel uit beide officiële bronnen: “Keep CLAUDE.md under 200 lines” (features-overview) en “give it an owner, and review changes to it like code” (steering-blog). Procedures erin horen niet: “A 30-line procedure in CLAUDE.md. Procedures belong in skills.”
- Rules (
.claude/rules/) — constraints metpaths:-frontmatter die pas laden bij matchende bestanden; onscoped regels zijn “mechanically identical to putting the content in CLAUDE.md”. - Output styles — injecteren in de systeemprompt, nooit gecompressed, hoogste instructie-gewicht; een custom style vervangt standaard de coding-instructies (
keep-coding-instructions: truevoorkomt dat). - Dynamic workflows — “scripts Claude writes that run many subagents in the background and return one result”; orkestratieplannen leven in script-variabelen, niet in de context.
- Cross-session messaging en code intelligence (LSP) — respectievelijk boodschappen tussen sessies en symbool-navigatie met lage contextkost.
- Mods — plugins die hooks als JavaScript-functies in het eigen proces van Claude Code registreren; de reguliere hooks blijven naast mods werken.
(bron: features-overview, steering-blog, hooks reference · cache)
Ze verdienen allemaal een plaats in de matrix, maar geen ervan is een zesde as: het blijven variaties op weten, doen, dwingen, verdelen — of op de loop zelf.
12Geannoteerde bronnen
Alle primaire bronnen zijn als raw markdown gecacht in sources/ (met provenance-header: URL + ophaaldatum). Elk citaat op deze pagina is daarin terug te vinden; wil je een passage verifiëren, grep de cache.