CGS IT Solutions GmbH — Claude Code Training · Modul 10c · Plugin-Entwicklung · v2.0.1

Modul 10c

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

Plugins: Aufbau, Katalog, Grenzen

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. Das Manifest ist optional.
  2. Der Marketplace ist eine Datei marketplace.json. Ein lokaler Pfad genügt zum Testen.
  3. Jede Komponente trägt den Plugin-Namen als Präfix — aus name, nicht aus displayName.
  4. Nicht alles, was im Projekt funktioniert, funktioniert im Plugin. Die Liste ist länger als erwartet.
# eigenes oeffentliches Repository
cgsit-claude-plugins/
  .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
checked am 2026-09-26 gegen github.com/chris-cgsit/cgsit-claude-plugins

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, solange das Plugin aktiv ist.
das Plugin-Wurzelverzeichnis
skills/
commands/
agents/
workflows/
hooks/
monitors/
.mcp.json
.lsp.json
output-styles/
themes/
scripts/
bin/
.claude-plugin/ plugin.json
nur diese eine Datei liegt dort
Komponentenordner, alle optionaldas Manifest
checked am 2026-09-26 gegen docs/en/plugins/manifest-reference

Das Manifest

Das Manifest ist optional.
Ohne es findet Claude Code die Komponenten an den Standardorten, der Name kommt aus Katalog oder Verzeichnis.

  1. Gibt es ein Manifest, ist name das einzige Pflichtfeld. Alles andere ist Metadaten oder Pfadangabe.
  2. version steuert Updates. Ohne sie dient bei Git-Quellen der Commit-SHA als Version. Mit ihr gibt es Updates nur beim Anheben.
  3. Unbekannte Felder streicht Claude Code still — claude plugin validate warnt, --strict macht daraus einen Fehler.
  4. Falsche Typen scheitern hart: keywords als Zeichenkette statt Liste lädt nicht.
// cgs-demo/.claude-plugin/plugin.json
{
  "name": "cgs-demo",
  "displayName": "CGS Demo",
  "version": "0.1.0",
  "description": "Beispiel-Plugin ...",
  "author": { "name": "CGS IT ..." },
  "keywords": ["training", ...]
}

# pruefbar, nicht interaktiv:
claude plugin validate . --strict
checked am 2026-09-26 gegen docs/en/plugins/manifest-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 meisten tritt er an die Stelle des Standardordners.

Feld Verhalten
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, lspServerszusammengeführt — die Standarddatei lädt zuerst, das Manifest kommt dazu
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-09-26 gegen docs/en/plugins/manifest-reference

Namensräume

Plugin-Skills heißen immer /plugin-name:skill-name.
So kommen sich zwei Plugins mit gleichnamigen Skills nicht in die Quere.

  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 die Installation der Katalog-Name.
  4. Plugin-Agenten heißen ebenso, etwa cgs-demo:link-reviewer. Unterordner unter agents/ werden Teil des Namens.
Beim Umbau von .claude/ in ein Plugin: Bei gleichem Namen hat der Projekt-Agent Vorrang vor dem Plugin-Agenten.
Skills stehen beide da, als /name und /plugin:name.
checked am 2026-09-26 gegen docs/en/plugins/components

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 — zwei Kataloge gleichen Namens lassen sich nicht gleichzeitig anmelden.
  4. Reservierte Namen: die offiziellen Kataloge von Anthropic, dazu inline, skills-dir, synced, github, npm und ähnliche.
{
  "name": "cgs-training",
  "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-09-26 gegen docs/en/plugins/marketplace-reference

Woher ein Plugin kommt

Sieben Quelltypen für ein Plugin.
Für den Kurs zählt der erste: ein relativer Pfad in einem lokalen Katalog.

  1. Relativer Pfad — beginnt mit ./, liegt im Katalog-Verzeichnis. Aus einem lokalen Katalog lädt Claude Code es an Ort und Stelle.
  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, archive (ZIP über HTTPS) und command (ein Befehl nennt das Verzeichnis).
  5. Sind ref und sha gesetzt, gewinnt der sha.
Katalog-Quelle
./verzeichnis
oder owner/repo
der Katalog
(eine Datei)
Plugin-Quelle
./pfad
github
url
git-subdir
npm
archive
command
ein Plugin
daraus
Quelltypwas daraus wird
Katalog-Quelle und Plugin-Quelle sind zwei verschiedene Dinge: url meint beim Katalog eine marketplace.json, beim Plugin ein Git-Repository.
Nur die Plugin-Quelle kennt sha.
checked am 2026-09-26 gegen docs/en/plugins/marketplace-reference

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. claude plugin update meldet vorher „already at the latest version".
  2. Ohne version: bei Git-Quellen ist der Commit-SHA die Version — jeder Commit ist ein Update.
  3. Steht sie an beiden Stellen, gewinnt plugin.json über den Katalogeintrag.
  4. Auto-Update ist für fremde Kataloge aus, für die offiziellen von Anthropic an. autoUpdate in extraKnownMarketplaces schaltet es ein.
  5. Ein Update wechselt das Verzeichnis. Das alte wird 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-09-26 gegen docs/en/plugins/loading

Aktivieren und Grenzen

Wo der Schalter steht — und was im Plugin nicht gilt

Wo ein Plugin ein- und ausgeschaltet wird

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

  1. Es gilt die Settings-Reihenfolge (Modul 10b): Ein false in den User-Settings verpufft, wenn das Projekt das Plugin aktiviert.
  2. Der eigene Opt-out gehört in .claude/settings.local.json.
  3. Managed Settings: true erzwingt, false sperrt — keine andere Datei ändert das.
  4. Aktivieren ist nicht installieren. Ein true nur im Projekt holt kein Plugin aus einer externen Quelle auf den Rechner — nur Plugins mit relativem Pfad im Katalog laden direkt.
Managed
"plugin@katalog": true
erzwungen — auch Local hilft nicht
settings.local.json
"plugin@katalog": false
wirkt — der eigene Opt-out
Projekt
"plugin@katalog": true
schlägt User
User
"plugin@katalog": false
verpufft gegen das Projekt
oben gewinnt — und Aktivieren ist nicht Installieren
checked am 2026-09-26 gegen docs/en/plugins/loading

Was ein Plugin nicht mitbringen kann

Ein Plugin verteilt Fähigkeiten.
Rechte, Projektkontext und Anschlüsse je Subagent gibt es sich nicht selbst.

Wo Was nicht funktioniert
Plugin-SubagentpermissionMode, hooks, mcpServers, initialPrompt — ignoriert
Plugin-settings.jsonnur agent und subagentStatusLine; alles andere fällt beim Laden weg
CLAUDE.md im Pluginwird nicht als Projektkontext geladen — Anweisungen gehören in einen Skill
Pfade nach draußen../shared-utils lädt nicht; Symlinks aus dem Plugin heraus ebenso wenig
Hook-Matcher auf eigenen MCP-Serverder bloße Server-Name feuert nie — es braucht mcp__plugin_<plugin>_<server>__<tool>
checked am 2026-09-26 gegen docs/en/plugins/components

Einen Team-Katalog verteilen

Ein Eintrag im Projekt meldet den Team-Katalog für alle an, die das Repository öffnen.
Die Firma kann zusätzlich begrenzen, woher Plugins kommen dürfen.

  1. extraKnownMarketplaces im Projekt meldet den Katalog an — erst nach der Workspace-Trust-Abfrage.
  2. enabledPlugins daneben schaltet Plugins daraus ein; installieren muss jede:r selbst.
  3. strictKnownMarketplaces (nur Managed) ist die Allowlist der Kataloge. Ein leeres Array sperrt alles, auch den offiziellen.
  4. disableSideloadFlags (nur Managed) schließt die Umgehung über Startflags wie --plugin-dir und --mcp-config.
// .claude/settings.json im Team-Repo
{
  "extraKnownMarketplaces": {
    "cgs-training": {
      "source": {
        "source": "github",
        "repo": "chris-cgsit/cgsit-claude-plugins"
      },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "cgs-demo@cgs-training": true
  }
}
checked am 2026-09-26 gegen docs/en/settings-reference

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.

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
  • Permission-Regeln dazugehören — ein Plugin kann keine mitbringen
  • die Regel sich noch bewegt: eine Datei ändern schlägt ein Release
  • das Team ohnehin nur ein Repository hat
Die Zwischenstufe ohne Katalog: Ein Plugin-Verzeichnis unter .claude/skills/ lädt als name@skills-dir, sobald man dem Ordner vertraut.
checked am 2026-09-26 gegen docs/en/plugins/loading

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 im Plugin ignorierten 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 examples/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
# Modul 8c absichtlich gepflanzt
# wurde. Das Plugin findet den
# Anti-Pattern-Fehler von dort.

Modul 10c 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. Plugin-Subagenten ignorieren permissionMode, hooks und mcpServers.
  5. Es lohnt ab dem zweiten Repository — vorher reicht .claude/ im Projekt.

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 Modul 8b.
Workspace-Trust-Abfrage Der Dialog, mit dem man einem Ordner vertraut. Erst danach meldet Claude Code Kataloge und Plugins aus dessen .claude/-Verzeichnis an.

© 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 · Modul 10c · Plugins · v2.0.1