Deel C · Module 05
Distribueren: plugins
Hoe deel je dit met je team?
Leerdoelen
Na deze module kun je:
- voor elk bestand in een plugin aanwijzen wat het in je sessie wordt, en hoe het heet (namespace, MCP-toolnaam);
- een bestaande
.claude/-setup omzetten naar een plugin, en de dubbele hooks en botsende namen voorspellen die daarbij ontstaan; - uitleggen hoe een marketplace, install-scopes en versies samenwerken, en wat een plugin kost en mag in elke sessie.
Voorkennis-check
Twee vragen over de componenten die een plugin bundelt. Fout? Lees C1 Sturen en C3 MCP eerst terug.
Waar zitten we?
Een plugin voegt geen nieuw gedrag toe aan de harness (laag 4): hij verpakt wat je in C1–C4 leerde. Daarmee raakt hij ook laag 5: wie installeert wat, welke versie, welke bronnen zijn toegestaan. Distributie is een organisatievraag.
De stof in drie lagen
Kern ± 5 min lezen, daarna door de bestanden klikken
Alles uit de vorige modules werkt zonder plugin: een skill in .claude/skills/, een agent in .claude/agents/, een hook in settings.json, een server in .mcp.json. Voor één project is dat prima. Maar zodra een tweede repo of een collega dezelfde setup wil, ga je kopiëren, en kopieën lopen uit elkaar.
Een plugin is een map met die componenten, plus meestal een manifest (.claude-plugin/plugin.json). Hij wordt als één eenheid geïnstalleerd, aan- en uitgezet en bijgewerkt. Een marketplace is een repo met een catalogus (marketplace.json) die zegt welke plugins er zijn en waar ze staan.
Use a plugin when you want several skills, subagents, hooks, or MCP servers packaged as one unit.
Drie dingen veranderen als je iets in een plugin zet:
- Namen krijgen een prefix.
/reviewwordt/team-tools:review, de agentreviewerwordtteam-tools:reviewer. Zo kunnen twee plugins allebei eenreviewhebben. Hooks krijgen géén prefix. - Paden worden relatief aan de plugin. Gebruik
${CLAUDE_PLUGIN_ROOT}, want de installatiemap verandert bij elke update. - Het staat overal aan. Een ingeschakelde plugin hoort bij elke sessie: descriptions in de context, servers als proces, hooks die vuren.
Klik hieronder door een marketplace met één plugin. Bekijk per bestand wat het in je sessie wordt, waar het zonder plugin zou staan, en waar het misgaat.
Samengevat: skills onderwijzen, subagents isoleren, hooks dwingen, MCP verbindt, en plugins distribueren de rest. Een plugin is de verpakking, niet de inhoud.
Verdieping layout, marketplace, scopes, kosten, vertrouwen
De standaardlayout
| Component | Locatie | In je sessie |
|---|---|---|
| Manifest | .claude-plugin/plugin.json | naam (namespace), versie, metadata; optioneel |
| Skills | skills/<naam>/SKILL.md | /plugin:naam |
| Agents | agents/*.md | subagent plugin:naam |
| Hooks | hooks/hooks.json | samengevoegd met al je andere hooks |
| MCP-servers | .mcp.json | tools als mcp__plugin_<plugin>_<server>__<tool> |
| Executables | bin/ | op de PATH van de Bash-tool |
| Verder | .lsp.json, output-styles/, monitors/, workflows/, themes/ | code intelligence, stijlen, achtergrondmonitors … |
Alleen plugin.json hoort in .claude-plugin/. Al het andere staat in de plugin-root. Een CLAUDE.md in de plugin-root laadt niet als context: wil je teamconventies meeleveren, zet ze dan in een skill.
Marketplace: catalogus, geen winkel
Een marketplace is een directory (meestal een git-repo) met .claude-plugin/marketplace.json: een name, een owner en een lijst plugins met per plugin een name en een source. De source is een pad binnen de marketplace of een verwijzing naar een andere repo. Je voegt een marketplace één keer toe en installeert dan op naam:
De installatielus
/plugin marketplace add org/team-marketplace # GitHub-repo, URL of lokaal pad
/plugin install team-tools@team-marketplace # naam@marketplace
/plugin # Discover / Installed / Marketplaces
/reload-plugins # wijzigingen laden zonder herstart
Anthropic heeft een officiële marketplace (claude-plugins-official), die Claude Code bij de eerste interactieve sessie toevoegt. Er is ook een community-marketplace. Al het andere, ook de marketplace van je eigen team, heet third-party.
Whatever the tier, a plugin you install can run code with your user privileges.
Install-scopes
| Scope | Aan voor | Opgeslagen in |
|---|---|---|
| user | jou, in al je projecten op deze machine | je user settings |
| project | iedereen in deze repo | .claude/settings.json (gecommit); elke collega installeert nog wel op zijn eigen machine |
| local | jou, alleen in deze repo | je lokale, niet gedeelde projectsettings |
Via managed settings kan een organisatie marketplaces toestaan of blokkeren en plugins verplicht installeren. Dat komt terug in D4.
Wat een plugin kost, ook als je hem niet gebruikt
An enabled plugin is part of every session, not only the sessions where you use it.
- Context: naam en description van elke skill en agent die het model zelf mag starten, in elke beurt. De volledige tekst laadt pas bij gebruik. MCP-tools volgen tool search (C3).
- Processen: MCP-servers draaien mee; hooks vuren op hun events.
- Rechten: wat de plugin draait, draait als jou.
Zet een plugin die je niet gebruikt uit (/plugin of claude plugin disable) in plaats van hem te laten staan. In /plugin toont de officiële marketplace per plugin een schatting van de contextkosten.
Wanneer (nog) geen plugin?
Werk je alleen, in één project? Dan is .claude/ genoeg, of ~/.claude/ voor al je projecten. Een plugin loont zodra je gaat delen: met collega's, over repo's heen, of met versies die je gecontroleerd uitrolt. De docs noemen als trigger: "A second repository needs the same setup".
Onder de motorkap manifest, variabelen, versies, ontwikkelen, valkuilen
Het manifest
name is het enige verplichte veld: kebab-case, zonder spaties, @, : of padscheidingstekens. Elke component krijgt die naam als namespace. Namen die op Anthropic lijken (claude-…, anthropic-…, official-claude-…) weigert claude plugin validate. Verder optioneel:
version: zet je die, dan blijven gebruikers op die versie tot jij hem verhoogt. Uitzondering: een plugin uit een marketplace die je met een lokaal pad toevoegde, laadt ter plekke en wordt niet vastgezet.dependencies: plugins die aan moeten staan om deze te laten werken.userConfig: waarden die Claude Code bij het inschakelen vraagt, zoals een API-token ("sensitive": true). Hooks krijgen ze alsCLAUDE_PLUGIN_OPTION_<KEY>.- Componentpaden (
skills,agents,hooks,mcpServers, …) als je van de standaardlayout afwijkt. Let op:skillsvoegt toe aan de standaardmap,agentsencommandsvervangen hem.
Drie padvariabelen
| Variabele | Wijst naar | Gebruik voor |
|---|---|---|
${CLAUDE_PLUGIN_ROOT} | de geïnstalleerde versie van de plugin; verandert bij elke update | meegeleverde scripts, binaries, config |
${CLAUDE_PLUGIN_DATA} | ~/.claude/plugins/data/<id>/; blijft bestaan over updates | node_modules, caches, gegenereerde code |
${CLAUDE_PROJECT_DIR} | de projectroot | projectbestanden |
Ze worden ingevuld in hook-commando's, MCP- en LSP-config, en in de Markdown van skills en agents. Ze staan niet in de omgeving van commando's die Claude via de Bash-tool draait. Schrijf de verwijzing dus in de skilltekst; Claude Code vult het pad in bij het laden.
Ontwikkelen zonder marketplace
Lokale ontwikkellus
claude plugin validate ./team-tools # manifest, frontmatter, hooks-JSON
claude --plugin-dir ./team-tools # laad de plugin voor één sessie
/reload-plugins # na een wijziging, in de sessie
claude plugin details team-tools # wat is er geladen? (component inventory)
Valkuilen bij omzetten
- Dubbele hooks: staat dezelfde hook nog in je
settings.json, dan draait hij twee keer per event. Hooks hebben geen namespace. - Twee versies van alles:
/review(uit.claude/) en/team-tools:review(uit de plugin) bestaan naast elkaar tot je de originelen verwijdert. - Matchers op MCP-namen:
mcp__issues__.*vuurt niet meer; de pluginversie heetmcp__plugin_team-tools_issues__…. - Plugin-subagents negeren
hooks,mcpServersenpermissionModein hun frontmatter. - State in de plugin-root is na de volgende update weg. Gebruik
${CLAUDE_PLUGIN_DATA}.
Uitgewerkt voorbeeld: van .claude/ naar een team-marketplace
Een team heeft in één repo een review-skill, een security-agent en een formatter-hook. Een tweede repo wil hetzelfde. In vier stappen wordt het één plugin in een eigen marketplace-repo.
Stap 1–2: structuur en kopiëren (vanuit de projectroot)
mkdir -p team-marketplace/.claude-plugin team-marketplace/plugins/team-tools/.claude-plugin
cd team-marketplace/plugins/team-tools
cp -r ../../../.claude/skills ../../../.claude/agents .
mkdir -p hooks scripts && cp ../../../.claude/hooks/format.sh scripts/
Stap 3: plugins/team-tools/hooks/hooks.json
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [ { "type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh" } ] }
]
}
}
- Hetzelfde
hooks-object als insettings.json, alleen het pad verandert: van$CLAUDE_PROJECT_DIR/.claude/hooks/naar${CLAUDE_PLUGIN_ROOT}/scripts/. Verwijder daarna de hook uit jesettings.json, anders draait hij twee keer.
Stap 4: manifest en catalogus
// plugins/team-tools/.claude-plugin/plugin.json
{ "name": "team-tools", "version": "1.0.0",
"description": "Review-skill, security-agent en formatter van het platformteam" }
// .claude-plugin/marketplace.json
{ "name": "team-marketplace",
"owner": { "name": "Platformteam" },
"plugins": [ { "name": "team-tools", "source": "./plugins/team-tools" } ] }
- name wordt de namespace:
/team-tools:review. Houd hem gelijk aan denamein de marketplace-entry. - version: collega's blijven op 1.0.0 tot je verhoogt. Zo rol je wijzigingen gecontroleerd uit.
- source: pad vanaf de marketplace-root, de map die
.claude-plugin/bevat.
Daarna: claude plugin validate ./team-marketplace, pushen, en collega's doen /plugin marketplace add org/team-marketplace en /plugin install team-tools@team-marketplace. Voor de tweede repo zet je de plugin op project-scope, zodat iedereen die de repo opent hem aangeboden krijgt.
Zet een losse setup om naar een plugin en installeer hem via je eigen marketplace
Starter: oefenrepo/c5-plugins/. Een project met een skill /review, een subagent security-reviewer en een hook die elke edit logt naar .claude/edits.log. Skill en agent beginnen hun antwoord met een herkenbare kopregel. Je hebt Claude Code en jq nodig.
Opdracht
- Kopieer de map,
git init && git add -A && git commit -m start. Startclaudeen controleer dat/reviewwerkt. - Maak naast
.claude/een mapteam-tools/met.claude-plugin/plugin.json(name: "team-tools",version: "1.0.0"). Kopieerskills/enagents/. Zet het script inteam-tools/scripts/en maakteam-tools/hooks/hooks.jsonmet${CLAUDE_PLUGIN_ROOT}/scripts/log-edit.sh. claude plugin validate ./team-tools, danclaude --plugin-dir ./team-tools. Typ/en zoek beide review-varianten. Laat Claude één regel insrc/app.pyaanpassen en bekijk.claude/edits.log.- Ruim op: verwijder
.claude/skills,.claude/agentsen de hook uit.claude/settings.json. Herhaal de edit en kijk opnieuw in het log. - Marketplace. Maak
team-marketplace/.claude-plugin/marketplace.jsonen verplaatsteam-tools/naarteam-marketplace/plugins/. Danclaude plugin marketplace add ./team-marketplaceenclaude plugin install team-tools@team-marketplace. Startclaudezonder--plugin-dir. - Maak het kapot. Zet
plugin.jsonper ongeluk in de plugin-root in plaats van in.claude-plugin/, en zet ookskills/in.claude-plugin/. Wat zegtclaude plugin validate? Wat laadt er?
Verwacht resultaat
Stap 3: validate eindigt met ✔ Validation passed. In het /-menu staan /review én /team-tools:review, en de agents security-reviewer en team-tools:security-reviewer. Na één edit staan er twee regels in edits.log: de hook draait twee keer, uit de settings en uit de plugin.
Stap 4: alleen de geprefixte varianten blijven, en per edit verschijnt er één logregel.
Stap 5: de commando's melden Successfully added marketplace: team-marketplace en Successfully installed plugin: team-tools@team-marketplace (scope: user). claude plugin list toont de plugin als enabled, en /team-tools:review werkt in elk project op je machine.
Stap 6: zonder manifest op de juiste plek laadt de plugin met de naam uit de marketplace-entry of de mapnaam (het manifest is optioneel). Componenten in .claude-plugin/ worden niet gevonden: de skill is weg. Zet alles behalve plugin.json terug in de plugin-root.
Als het niet werkt, kijk naar …
- Hook draait niet uit de plugin. Is
scripts/log-edit.shexecutable (chmod +x)? Staat inhooks.jsonhet object{"hooks": {…}}, in hetzelfde formaat als in settings? - Wijziging zie je niet.
/reload-pluginsna het aanpassen van pluginbestanden. Een marketplace op een lokaal pad laadt de plugin ter plekke; bij een gehoste marketplace metversionmoet je de versie verhogen voordat gebruikers de wijziging krijgen. Plugin not found in marketplace. Denamein de marketplace-entry moet overeenkomen met wat je installeert, ensourceis relatief aan de map met.claude-plugin/.- Opruimen na de oefening.
claude plugin marketplace remove team-marketplaceverwijdert de marketplace en de-installeert de plugins eruit.