SpyBara
Go Premium

plugins/components.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 233 additions and 700 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Wed 7 23:59 Thu 8 22:58 Sat 10 23:01 Wed 14 22:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58

Komponenten zu einem Plugin hinzufügen

Fügen Sie Skills, Hooks, MCP-Server und alle anderen Komponententypen zu einem Claude Code-Plugin hinzu, mit einem Beispiel, das für jeden validiert.

Ein Claude Code-Plugin wird aus Komponenten erstellt, wie Skills, Agents, Hooks und MCP-Servern. Jede Komponente hat einen Standard-Ordner im Plugin, einen optionalen Manifest-Schlüssel in .claude-plugin/plugin.json, der diesen Ordner ersetzt oder ergänzt, und einen Namen, den der Benutzer sieht. Für jede Schlüssels vollständige Feldtabelle siehe die Manifest-Referenz.

Verwenden Sie diese Seite, um eine Komponente zu einem Plugin hinzuzufügen, das bereits geladen wird.

Nachdem Sie eine Komponente hinzugefügt haben, führen Sie /reload-plugins in einer laufenden Sitzung aus oder starten Sie eine neue, damit Claude Code sie lädt. Um die Datei der Komponente vor dem Laden zu überprüfen, führen Sie claude plugin validate . in Ihrer Shell aus dem Plugin-Verzeichnis aus.

[!NOTE]

Diese Fälle werden auf anderen Seiten behandelt:

Plugin-Verzeichnis erkunden

Der Explorer zeigt ein Beispiel-Plugin, my-plugin, das an seinem Standard-Speicherort eine von jeder Art von Komponente hat:

  • Ein Review-Skill und einen about-Befehl
  • Einen Security-Review-Subagenten
  • Einen Hook, der Dateien nach Claude-Bearbeitungen formatiert, und den scripts/-Ordner, den er aufruft
  • Einen Log-Monitor
  • Einen Output-Stil und ein Farbschema
  • Einen Route-Audit-Workflow
  • Eine hello-plugin-Ausführungsdatei
  • Standard-Einstellungen
  • Einen lokalen MCP-Server und einen Go-Sprachserver

Jede Datei ist das kleinste gültige Beispiel ihres Formats, um die Form zu zeigen, nicht um nützlich zu sein: Ein echter Skill oder Agent trägt vollständige Anweisungen und oft unterstützende Dateien, und ein echter Hook oder Monitor führt echte Arbeit aus. Die Abschnitte nach dem Explorer verwenden die gleichen Dateien als ihre Beispiele und verlinken auf vollständigere. Wählen Sie eine Datei oder einen Ordner aus, um zu lesen, wofür sie gedacht ist, zu sehen, was darin geht, und den Abschnitt zu finden, der sie behandelt.

What goes in a plugin

This example plugin, my-plugin, has one of every kind of component, each in its default location. Select a file or folder to read what it’s for and see what goes in it.

Plugin directory

my-plugin/

Selected piece

Das Manifest ist die plugin.json-Datei im .claude-plugin/-Verzeichnis eines Plugins. Sie enthält die Metadaten des Plugins und die userConfig-Werte, die Claude Code den Benutzer fragt. Claude Code lädt ein Plugin auch ohne eines. In der Datei ist nur name erforderlich. In diesem Fall ist description der Text, den Benutzer für das Plugin in /plugin sehen, und version hält Benutzer auf dieser Version, bis Sie sie ändern:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review, formatting, and database tools for this team"
}

Ein Skill ist eine SKILL.md-Datei. Speichern Sie jeden Skill in seinem eigenen Verzeichnis unter skills/. Claude liest die description jedes Skills, und wenn das, was der Benutzer fragt, damit übereinstimmt, wie zum Beispiel Claude zu bitten, einen Pull Request zu überprüfen, lädt Claude die Anweisungen des Skills und folgt ihnen. Der Benutzer kann ihn auch direkt als /my-plugin:review ausführen:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

Ein Befehl ist eine einzelne Markdown-Datei, die der Benutzer nach Name ausführt. Befehle sind das ältere Format: Ein Skill wird auf die gleiche Weise nach Name ausgeführt und kann auch unterstützende Dateien in seinem eigenen Verzeichnis tragen, daher schreiben Sie neue als Skills und behalten Sie commands/ für Dateien, die Sie bereits haben. Diese Datei wird zu /my-plugin:about und nimmt die gleiche Frontmatter wie ein Skill:

---
description: Summarize the repository
---

Summarize what this repository does in three sentences.

Ein Subagent ist ein separater Assistent mit seinen eigenen Anweisungen und seinem eigenen Kontextfenster, dem Claude eine Aufgabe delegieren und ein Ergebnis zurückbekommen kann. Jede Markdown-Datei unter agents/ definiert einen: Die Frontmatter benennt ihn und sagt, wann er zu verwenden ist, und der Text ist sein System-Prompt. Dieser wird my-plugin:security-reviewer genannt, und der Benutzer kann ihn mit @agent-my-plugin:security-reviewer aufrufen:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

Ein Hook führt etwas automatisch an einem Punkt im Lebenszyklus von Claude Code aus, wie zum Beispiel nach jeder Dateibearbeitung: ein Shell-Befehl, eine HTTP-Anfrage, ein MCP-Tool-Aufruf, ein Prompt an ein Modell oder ein Subagent. Speichern Sie die Hooks des Plugins in hooks/hooks.json im Plugin-Root. Dieser führt das scripts/format.sh des Plugins nach jedem Write oder Edit aus:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

Ein Monitor ist ein Shell-Befehl, den Claude Code beim Start der Sitzung im Hintergrund startet und bis zu deren Ende weiterlaufen lässt. Was er ausgibt, erreicht Claude als Benachrichtigungen. Ein when-Feld kann ihn stattdessen starten, wenn ein benannter Skill zum ersten Mal ausgeführt wird. Dieser verfolgt ein Fehler-Log:

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

Ein Plugin kann Output-Stile enthalten, die ändern, wie Claude seine Antworten formatiert und formuliert. Speichern Sie jeden Output-Stil als output-styles/<name>.md. Dieser erscheint in /output-style als my-plugin:terse:

---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---

Keep every reply short. Skip preambles and summaries.

Ein Plugin kann Farbschemas für die Claude Code-Schnittstelle enthalten. Speichern Sie jedes Schema als themes/<slug>.json. Dieses erscheint in /theme als Dracula, markiert als von my-plugin:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

Der workflows/-Ordner enthält Workflow .js-Dateien: einen meta-Block, dann einen Script-Text, der mehrere Subagenten orchestriert. Dieser läuft als /my-plugin:audit-routes:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

bin/ ist, wie ein Plugin ein Befehlszeilentool versendet. Während das Plugin aktiviert ist, setzt Claude Code diesen Ordner auf den PATH der Shell, in der es Befehle ausführt, damit Claude oder die Anweisungen eines Skills das Tool nach Name ausführen können, ohne dass der Benutzer etwas installieren muss. Mit dieser ausführbaren Datei an Ort und Stelle ist hello-plugin ein Befehl, den Claude ausführen kann:

#!/bin/bash
echo "hello from my-plugin"

Der Hook in hooks/hooks.json führt ein Script aus, und dieser Ordner ist, wo das Beispiel es behält. Der Name scripts/ ist eine Konvention, nicht etwas, das Claude Code sucht: Der Hook zeigt auf die Datei nach ihrem Pfad, ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh. Ein Formatter-Script könnte so aussehen:

#!/bin/bash
npx prettier --write .

Eine settings.json im Plugin-Root hält Einstellungen, die gelten, während das Plugin aktiviert ist, damit ein Plugin ändern kann, wie sich die Sitzung verhält, und nicht nur Komponenten hinzufügt. Nur zwei Schlüssel wirken sich von einem Plugin aus, agent und subagentStatusLine; jeder andere Schlüssel wird gelöscht. Siehe Standard-Einstellungen.

Dieser setzt agent, der die Haupt-Thread-Sitzung als den eigenen security-reviewer-Agent des Plugins ausführt, damit der System-Prompt, die Tool-Einschränkungen und das Modell dieses Agenten auf die ganze Sitzung angewendet werden:

{
  "agent": "security-reviewer"
}

Ein MCP-Server gibt Claude Tools von einem externen System. Deklarieren Sie ihn in .mcp.json im Plugin-Root. Dieser startet einen lokalen Server aus einem Script im Plugin und erscheint in /mcp als plugin:my-plugin:db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

Ein LSP-Server gibt Claude Diagnostik und Code-Navigation für eine Sprache. Deklarieren Sie den Server in .lsp.json im Plugin-Root. Dieser verbindet den Go-Sprachserver für .go-Dateien:

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

Jede Art von Komponente hinzufügen

Jeder der folgenden Abschnitte behandelt eine Art von Komponente: wo ihre Dateien im Plugin liegen, ein Beispiel, das die Validierung besteht, was der Benutzer sieht, sobald das Plugin geladen ist, und den Manifest-Schlüssel, der den Standardspeicherort ändert. Fügen Sie diejenigen hinzu, die Ihr Plugin benötigt; keine ist erforderlich.

Skills

Ein Skill ist eine SKILL.md-Datei, die Claude laden kann, wenn ihre Beschreibung zur Aufgabe passt. Der Benutzer kann ihn auch als Befehl ausführen. Speichern Sie jeden Skill in einem eigenen Verzeichnis unter skills/:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

Geben Sie der SKILL.md eine description, damit Claude weiß, wann er verwendet werden soll:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

Nachdem Sie das Plugin geladen haben, führt /my-plugin:review den Skill aus. Der Befehlsname und wer ihn aufrufen kann, folgen diesen Regeln:

  • Befehlsname: /<plugin>:<directory>, also ist skills/review/SKILL.md in my-plugin gleich /my-plugin:review. Wenn Sie name im Frontmatter festlegen, ersetzt es das letzte Segment, und das Plugin-Präfix bleibt erhalten. Siehe wie ein Skill seinen Befehlsnamen erhält
  • Wer ihn aufruft: Claude, der Benutzer oder beide, gesteuert über das Frontmatter. Siehe Steuern, wer einen Skill aufruft

Sie können Skills auch außerhalb des Standardverzeichnisses skills/ ablegen:

  • Zusätzliche Verzeichnisse: Führen Sie sie im Manifest-Schlüssel skills auf. Sie ergänzen den Standard-Scan von skills/, anstatt ihn zu ersetzen, anders als bei commands und agents
  • Ein einzelner Skill im Plugin-Stammverzeichnis: Ohne skills/-Verzeichnis und ohne Manifest-Schlüssel skills wird eine SKILL.md im Plugin-Stammverzeichnis als ein Skill geladen. Legen Sie name in ihrem Frontmatter fest, da eine Marketplace-Installation den Skill sonst nach seinem Cache-Verzeichnis benennt statt nach Ihrem Plugin

Um Anweisungen in ein Plugin aufzunehmen, schreiben Sie sie als Skill. Claude Code lädt keine CLAUDE.md im Plugin-Stammverzeichnis, und claude plugin validate warnt mit CLAUDE.md at the plugin root is not loaded as project context.

Wenn eine Regel jedes Mal gelten muss, etwa das Blockieren von Bearbeitungen geschützter Dateien, fügen Sie sie dem Plugin als Hook statt als Skill hinzu. Um zwischen beiden zu wählen, siehe den Tab „Hook vs Skill“ unter Ähnliche Funktionen vergleichen.

Informationen zu Frontmatter-Feldern und unterstützenden Dateien finden Sie unter Skills.

Befehle

Ein Befehl ist eine einzelne Markdown-Datei, die der Benutzer über ihren Namen ausführt, etwa /my-plugin:about.

[!NOTE]

Befehle sind das ältere Format, und Skills lösen sie für neue Arbeiten ab. Ein Skill wird auf dieselbe Weise über seinen Namen ausgeführt und kann zusätzlich unterstützende Dateien in seinem Verzeichnis mitführen. Behalten Sie commands/ für Dateien bei, die Sie aus .claude/commands/ übernehmen.

Speichern Sie einen Befehl unter commands/<file>.md, und er wird zu /<plugin>:<file>. Ein Unterverzeichnis fügt ein Segment hinzu, sodass commands/db/migrate.md zu /my-plugin:db:migrate wird.

Befehlsdateien verwenden dasselbe Frontmatter wie Skills.

Befehle im Manifest definieren

Dies benötigen Sie nur, wenn Sie Befehlsdateien an einem anderen Ort als commands/ ablegen oder einen kurzen Befehl direkt in plugin.json ohne separate Markdown-Datei definieren möchten. Legen Sie den Manifest-Schlüssel commands fest, und Claude Code liest ihn, anstatt commands/ zu scannen. Der Schlüssel akzeptiert einen Pfad, ein Array von Pfaden oder ein Objekt, das jedem Befehlsnamen entweder eine source-Datei oder Inline-content zuordnet.

Dieses Manifest definiert /my-plugin:about inline, ohne Markdown-Datei:

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

Laden Sie das Plugin und führen Sie /my-plugin:about in der Sitzung aus, um zu bestätigen, dass er geladen wurde.

Die vollständige Syntax des Schlüssels finden Sie unter commands.

Agenten

Ein Subagent ist ein separater Assistent mit eigenen Anweisungen und eigenem Kontextfenster, an den Claude eine Aufgabe delegieren kann. Jede Markdown-Datei unter agents/ definiert einen:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

Dieser Agent heißt my-plugin:security-reviewer, und der Benutzer kann ihn explizit aufrufen mit @agent-my-plugin:security-reviewer. Die Namensform ist <plugin>:<name>, wobei <name> aus dem Frontmatter-Feld name stammt oder aus dem Dateinamen, wenn dieses Feld fehlt.

Der Manifest-Schlüssel agents ersetzt den Scan von agents/.

Agenten in Unterordnern organisieren

Sie können Agentendateien eines Plugins in Unterordnern von agents/ ablegen. Claude Code lädt sie rekursiv und verbindet den Plugin-Namen, jeden Unterordnernamen und den Dateinamen mit Doppelpunkten zum bereichsbezogenen Namen des Agenten. Beispielsweise wird agents/review/security.md in einem Plugin namens my-plugin als my-plugin:review:security geladen. Zwei Einstellungen ändern diesen Namen:

  • Frontmatter name: Es ersetzt nur den Dateinamen, sodass name: audit in agents/review/security.md als my-plugin:review:audit geladen wird
  • Manifest-Feld agents: Eine dort aufgeführte Datei wird ohne Unterordnernamen geladen, sodass "agents": "./custom/review/security.md" als my-plugin:security geladen wird

Frontmatter-Felder in Plugin-Agenten

Das Frontmatter eines Plugin-Agenten folgt diesen Regeln:

  • Unterstützte Felder: name, description, model, effort, maxTurns, autoCompactWindow, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color und der Schlüssel cacheTtl von experimental. Der einzige gültige Wert für isolation ist "worktree". Was jedes Feld bewirkt, erfahren Sie unter unterstützte Frontmatter-Felder
  • Ignorierte Felder: permissionMode, hooks, mcpServers und initialPrompt. Eine Agentendatei kann selbst keine Hooks oder MCP-Server hinzufügen, fügen Sie diese daher stattdessen als Plugin-Hooks und MCP-Server hinzu
  • Frontmatter, das sich nicht parsen lässt: Der Agent wird trotzdem geladen, wobei alle Felder ignoriert werden. Er wird nach der Datei benannt, und seine Beschreibung lautet Agent from my-plugin plugin. Führen Sie claude plugin validate in Ihrer Shell aus, um diese Dateien zu finden

Was jedes Feld bewirkt und welche Vorrangregeln gelten, erfahren Sie unter Subagenten.

Hooks

Ein Hook führt an einem Punkt im Lebenszyklus von Claude Code automatisch etwas aus, etwa nach jeder Dateibearbeitung: einen Shell-Befehl, eine HTTP-Anfrage, einen MCP-Tool-Aufruf, einen Prompt an ein Modell oder einen Subagenten. Speichern Sie die Hooks des Plugins in hooks/hooks.json im Plugin-Stammverzeichnis unter einem "hooks"-Schlüssel auf oberster Ebene, in derselben Form wie das hooks-Objekt in settings.json. So können Sie einen vorhandenen Einstellungs-Hook unverändert übernehmen.

Dieser Hook führt nach jedem Write oder Edit ein mitgeliefertes Skript aus:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

Speichern Sie das Skript unter scripts/format.sh und machen Sie es ausführbar.

Laden Sie das Plugin und bitten Sie Claude, eine Datei zu bearbeiten. Ein PostToolUse-Hook, der mit 0 beendet wird, zeigt im Transkript nichts an. Bestätigen Sie daher seine Ausführung mit Debug-Logging oder anhand dessen, was das Skript selbst ändert.

Hooks in hooks/hooks.json und im Manifest-Schlüssel hooks werden beide geladen. Alle Ereignisse und ihre Payloads finden Sie unter Hook-Ereignisse.

Wenn ein anderes aktiviertes Plugin denselben Namen hat, registriert eines der beiden seine Hooks aus hooks/hooks.json, und die des anderen werden ausgelassen. Welches das ist und welcher Hinweis in /plugin Sie darüber informiert, erfahren Sie unter Hooks, wenn zwei aktivierte Plugins denselben Namen haben.

Um Hooks als JavaScript-Funktionen zu schreiben, die innerhalb von Claude Code laufen und in dessen Oberfläche zeichnen können, führen Sie eine Moduldatei unter einem modules-Schlüssel in derselben hooks/hooks.json auf. Ein Plugin mit einer solchen Datei ist ein Mod. Siehe Einen Mod erstellen.

Wann Plugin-Hooks ausgelöst werden

Die Hooks eines Plugins warten nicht darauf, dass einer der Skills oder Befehle des Plugins verwendet wird. Claude Code registriert sie, wenn eine Sitzung das Plugin lädt, und sie werden von da an bei ihren Ereignissen ausgelöst. Um einzuschränken, wann ein Hook ausgeführt wird, grenzen Sie seinen matcher ein.

Wenn ein Hook nie ausgelöst wird, siehe Hooks, die nicht ausgelöst werden.

Umgebung, Anführungszeichen und Abgleich von MCP-Tools

Die Umgebung des Hooks, das Setzen von ${CLAUDE_PLUGIN_ROOT} in Anführungszeichen und Matcher für die eigenen MCP-Tools des Plugins funktionieren wie folgt:

  • Umgebung: Jeder Hook-Prozess erhält CLAUDE_PLUGIN_ROOT und CLAUDE_PLUGIN_DATA in seiner Umgebung sowie CLAUDE_PLUGIN_OPTION_<KEY> für jeden Wert der Benutzerkonfiguration, sodass Ihr Skript sie von dort lesen kann
  • Anführungszeichen: Wenn command keine args hat, wird es über eine Shell ausgeführt. Setzen Sie den Pfad ${CLAUDE_PLUGIN_ROOT} daher in doppelte Anführungszeichen, wie im hooks/hooks.json-Beispiel unter Hooks, damit der expandierte Pfad ein einzelnes Shell-Wort bleibt. Wenn Sie stattdessen args übergeben, wird jedes Element ohne Shell als ein Argument übergeben und benötigt keine Anführungszeichen. Siehe Exec-Form und Shell-Form
  • Abgleich der eigenen MCP-Tools des Plugins: Ein Tool von einem MCP-Server, den dieses Plugin deklariert, heißt mcp__plugin_<plugin>_<server>__<tool>. Schreiben Sie daher diesen vollständigen Namen in den Matcher. Ein Matcher allein auf den Servernamen wird nie ausgelöst. Siehe MCP-Tools abgleichen

MCP-Server

Ein MCP-Server stellt Claude Tools aus einem externen System zur Verfügung. Deklarieren Sie ihn in .mcp.json im Plugin-Stammverzeichnis, in derselben Form wie eine Projekt-.mcp.json. Diese .mcp.json deklariert einen Server namens db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

Sie können den mcpServers-Wrapper auch weglassen und db auf die oberste Ebene der Datei setzen.

Laden Sie das Plugin und führen Sie /mcp aus, um zu bestätigen, dass der Server als plugin:my-plugin:db erscheint.

claude plugin validate prüft .mcp.json und meldet einen Servereintrag, den Claude Code beim Laden verwerfen würde, als Fehler. Erfordert Claude Code v2.1.281 oder neuer.

Wo ein fehlerhafter Eintrag beim Laden angezeigt wird, erfahren Sie unter MCP-Server, die nicht starten.

Der Manifest-Schlüssel mcpServers akzeptiert eine Inline-Server-Map, einen Pfad zu einer JSON-Datei oder ein Array davon. Wenn ein Manifest-Server denselben Namen wie einer in .mcp.json hat, ersetzt der Manifest-Server diesen.

Benutzer auf claude.ai und in Cowork erreichen

Ein lokaler stdio-Server, etwa der db-Server unter MCP-Server, läuft in Claude Code und in einer Cowork-Sitzung, die in der Claude Desktop-App auf Ihrem Rechner läuft, aber nicht auf claude.ai. Um auch Benutzer dort zu erreichen, verweisen Sie über seine https://-URL auf einen Remote-Server, den claude.ai und Cowork dem Benutzer als Konnektor anbieten, wie unter Einen MCP-Konnektor mit seinem Skill bündeln gezeigt.

Servernamen, Tool-Namen und Neuladen

Die Namen des Servers, die Variablenersetzung und das Verhalten beim Neuladen folgen diesen Regeln:

  • Servername: plugin:<plugin>:<server>, also ist der db-Server in my-plugin in /mcp gleich plugin:my-plugin:db. Verwenden Sie dieselbe Form, um den Server in einem mcp_tool-Hook zu benennen
  • Tool-Namen: mcp__plugin_<plugin>_<server>__<tool>, also ist ein query-Tool auf diesem db-Server gleich mcp__plugin_my-plugin_db__query. Diesen Namen verwenden Sie in Berechtigungsregeln und Hook-Matchern
  • Ersetzung: ${CLAUDE_PLUGIN_ROOT} und die anderen Pfadvariablen werden in command, args und env ersetzt. In args sind keine Anführungszeichen nötig, da jedes Element als ein Argument übergeben wird
  • Neuladen: Wenn der Benutzer /reload-plugins ausführt und das Neuladen greift, behält ein Server mit unveränderter Konfiguration seine Verbindung. Ein Server, dessen Konfiguration sich geändert hat, verbindet sich neu, und einer, den Sie entfernt haben, trennt die Verbindung

Einen gepackten MCPB-Server einbinden

Der Schlüssel mcpServers akzeptiert auch einen gepackten Server als MCPB-Datei mit der Endung .mcpb oder der älteren .dxt. Lassen Sie den Schlüssel auf die Datei verweisen, als Pfad innerhalb des Plugins oder als https://-URL:

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

Der Server erhält seinen Namen aus dem name im Manifest des Bundles.

Das eigene Manifest eines Bundles kann in einem user_config-Block Einstellungen deklarieren, die der Server vom Benutzer benötigt. Ein gebündelter Server mit einer erforderlichen Einstellung ohne gespeicherten Wert startet nicht. Der Tab Errors in /plugin zeigt Bundled MCP server "<name>" was not started: it needs configuration an.

Benutzer geben die Werte auf eine von zwei Arten an:

  • In /plugin: Wählen Sie das Plugin auf dem Tab Installed aus und wählen Sie Configure
  • Bei der Installation, über die Shell: Übergeben Sie --config <server>.<key>=<value> an claude plugin install. Erfordert Claude Code v2.1.285 oder neuer und funktioniert nur für ein Bundle, das innerhalb des Plugins gepackt ist.

Informationen zu Transporten und Authentifizierung finden Sie unter MCP.

LSP-Server

Ein LSP-Server stellt Claude Diagnosen und Code-Navigation für eine Sprache zur Verfügung. Wenn ein offizielles Code-Intelligence-Plugin Ihre Sprache bereits abdeckt, installieren Sie dieses, anstatt selbst eines zu schreiben. Andernfalls deklarieren Sie den Server in .lsp.json im Plugin-Stammverzeichnis:

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

Die Datei ordnet jeden Servernamen direkt seiner Konfiguration zu, ohne Wrapper-Objekt um die Map. command ist der Name der Binärdatei, deren Argumente in args stehen. extensionToLanguage benötigt mindestens eine Dateiendung, die jeweils mit . beginnt.

claude plugin validate liest diese Datei nicht. Wenn ein Eintrag ungültig ist, wird die gesamte Datei beim Laden übersprungen, und Invalid LSP server config for ".lsp.json" erscheint im Tab Errors von /plugin.

Ihr Plugin konfiguriert die Verbindung, installiert aber nicht die Binärdatei des Servers, und jede Dateiendung erhält einen Server:

  • Fehlende Binärdatei: Claude Code startet command über seinen Namen aus dem PATH des Benutzers. Wenn die Binärdatei dort nicht vorhanden ist, startet der Server nicht, und claude --debug protokolliert LSP server <name> failed to start
  • Konflikte bei Dateiendungen: Wenn zwei aktivierte Server dieselbe Dateiendung beanspruchen, verarbeitet der zuerst registrierte diese Dateien, und der andere wird dafür nicht verwendet, unabhängig davon, ob die Server aus einem oder zwei Plugins stammen. Der Tab Errors in /plugin zeigt die Warnung LSP server "<name>" is not used for <ext> files an

Der Manifest-Schlüssel lspServers akzeptiert dieselbe Map inline, einen Pfad zu einer JSON-Datei oder ein Array davon, und seine Server ergänzen die in .lsp.json. Wenn ein Manifest-Server denselben Namen wie einer in .lsp.json hat, ersetzt der Manifest-Server diesen.

Informationen zu transport, Timeouts, Neustarts und den anderen Feldern finden Sie unter lspServers.

Senden Sie Log-Ausgaben an stderr, nicht an stdout. Claude Code liest die stdout-Ausgabe eines Servers ausschließlich als Protokollnachrichten und akzeptiert Nachrichten-Header bis 64 KiB und einen Nachrichtentext bis 32 MiB.

Claude Code trennt die Verbindung zu einem Server, der eines der Limits überschreitet oder Ausgaben außerhalb des Protokolls an stdout schreibt, und zählt die Trennung als Absturz für restartOnCrash und maxRestarts. Wenn Sie mit --debug ausführen, schreibt Claude Code einen Fehler mit der Ursache in das Debug-Log.

Ausführbare Dateien

Dateien in bin/ im Plugin-Stammverzeichnis liegen im PATH der Shell des Bash-Tools, solange das Plugin aktiviert ist, sodass Claude sie als einfache Befehle ausführen kann. Ein Befehl, den Claude mit dem PowerShell-Tool außerhalb der Sandbox ausführt, findet sie ebenfalls in seinem PATH, ein in einer Sandbox ausgeführter PowerShell-Befehl dagegen nicht. Fügen Sie ein ausführbares Skript hinzu:

#!/bin/bash
echo "hello from my-plugin"

Machen Sie es mit chmod +x bin/hello-plugin ausführbar und laden Sie das Plugin. Wenn Sie Claude bitten, hello-plugin auszuführen, zeigt das Ergebnis des Bash-Tools die Ausgabe des Skripts.

Die bin/-Verzeichnisse von Plugins stehen hinter den eigenen PATH-Einträgen des Benutzers, sodass ein Plugin git, ls oder einen anderen Systembefehl nicht überdecken kann.

claude.ai und Cowork installieren kein Plugin mit einem bin/-Verzeichnis auf oberster Ebene, auch keines, das Sie über die Organisationseinstellungen von claude.ai verteilen.

Standardeinstellungen

Um Standardwerte festzulegen, die gelten, solange das Plugin aktiviert ist, fügen Sie eine settings.json im Plugin-Stammverzeichnis hinzu oder setzen Sie dasselbe Objekt inline in den Manifest-Schlüssel settings. Zwei Schlüssel werden wirksam, agent und subagentStatusLine, und alle anderen Schlüssel werden verworfen.

Legen Sie agent fest, um einen der eigenen Agenten des Plugins als Hauptthread auszuführen:

{
  "agent": "security-reviewer"
}

Laden Sie das Plugin und starten Sie eine Sitzung. Claude antwortet dann in der Hauptkonversation mit dem System-Prompt und dem Modell des Agenten security-reviewer.

Alles, was der Schlüssel steuert, finden Sie unter der Einstellung agent.

Wenn derselbe Schlüssel an mehr als einer Stelle festgelegt ist, entscheiden diese Regeln, welcher Wert gilt:

  • Datei vor Manifest: Wenn beide vorhanden sind und settings.json mindestens einen unterstützten Schlüssel festlegt, gilt settings.json, und settings im Manifest wird ignoriert
  • Benutzereinstellungen vor Plugin-Standardwerten: Über alle Einstellungsquellen hinweg bilden Plugin-Standardwerte die unterste Ebene, sodass ein eigenes agent des Benutzers in ~/.claude/settings.json Ihres überschreibt
  • Zwei Plugins legen denselben Schlüssel fest: Es gilt der Wert des zuletzt geladenen Plugins, und claude --debug protokolliert overrides setting

Die Form von subagentStatusLine finden Sie unter Statuszeilen für Subagenten.

Themes und Ausgabestile

Ein Plugin kann Farbthemes und Ausgabestile enthalten. Beide erscheinen in denselben Auswahlmenüs wie die eigenen des Benutzers. Für beide gilt: Wenn Sie den Manifest-Schlüssel festlegen, ersetzt dieser den Ordner-Scan.

Komponente Speichern als Format Erscheint in Manifest-Schlüssel
Theme themes/<slug>.json Das Format der benutzerdefinierten Theme-Datei, das Benutzer in ~/.claude/themes/ schreiben /theme, unter dem name der Datei experimental.themes
Ausgabestil output-styles/<name>.md Das Format des benutzerdefinierten Ausgabestils, mit name- und description-Frontmatter /output-style, als <plugin>:<name> outputStyles

Plugin-Themes sind schreibgeschützt. Wenn ein Benutzer eines in /theme bearbeitet, wird die Bearbeitung daher als Kopie in seinem eigenen Theme-Verzeichnis gespeichert.

Dieses Theme färbt den Prompt-Akzent und den Fehlertext der dunklen Voreinstellung um:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

Channels

Ein Channel ermöglicht es einem externen System wie einer Chat-App, Nachrichten in eine Sitzung zu senden. In einem Plugin ist ein Channel einer der MCP-Server plus ein channels-Eintrag, der an ihn gebunden ist und seine eigene Konfiguration abfragen kann. Dieses Manifest bindet einen Channel an einen telegram-Server und fragt nach einem Bot-Token:

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

server muss einem Schlüssel in mcpServers entsprechen. Das kanalspezifische userConfig hat dieselbe Form wie der userConfig-Schlüssel auf oberster Ebene.

Was der Server implementieren muss und wie Benutzer ein Channel-Plugin aktivieren, erfahren Sie unter Als Plugin paketieren in der Channels-Referenz. Die Feldtabelle finden Sie unter channels.

Monitore

Ein Monitor ist ein Shell-Befehl, der während der gesamten Sitzung im Hintergrund läuft. Was er ausgibt, erreicht Claude als Benachrichtigungen, sodass Claude auf ein Log oder eine Statusänderung reagieren kann, ohne zur Beobachtung aufgefordert zu werden. Speichern Sie die Einträge in monitors/monitors.json:

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

Der Befehl läuft in einer Shell im aktuellen Arbeitsverzeichnis der Sitzung. Er läuft mit Ihren vollen Benutzerberechtigungen und außerhalb der Sandbox.

Der Befehl eines Monitors ist eingeschränkt, was seinen Start und das betrifft, worauf er verweisen kann:

  • Nur interaktive Sitzungen: Plugin-Monitore starten in einer interaktiven Sitzung und nie im nicht interaktiven Modus mit dem Flag -p. Sie starten auch nicht in Sitzungen, in denen die Einstellungen für API-Anbieter oder Telemetrie das Monitor-Tool nicht verfügbar machen
  • Keine Benutzerkonfiguration: command erhält die Pfadvariablen und ${ENV_VAR} aus der Umgebung, aber nie ${user_config.*}. Ein Monitor, der auf eine solche verweist, startet nicht, und Monitor-Prozesse erhalten auch kein CLAUDE_PLUGIN_OPTION_<KEY>
  • Deaktivieren während der Sitzung: Wenn Sie ein Plugin während einer Sitzung deaktivieren, stoppt Claude Code bereits laufende Monitore nicht. Sie stoppen, wenn die Sitzung endet

Der Manifest-Schlüssel experimental.monitors akzeptiert dasselbe Array inline oder einen Pfad zu einer JSON-Datei und wird anstelle von monitors/monitors.json gelesen.

Informationen zum Trigger when und zu den anderen Feldern finden Sie unter monitors.

Fragen Sie den Benutzer nach Konfigurationswerten

Deklarieren Sie die Werte, die Ihr Plugin vom Benutzer benötigt, im userConfig-Manifest-Schlüssel, damit Benutzer nicht settings.json selbst bearbeiten. Jede Option erscheint in einem Dialog mit seinem title als Label und seiner description darunter.

Setzen Sie "sensitive": true für einen Token oder ein Passwort. Der Dialog maskiert dann die Eingabe, und der Wert wird in sicherer Speicherung statt settings.json gespeichert.

Dieses Manifest fragt nach einem Endpunkt und einem Token:

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

Wenn der Konfigurationsdialog erscheint

Der Dialog ist Teil der interaktiven /plugin-Schnittstelle. Wenn der Benutzer eines der folgenden tut, öffnet er sich für jede Option, die noch nicht gesetzt ist:

  • Installiert das Plugin in /plugin
  • Führt /plugin install <plugin>@<marketplace> in einer Sitzung aus
  • Aktiviert das Plugin aus der Installed-Registerkarte in /plugin

Um den gleichen Dialog jederzeit zu öffnen, führt der Benutzer /plugin configure <plugin>@<marketplace> aus.

Der Dialog des VS Code-Erweiterung Plugins verwalten fragt nach nicht gesetzten Optionen als Formular nach einer Installation, und ein Zahnradsymbol in der Zeile des Plugins öffnet das Formular erneut mit jeder Option.

Der claude plugin install-Shell-Befehl fordert nie userConfig-Werte auf. Um Werte aus der Shell zu setzen, übergeben Sie jeden als --config KEY=VALUE bei der Installation, oder leiten Sie ein JSON-Objekt an claude plugin configure --values-stdin danach weiter.

Wenn Optionen ungesetzt bleiben, druckt claude plugin install eine userConfig options not yet set-Zeile. Für den genauen Text der Zeile siehe Der userConfig-Dialog erscheint nie.

Für die Optionsfelder, wo jeder Wert gespeichert wird, wie eine Komponente einen gespeicherten Wert referenziert und welche Felder ${user_config.*} ablehnen, siehe Benutzerkonfiguration.

Referenzieren Sie Plugin-Pfade und speichern Sie Daten

Sie wissen nicht, wo Ihr Plugin installiert wird, daher referenzieren Sie seine Dateien und Daten durch diese Variablen statt fester Pfade. Sie werden in Skill-, Befehls- und Agent-Inhalten, in Hook- und Monitor-Befehlen und in MCP- und LSP-Server-Konfigurationen ersetzt. Sie werden auch an Hook-, MCP- und LSP-Prozesse exportiert:

  • ${CLAUDE_PLUGIN_ROOT}: Das Installationsverzeichnis des Plugins. Jede Version hat ihr eigenes Cache-Verzeichnis, daher ändert sich der Pfad, wenn das Plugin aktualisiert wird. Schreiben Sie keinen Zustand dort
  • ${CLAUDE_PLUGIN_DATA}: Ein Verzeichnis, das Updates überlebt, für node_modules, virtuelle Umgebungen und Caches. Es wird zu ~/.claude/plugins/data/<id>/ aufgelöst und wird erstellt, wenn zuerst referenziert
  • ${CLAUDE_PROJECT_DIR}: Das Projekt-Root, der gleiche Wert, den Hooks erhalten

Im Pfad des Daten-Verzeichnisses ist <id> die Plugin-ID mit jedem Zeichen außer Buchstaben, Ziffern, _ und - ersetzt durch -, daher wird my-plugin@my-marketplace zu my-plugin-my-marketplace.

Auf Windows verwenden die ersetzten Pfade Schrägstriche, daher liest eine Shell Backslashes nicht als Escapes.

Installieren Sie Abhängigkeiten in das Daten-Verzeichnis

Für ein Marketplace-installiertes Plugin installiert Claude Code automatisch berechtigte Node.js-Paket-Abhängigkeiten, wenn es das Plugin zwischenspeichert, daher müssen Sie sie möglicherweise nicht selbst installieren. Wenn Sie es tun, installiert dieser SessionStart-Hook node_modules in ${CLAUDE_PLUGIN_DATA} beim ersten Lauf und erneut nach einer Aktualisierung, die package.json ändert:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

Nach der ersten Sitzung existiert ~/.claude/plugins/data/<id>/node_modules. Ein MCP-Server kann dann NODE_PATH auf ${CLAUDE_PLUGIN_DATA}/node_modules in seinem env setzen. Für welche Felder welche Variable ersetzen, siehe Umgebungsvariablen.

Nächste Schritte