Claude-Code-Plugins: das erste Plugin bauen, testen und veröffentlichen

Plugins für Claude Code wirken wie eine kleine Paketierungsfunktion, lösen aber ein größeres Problem. Vorher lag ein Claude-Code-Setup lose im Ordner .claude/. Es zu teilen war umständlich, es zu versionieren chaotisch und es zu prüfen schwierig. Ein Plugin bündelt all das in einer einheitlichen Einheit.

Ein Detail erklärt das ganze Design. Alles, was ein Plugin enthalten kann, also Skills, Agents, Hooks und MCP-Server, gab es schon vorher für sich. Plugins bringen keine neuen Fähigkeiten mit. Sie vereinheitlichen, wie diese Teile verpackt und an andere weitergegeben werden.

Eigenständige Konfiguration oder Plugin?

Die beiden Varianten unterscheiden sich in der Benennung und darin, für wen sie gedacht sind:

• Eigenständige Konfiguration im Ordner .claude/. Befehle werden als /hello aufgerufen. Das passt zu persönlichen Workflows, projektspezifischen Anpassungen und schnellen Experimenten.
• Plugin, ein in sich geschlossenes Verzeichnis mit Manifest. Befehle tragen ein Präfix, etwa /plugin-name:hello. Das passt zum Teilen im Team, zur Verbreitung in der Community, zu versionierten Releases und zur Wiederverwendung in mehreren Projekten.

Ein sinnvoller Weg ist, mit einer eigenständigen Konfiguration schnell zu iterieren und sie in ein Plugin umzuwandeln, sobald sie reif zum Teilen ist.

Ein erstes Plugin in drei Schritten

1. Ordner und Manifest anlegen.

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

Die Manifest-Datei plugin.json kommt in diesen versteckten Ordner und gibt dem Plugin seine Identität:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Der Wert von name ist die eindeutige Kennung und wird zugleich zum Namensraum für jeden Skill im Plugin. Das Feld version ist optional. Ist es gesetzt, bekommen Nutzer Updates erst, wenn die Nummer erhöht wird.

2. Einen Skill hinzufügen. Skills liegen im Verzeichnis skills/, jeder in einem eigenen Ordner mit einer Datei SKILL.md:

mkdir -p my-first-plugin/skills/hello---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

3. Lokal ausprobieren.

claude --plugin-dir ./my-first-plugin

Sobald Claude läuft, startet die Eingabe /my-first-plugin:hello den Skill.

Die Namensräume verdienen eine Erwähnung. Jeder Plugin-Skill folgt dem Muster /plugin-name:skill-name, sodass zwei Plugins Skills mit demselben Namen ausliefern können, ohne dass sie sich je in die Quere kommen.

Damit ein Skill Eingaben annimmt, setzen Sie den Platzhalter $ARGUMENTS in seine SKILL.md:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Nach dem Bearbeiten übernimmt /reload-plugins die Änderungen. Eine Eigenheit: Die Zahl der Skills, die nach dem Neuladen angezeigt wird, berücksichtigt nur das Verzeichnis commands/. Sie kann also null anzeigen, obwohl der neue Skill geladen ist und funktioniert.

Es gibt auch eine Abkürzung. claude plugin init my-tool legt ein Plugin unter ~/.claude/skills/ an, und es wird in jeder künftigen Sitzung als my-tool@skills-dir geladen, ganz ohne --plugin-dir.

Was ein Plugin enthalten kann

Jeder Ort im Plugin-Stammverzeichnis hat eine feste Aufgabe:

• .claude-plugin/ enthält nur das Manifest plugin.json
• skills/ enthält Skills im Aufbau <skill-name>/SKILL.md
• commands/ ist das ältere Skill-Format mit flachen Markdown-Dateien, neue Plugins sollten stattdessen skills/ nutzen
• agents/ enthält eigene Agent-Definitionen
• hooks/ enthält Event-Handler, beschrieben in hooks.json
• .mcp.json konfiguriert MCP-Server
• .lsp.json konfiguriert Language Server für Code-Intelligenz
• monitors/ konfiguriert Hintergrund-Monitore
• bin/ enthält ausführbare Dateien, die im PATH landen, solange das Plugin aktiv ist
• settings.json liefert Standardeinstellungen, die beim Aktivieren des Plugins greifen

Der klassische Anfängerfehler ist, commands/, agents/, skills/ oder andere Inhaltsordner in .claude-plugin/ abzulegen. Dorthin gehört nur das Manifest. Alles andere liegt direkt im Stammverzeichnis des Plugins.

Bei einem Plugin mit nur einem Skill kann SKILL.md im Stammverzeichnis liegen, und der name aus dessen Frontmatter wird zum Aufrufnamen. Plugins mit mehreren Skills sollten den Aufbau mit skills/ verwenden.

Extras für anspruchsvollere Plugins

Language Server. Um eine Sprache zu unterstützen, die Claude Code nicht von Haus aus abdeckt, fügen Sie eine Datei .lsp.json hinzu:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Wer das Plugin installiert, braucht das passende Language-Server-Binary auf seinem Rechner. Fehlt es, erscheint im Tab Errors des /plugin-Managers ein Startfehler.

Hintergrund-Monitore. Definieren Sie sie in monitors/monitors.json, dann starten sie, sobald das Plugin aktiviert wird. Jede Zeile, die der Befehl auf stdout ausgibt, erreicht Claude als Benachrichtigung:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Standardeinstellungen. settings.json versteht derzeit nur zwei Schlüssel, agent und subagentStatusLine, und unbekannte Schlüssel werden ohne Warnung ignoriert. Mit dem Schlüssel agent lässt sich einer der Agents des Plugins zum Hauptthread machen, was das Standardverhalten von Claude Code ändert:

{
  "agent": "security-reviewer"
}

Testen

Das wichtigste Entwicklungswerkzeug ist das Flag --plugin-dir. Es akzeptiert ein Verzeichnis und auch ein gezipptes Paket:

claude --plugin-dir ./my-plugin.zip

Hat ein lokales Plugin denselben Namen wie ein installiertes Marketplace-Plugin, gewinnt in dieser Sitzung die lokale Kopie. Das ist praktisch, um Änderungen auszuprobieren, ohne etwas zu deinstallieren. Zwangsweise aktivierte oder deaktivierte Plugins lassen sich so nicht überschreiben.

Für Tests aus der Ferne gibt es --plugin-url:

claude --plugin-url https://example.com/my-plugin.zip

Schlägt der Download fehl oder ist das Archiv beschädigt, startet Claude Code trotzdem und vermerkt das Problem im Tab Errors von /plugin. Wie bei jedem Plugin gilt: Laden Sie nur Quellen, denen Sie vertrauen.

Während der Entwicklung übernimmt /reload-plugins Änderungen ohne Neustart. Wenn etwas nicht funktioniert, prüfen Sie die Verzeichnisstruktur, testen Sie jede Komponente einzeln und greifen Sie auf die CLI-Debugging-Hilfen zurück, die in den Referenzseiten von Anthropic dokumentiert sind.

In einen Marketplace kommen

Anthropic betreibt zwei öffentliche Marketplaces:

• claude-plugins-official wird von Anthropic kuratiert und beim ersten interaktiven Start automatisch registriert. Ein dort aufgenommenes Plugin wird Nutzern direkt im Produkt angeboten.
• claude-community wird von der Community betrieben, Einreichungen von Dritten kommen nach einer Prüfung hinzu. Hinzufügen lässt er sich mit /plugin marketplace add anthropics/claude-plugins-community.

Vor dem Einreichen validieren:

claude plugin validate ./your-plugin

Bei Erfolg erscheint die Meldung „Validation passed“, und etwaige Warnungen werden aufgelistet. Mit --strict werden Warnungen zu Fehlern.

Eingereicht wird über eines von zwei Formularen. Ein Weg ist das Formular auf claude.ai, das nur Organisationen mit Team- oder Enterprise-Tarif offensteht. Einzelne Autoren nutzen stattdessen das Formular in der Console. Nach der Freigabe wird das Plugin im Community-Repository auf einen bestimmten Commit-SHA festgelegt, und die CI zieht diese Festlegung bei jedem neuen Commit nach. Öffentliche Verzeichnisse synchronisieren nachts, eine Lücke zwischen Freigabe und Erscheinen in marketplace.json ist also normal.

Der offizielle Marketplace funktioniert anders. Anthropic entscheidet, was hineinkommt, und es gibt keine öffentliche Bewerbung.

Ein bestehendes Setup umziehen

Eigenständige Konfigurationen lassen sich mit wenig Aufwand umwandeln. Legen Sie Plugin-Ordner und Manifest an und kopieren Sie dann die Inhalte hinüber:

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

Hooks brauchen eine eigene Behandlung. Nehmen Sie das Objekt hooks aus der vorhandenen settings.json und legen Sie es in hooks/hooks.json ab.

Löschen Sie danach die Originale aus .claude/. Agents in .claude/agents/ auf Projekt- oder Nutzerebene überschreiben gleichnamige Plugin-Agents, Überbleibsel würden also verhindern, dass die neue Version greift. Bei Skills gibt es diesen Konflikt nicht, weil Plugin-Skills einen Namensraum haben und beide Versionen nebeneinander bestehen können.

Was Plugins verändern

Mit Plugins kam keine neue Fähigkeit. Skills, Agents, Hooks und MCP-Server funktionierten auch als lose Konfiguration einwandfrei. Plugins bringen Struktur: Versionierung, einheitliche Benennung, Beschreibungen und echte Vertriebskanäle.

Damit rückt Claude Code vom Werkzeug zur Plattform. Ein Werkzeug erledigt eine Aufgabe gut, eine Plattform lässt andere darauf aufbauen. Was im Marketplace wachsen wird, ist schwer vorherzusagen, aber das Kopieren ganzer .claude/-Ordner zwischen Rechnern ist klar ein Auslaufmodell. Auch andere KI-Coding-Produkte, darunter Cursor, haben Plugin-Marketplaces gestartet, und so werden im ganzen Ökosystem verstreute Komponenten zu verpackten, teilbaren Einheiten.