CGS IT Solutions GmbH — Claude Code Training · Erweiterung 5 · Plugins · v0.10.0

Erweiterung 5

Plugin-Entwicklung

Vertiefung zu Modul 10 · Bündeln, verteilen, aktualisieren

Inhalt

1Anatomie und Namen — was drin ist und wie es heißt 2Der Marketplace — Katalog, Quellen, Versionen 3Aktivieren und Grenzen — und was nicht gilt 4Plugin oder Repo-Konfiguration — die Entscheidung Glossar — Begriffe zum Nachschlagen

Was dieses Deck ergänzt

Modul 10 sagt, warum man Konfiguration bündelt. Hier geht es darum, wie das Bündel aussieht — und wo es klemmt.

  1. Ein Plugin ist ein Verzeichnis mit Konventionen, kein Bauwerk. Das Manifest ist optional.
  2. Der Marketplace ist eine zweite Datei, nicht ein Dienst. Ein lokaler Pfad genügt zum Testen.
  3. Namensräume sind Pflicht, nicht Kür — und der Präfix kommt aus einem Feld, das man leicht falsch setzt.
  4. Nicht alles funktioniert im Plugin, was im Projekt funktioniert. Die Liste ist länger als erwartet.
# Begleitprojekt
examples/demo-plugin-marketplace/
  .claude-plugin/marketplace.json
  cgs-demo/
    .claude-plugin/plugin.json
    skills/checking-links/
    commands/plugin-info.md
    agents/link-reviewer.md
    hooks/hooks.json
    .mcp.json
  verify.sh

Anatomie und Namen

Was ein Plugin bündelt und wie die Teile heißen

Was ein Plugin bündeln kann

Fast alles, was auch in einem .claude/-Verzeichnis liegen kann — jede Art in ihrem eigenen Ordner, alle optional.

  1. Wissen und Abläufe: skills/, commands/, agents/, workflows/
  2. Automatik: hooks/, monitors/
  3. Anschlüsse: .mcp.json, .lsp.json
  4. Form: output-styles/, themes/
  5. Beigaben: scripts/, bin/ — was in bin/ liegt, ist als nackter Befehl aufrufbar.
Nur plugin.json liegt in .claude-plugin/. Alle Komponentenordner liegen daneben, im Plugin-Wurzelverzeichnis. Das ist der Fehler, den man genau einmal macht — und dann eine halbe Stunde sucht, warum nichts lädt.
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins-reference

Das Manifest

Das Manifest ist optional. Ohne es findet Claude Code die Komponenten an den Standardorten und leitet den Namen aus dem Verzeichnis ab.

  1. Gibt es ein Manifest, ist name das einzige Pflichtfeld. Alles andere ist Metadaten oder Pfadangabe.
  2. version steuert Updates. Ohne sie dient der Git-Commit als Version, jeder Commit gilt als neu. Mit ihr gibt es Updates nur beim Anheben.
  3. Unbekannte Felder werden ignoriert — claude plugin validate --strict macht daraus einen Fehler.
  4. Falsche Typen scheitern hart: keywords als Zeichenkette statt Liste ist ein Ladefehler.
// cgs-demo/.claude-plugin/plugin.json
{
  "name": "cgs-demo",
  "displayName": "CGS Demo",
  "version": "0.1.0",
  "description": "Beispiel-Plugin ...",
  "license": "MIT",
  "keywords": ["training"]
}

# pruefbar, nicht interaktiv:
claude plugin validate . --strict
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins-reference

Ergänzen oder ersetzen

Ein Pfad im Manifest verhält sich je Feld anders. Bei einem Feld kommt der eigene Pfad dazu, bei den übrigen tritt er an die Stelle des Standardordners.

FeldVerhalten
skillsergänzt — skills/ wird immer gescannt, die eigenen Pfade kommen dazu
commands, agents, workflows, outputStylesersetzt — sobald gesetzt, wird der Standardordner nicht mehr gescannt
hooks, mcpServers, lspServerseigene Zusammenführungsregeln
Den Standardordner behält man, indem man ihn mitlistet: "commands": ["./commands/", "./extras/"]. Alle Pfade sind relativ zum Plugin-Wurzelverzeichnis und beginnen mit ./.
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins-reference

Namensräume

Plugin-Skills sind immer mit Namensraum versehen: /plugin-name:skill-name. Das verhindert Kollisionen, wenn zwei Plugins denselben Skill mitbringen.

  1. Der Präfix ist name aus plugin.json — nicht displayName, der ist reine Anzeige.
  2. Der Skill-Name kommt aus dem Ordner unter skills/.
  3. Heißt das Plugin im Katalog anders, gilt für enabledPlugins und /plugin der Katalog-Name.
  4. Plugin-Agenten erscheinen mit Doppelpunkt, etwa plugin-dev:agent-creator.
Beim Umbau von .claude/ in ein Plugin: Projekt-Agenten überschreiben gleichnamige Plugin-Agenten. Skills nicht — sie sind namespaced, also bleiben /name und /plugin:name beide da.
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins

Der Marketplace

Katalog, Quellen, Versionen

Der Katalog ist eine Datei

.claude-plugin/marketplace.json im Wurzelverzeichnis des Katalogs. Kein Dienst, kein Konto, keine Anmeldung — eine Datei mit drei Pflichtfeldern.

  1. Pflicht: name, owner mit name, und plugins als Liste.
  2. Je Eintrag Pflicht: name und source. Erlaubt ist zusätzlich jedes Feld des Manifests.
  3. Ein Name je Nutzer:in — ein zweiter Katalog gleichen Namens ersetzt den ersten.
  4. Manche Namen sind reserviert, darunter die offiziellen Quellen von Anthropic. Wer einen davon nimmt, kommt nicht weit.
{
  "name": "cgs-training-local",
  "owner": { "name": "CGS IT ..." },
  "plugins": [{
    "name": "cgs-demo",
    "source": "./cgs-demo",
    "category": "training"
  }]
}

# relativer Pfad loest gegen den
# Katalog-Root auf, NICHT gegen
# .claude-plugin/
checked am 2026-07-29 gegen code.claude.com/docs/en/plugin-marketplaces

Woher ein Plugin kommt

Fünf Quelltypen. Für den Kurs zählt der erste: ein lokales Verzeichnis genügt, und die Doku beschreibt das ausdrücklich als Testweg.

  1. Relativer Pfad — muss mit ./ beginnen, liegt im Katalog-Verzeichnis.
  2. github mit repo, optional ref und sha.
  3. url für eine beliebige Git-Adresse, git-subdir für ein Unterverzeichnis daraus.
  4. npm über die Paketverwaltung.
  5. Sind ref und sha gesetzt, gewinnt der sha.
# in einer Sitzung
/plugin marketplace add ./examples/
  demo-plugin-marketplace
/plugin install cgs-demo@cgs-training-local

# oder nicht-interaktiv
claude plugin marketplace add \
  ./examples/demo-plugin-marketplace
Katalog-Quelle und Plugin-Quelle sind zwei verschiedene Dinge: die eine sagt, woher der Katalog kommt, die andere, woher ein einzelnes Plugin darin kommt. Nur die zweite kennt sha.
checked am 2026-07-29 gegen code.claude.com/docs/en/plugin-marketplaces

Aktualisieren

Wer version setzt, pinnt das Plugin auf diesen String. Neue Commits allein bewirken dann nichts.

  1. Mit version: Updates gibt es erst beim Anheben. /plugin update meldet vorher „already at the latest version".
  2. Ohne version: der Git-Commit ist die Version — jeder Commit ist ein Update.
  3. Steht sie an beiden Stellen, gewinnt plugin.json über den Katalogeintrag.
  4. Ein Update wechselt das Verzeichnis. Das alte wird als verwaist markiert und nach 14 Tagen entfernt — Zustand gehört deshalb nicht dorthin.
# zeigt auf das INSTALLATIONS-
# verzeichnis, wechselt bei Updates
${CLAUDE_PLUGIN_ROOT}

# ueberlebt Updates -- hierher
# gehoert Zustand
${CLAUDE_PLUGIN_DATA}

# das Projekt-Wurzelverzeichnis
${CLAUDE_PROJECT_DIR}
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins-reference

Aktivieren und Grenzen

Wo der Schalter steht — und was im Plugin nicht gilt

Die Präzedenz-Falle

enabledPlugins trägt Einträge der Form "plugin@katalog": true. Wo der Eintrag steht, entscheidet, ob er wirkt.

  1. Ein false in den User-Settings verpufft, wenn das Projekt das Plugin aktiviert — Projekt schlägt User.
  2. Der wirksame Ort für den eigenen Opt-out ist .claude/settings.local.json.
  3. Von der Firma erzwungene Plugins lassen sich so gar nicht abschalten: Managed Settings überstimmen auch Local.
  4. Aktivieren ist nicht installieren. Ein Eintrag in der Projektdatei installiert bei niemandem etwas; jeder Ladepfad fragt vorher nach Installation und Vertrauen.
Verwandter Schlüssel, andere Regel: pluginConfigs wird nur aus User-Settings und Managed Settings gelesen. Projekt- und Local-Einträge werden ignoriert — damit ein geklontes Repository keine Werte in Hook- und MCP-Konfigurationen einschleusen kann.
checked am 2026-07-29 gegen code.claude.com/docs/en/settings

Was im Plugin nicht gilt

Ein Plugin verteilt Fähigkeiten — es kann sich aber nicht selbst Rechte, Anschlüsse oder einen Lebenszyklus mitgeben.

WoWas nicht funktioniert
Plugin-Subagenthooks, mcpServers, permissionMode — ausdrücklich „for security reasons"
Plugin-settings.jsonnur agent und subagentStatusLine; alles andere wird stillschweigend ignoriert
CLAUDE.md im Pluginwird nicht als Projektkontext geladen — Anweisungen gehören in einen Skill
Pfade nach draußen../shared-utils fehlt nach der Installation; Symlinks aus dem Katalog heraus werden übersprungen
Hook-Matcher auf eigenen MCP-Serverder bloße Server-Schlüssel feuert nie — es braucht den vollen Namen mit Plugin-Präfix
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins-reference

Vertrauen und Firmenpolitik

Ein Plugin bringt fremden Code mit, der Hooks registrieren und Werkzeuge freigeben kann. Entsprechend gibt es Schalter dafür — nur in Managed Settings.

  1. strictKnownMarketplaces begrenzt, welche Kataloge überhaupt hinzugefügt werden dürfen.
  2. blockedMarketplaces ist die Sperrliste. Geprüft vor dem Herunterladen — gesperrte Quellen berühren das Dateisystem nie.
  3. strictPluginOnlyCustomization dreht es um: Skills, Agenten, Hooks und MCP-Server dürfen dann nur aus Plugins kommen.
  4. disableSideloadFlags schließt die Umgehung über --plugin-dir und Verwandte.
Vor der Installation zeigt Claude Code eine Vertrauenswarnung; Organisationen können ihr über pluginTrustMessage eigenen Text anhängen. Ein Plugin zu installieren heißt, seinem Autor Werkzeugzugriff in eurem Repository zu geben.
checked am 2026-07-29 gegen code.claude.com/docs/en/permissions

Plugin oder Repo-Konfiguration

Die Entscheidung, die vor dem Bauen kommt

Wann sich ein Plugin lohnt

Ein Plugin lohnt sich ab dem zweiten Repository, nicht ab der zweiten Datei. Vorher ist .claude/ im Projekt einfacher und ehrlicher.

Plugin, wenn

  • dieselbe Konfiguration in mehreren Repositories gebraucht wird
  • sie versioniert und mit Änderungshistorie verteilt werden soll
  • Menschen außerhalb des Teams sie nutzen
  • die Organisation Anpassungen nur aus Plugins zulassen will

Repo-Konfiguration, wenn

  • es um dieses Projekt geht und um sonst nichts
  • Rechte, Hooks oder MCP-Anschlüsse dazugehören — im Plugin fällt das weg
  • die Regel sich noch bewegt: eine Datei ändern schlägt ein Release
  • das Team ohnehin nur ein Repository hat
Der Weg zum Plugin ist der normale Code-Weg: Auslöser, Branch, kleine Änderung, Review durch einen Menschen, Merge. Eine geteilte Regel ist eine Team-Entscheidung, kein Vorschlag.
checked am 2026-07-29 gegen code.claude.com/docs/en/plugins

Praxisbeispiel: cgs-demo

Das Begleitplugin bündelt je eine Komponente jeder Art. Seine Nutzlast ist ein Link-Prüfer — klein, ohne Abhängigkeiten, in jedem Schulungs-Repository nützlich.

  1. Skill mit Begleitskript, freigegeben über allowed-tools mit ${CLAUDE_PLUGIN_ROOT}.
  2. Command als flache Datei — derselbe Baustein, nur ohne eigenes Verzeichnis.
  3. Subagent ohne Schreibwerkzeuge und ohne die drei verbotenen Felder.
  4. Hook auf PostToolUse, schreibt nach ${CLAUDE_PLUGIN_DATA}.
  5. MCP-Eintrag, der auf ein vorhandenes Projekt zeigt und erst nach dessen Bau verbindet.
$ check-links.py ../agent-scaffolding
FEHL  .claude/skills/helper/SKILL.md:10
      Link 'docs\overview.md' zeigt
      ins Leere
17 Dateien geprueft, 1 kaputter Link

# Das ist der Windows-Pfad, der in
# Erweiterung 1 absichtlich gepflanzt
# wurde. Das Plugin findet den
# Anti-Pattern-Fehler von dort.

Erweiterung 5 in fünf Sätzen

Was von diesem Deck hängenbleiben soll.

  1. Ein Plugin ist ein Verzeichnis mit Konventionen. Das Manifest ist optional; existiert es, ist name das einzige Pflichtfeld.
  2. In .claude-plugin/ liegt nur plugin.json. Alle Komponentenordner liegen daneben.
  3. version pinnt. Ohne sie ist jeder Commit ein Update, mit ihr gibt es keins, bis sie steigt.
  4. Ein Plugin verteilt Fähigkeiten, keine Rechte. Bei Plugin-Subagenten fallen hooks, mcpServers und permissionMode weg.
  5. Es lohnt ab dem zweiten Repository — und der Weg dorthin ist ein Pull Request mit menschlichem Review.

Glossar Glossar

Plugin Ein Verzeichnis, das Konfiguration zum Verteilen bündelt — Skills, Commands, Subagenten, Hooks, Anschlüsse. Installierbar über einen Marketplace und versionierbar.
Marketplace (Plugin-Katalog) Eine Datei marketplace.json, die auflistet, welche Plugins es gibt und woher sie kommen. Kein Dienst: ein lokales Verzeichnis oder ein Git-Repository genügt.
Manifest Die Datei plugin.json in .claude-plugin/. Trägt Metadaten und optional eigene Pfade zu den Komponenten. Insgesamt optional; ohne sie gelten die Standardorte.
Namensraum (Namespacing) Der Präfix, unter dem Komponenten eines Plugins erscheinen, etwa /cgs-demo:checking-links. Er kommt aus dem Feld name und verhindert Kollisionen zwischen Plugins.
MCP (Model Context Protocol) Offenes Protokoll, über das Claude Code fremde Systeme als Werkzeuge anbindet. Ein Plugin kann Server-Einträge mitbringen; Einzelheiten in der Vertiefung zu Modul 8.

© 2026 CGS IT Solutions GmbH

Alle Rechte vorbehalten

Diese Schulungsunterlagen sind urheberrechtlich geschützt. Vervielfältigung, Weitergabe oder kommerzielle Nutzung — auch in Auszügen — nur mit ausdrücklicher schriftlicher Genehmigung der CGS IT Solutions GmbH.

cgsit-claude-training · Erweiterung 5 · Plugins · v0.10.0