← Terug naar het leerpad  ·  Augmented Organisation

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)

skills · onderwijzen subagents · isoleren hooks · dwingen plugins · distribueren MCP · verbinden

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/.

DimensieSkillSubagentHookPluginMCP-server
WatMarkdown-procedure (SKILL.md + optionele scripts/referenties)Claude-instantie met eigen contextvenster, systeemprompt en tool-lijstScript / HTTP / MCP-tool / prompt / agent op een lifecycle-eventInstallatiebare bundel met manifest (.claude-plugin/plugin.json)Langlopend proces dat externe tools exposeert
Wie triggertModel (auto bij matchende description) of jij via /naamHoofdagent delegeert (Task/Agent-tool)De harness, op event — het model heeft er geen weet vanJij: /plugin installModel roept een tool van de server aan
LifetimeLeeft binnen één conversatie (bestand persists, de geladen skill niet)Één afgebakende taak, dan sterft de contextÉén event, draait tot completion, exitedPersistent pakket op schijf; de inhoud heeft eigen lifetimesDaemon die sessies en editors overleeft
GarantieGeen — het is een verzoek; het model kan weigeren of ernaast grijpenIsolatie + samenvattende terugkeer; geen determinismeAfgedwongen — exit code 2 blokkeert; exit 2 op Stop verbiedt stoppenZelfde setup in elk project; versie = rollback-hendelVerbinding, geen beleid
Loadmoment (docs)Beschrijvingen bij session start; volledige body bij gebruikBij spawn: verse geïsoleerde contextOp trigger; de handler draait buiten het contextvensterInstall-time; componenten laden als hun primitiefToolnamen 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/.mdsettings.json (hooks-key) of plugin hooks/hooks.jsonMarketplace, git-repo of lokale map → ~/.claude/plugins/.mcp.json of claude mcp add; apart proces
Trust boundary (mcp.directory)Vertrouwd pad, draait in agent-contextGeïsoleerd; tool-lijst is scoping, geen security boundaryDraait met jouw shell-rechten, volledige filesystem-accessVertrouwd bij install — audit vóór adoptieAfzonderlijk 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.md file 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.”

Anti-patroonFeiten over je codebase in skills (kolommen van je user-tabel): “the model already discovers that with one grep. Save skill space for methodology that grep won't surface” (shrikar). En: bij meer dan ~5–6 skills met overlappende beschrijvingen gaat de router inconsistente kanten op — één canonieke naam per taak (mcp.directory, pitfall 5).
Anti-patroon“Always do X” als skill. De Anthropic-blog is bot: “The model choosing to run a formatter is different from the formatter running automatically” — dat is hook-territorium.

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

AspectSkillSubagent
WatHerbruikbare instructies, kennis, workflowsGeïsoleerde worker met eigen context
Context-impactVoegt toe aan je main windowEigen window; alleen de samenvatting keert terug
Best voorReferentiemateriaal, aanroepbare workflowsTaken 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.

Anti-patroonTwee backfires uit de praktijk (Imoto): een subagent kan halverwege niet een vraag aan jou stellen — bij ambiguousiteit gokt hij; en de terugkeer is lossy by design. Fix: laat de instructies evidence teruggeven (paths, aantallen), niet alleen conclusies. Derde addertjes: permissiemodes worden geërfd van de parent en kunnen de voorzichtige 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

TypeWatDeterministisch?
commandShell-commando; stdin = JSON-payload, beslis via exit-code of JSON op stdoutJa
httpPOST van de event-JSON naar een endpointJa
mcp_toolMaak een tool-call op een geconfigureerde MCP-server; tekstoutput als stdoutJa
promptStuur een prompt naar een Claude-model voor single-turn evaluatie; besluit komt als JSON terugNee — model-judgment
agentSpant een subagent die met Read/Grep/Glob voorwaarden verifieert vóór zijn besluitNee — 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

Setup SessionStart InstructionsLoaded ConfigChange CwdChanged DirectoryAdded FileChanged WorktreeCreate WorktreeRemove SessionEnd

Beurt-cadans — per assistent-beurt

UserPromptSubmit UserPromptExpansion Stop StopFailure TeammateIdle

Tool-cadans — per tool-aanroep in de agentic loop

PreToolUse PermissionRequest PermissionDenied PostToolUse PostToolUseFailure PostToolBatch SubagentStart SubagentStop TaskCreated TaskCompleted Elicitation ElicitationResult

Async / context-hygiëne — naast de hoofdflow

Notification MessageDisplay PreCompact PostCompact PreModelSwitch PostModelSwitch

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).

Anti-patroonDe blockerende hook die een lus bouwt (Imoto, met zijn eigen woorden): “I once wrote a 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.”
Anti-patroonVergeten 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.

Anti-patroonPlugins als privé, mutatebare opslagruimte: direct tweaken onder ~/.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).

Anti-patroonEen MCP-server bouwen voor wat eigenlijk “hoe werken wij hier”-kennis is — dan heb je een API rond je eigen wiki gebouwd en betaalt elke sessie voor schema's die je als tekst had kunnen documenteren. De andere kant op: een skill schrijven die “roep de API maar aan” voorschrijft, want dan ontbreekt de tool die het moet uitvoeren.

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:

AsVraagUitslag
LifetimeHoe 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.
TriggerMoet 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.
OwnershipWat 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:

Moet dit gebeuren ook als het model besluit het niet te doen?ja → HOOK
Leveren deze zijtaken output die de parent niet hoeft te bewaren?ja → SUBAGENT
Wil je het model een workflow leren die inspringt wanneer relevant?ja → SKILL
Moet dit meer dan één persoon installeren, met versionering en rollback?ja → PLUGIN (om het bovenstaande te shippen)
Niks van dat alles?dan: één regel in CLAUDE.md, of een MCP-server bij live externe systemen

“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)

Onze aanvullingVoor de blog-plugin: scheiding intentie vs. stijl. De plugin levert structuur (outline, argumenten, bronnen), creatieve keuzes blijven bij het model; orchestratie via subagent + hooks, niet via één mega-prompt. Mitigatie van agent-in-agent: least-privilege tool-lijsten, read-only mounts, apart output-volume. Sandboxing is pas relevant bij multi-tenant of onbetrouwbare code — lokaal volstaan Docker-netwerken en mount-beperkingen.

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 met paths:-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: true voorkomt 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.

Primair — Anthropic officiële docs (code.claude.com/docs)

Extend Claude Code (features-overview)de officiële vergelijkingstabellen, context-kostentabel en load-diagrammen · cache
Extend Claude with skillsfrontmatter-referentie, bundled skills, progressive disclosure, agentskills-standaard · cache
Sub-agentsfork-gedrag, skills-preload, agent-naming, wat laadt bij startup · cache
Hooks reference & Hooks guide33 events met schema's, 5 hook-types, exitcodes/JSON-besluiten, async & HTTP hooks · cache · cache
Plugins overview & Manifest referenceplugin = bundle die als één unit installeert; default-layout en manifest-velden · cache · cache
MCPtransports, authenticatie, tool search, /mcp-diagnostiek · cache
Memory · Output styles · Dynamic workflowsCLAUDE.md-lagen en rules; styles; workflow-scripts · cache · cache · cache

Secundair — blogs en veldgidsen

Steering Claude Code — Anthropic-blog, Michael Segner, 18 juni 2026de zeven instructiemethoden met loadmoment/compactie/autoriteit-tabel; “real guardrail needs to be deterministic” · cache
Skills vs Subagents vs Plugins vs Hooks — mcp.directory, mei 2026de beste composability-patronen (zes), decision flowchart met volgorde-argumentatie en zeven production pitfalls · cache
A mental model that finally sticks — Shrikar Archak, 12 mei 2026classificatie op lifetime/trigger/ownership; de vijf-zinnen-model; “the plugin is just the postage” · cache
When Each Backfires — Ken Imoto, dev.to, 13 sep 2026backfires en footguns: exit-2-deadlock, description-belasting, lossy samenvattingen, permissie-erving · cache
53 architecture diagrams — cc.bruniaux.comvisuele referentie: hooks-pipeline, MCP-architectuur, multi-agent-topologieën, config-precedentie · index-cache
claude-code-book — huifer (GitHub)Chinestalige diepe analyse van de CLI; “dubbelsporig”: plugins = CLI-capaciteit, skills = AI-gedrag · cache