SpyBara
Go Premium

plugins/components.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 1130 additions and 0 deletions.

2026
Fri 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.

export const Piece = ({id, children}) =>

{children}
;

export const PluginExplorer = ({children}) => { const PIECES = [{ id: 'manifest', name: 'Manifest', path: '.claude-plugin/plugin.json', required: "Required by Anthropic's directory", lines: [{ depth: 0, kind: 'folder', text: '.claude-plugin/' }, { depth: 1, kind: 'file', text: 'plugin.json' }], href: '/en/plugins/manifest-reference#manifest-file', linkText: 'Go to the manifest reference' }, { id: 'skills', name: 'Skills', path: 'skills/review/SKILL.md', lines: [{ depth: 0, kind: 'folder', text: 'skills/' }, { depth: 1, kind: 'folder', text: 'review/' }, { depth: 2, kind: 'file', text: 'SKILL.md' }], href: '/en/plugins/components#skills', linkText: 'Go to the Skills section' }, { id: 'commands', name: 'Commands', path: 'commands/about.md', lines: [{ depth: 0, kind: 'folder', text: 'commands/' }, { depth: 1, kind: 'file', text: 'about.md' }], href: '/en/plugins/components#commands', linkText: 'Go to the Commands section' }, { id: 'agents', name: 'Agents', path: 'agents/security-reviewer.md', lines: [{ depth: 0, kind: 'folder', text: 'agents/' }, { depth: 1, kind: 'file', text: 'security-reviewer.md' }], href: '/en/plugins/components#agents', linkText: 'Go to the Agents section' }, { id: 'hooks', name: 'Hooks', path: 'hooks/hooks.json', lines: [{ depth: 0, kind: 'folder', text: 'hooks/' }, { depth: 1, kind: 'file', text: 'hooks.json' }], href: '/en/plugins/components#hooks', linkText: 'Go to the Hooks section' }, { id: 'monitors', name: 'Monitors', path: 'monitors/monitors.json', lines: [{ depth: 0, kind: 'folder', text: 'monitors/' }, { depth: 1, kind: 'file', text: 'monitors.json' }], href: '/en/plugins/components#monitors', linkText: 'Go to the Monitors section' }, { id: 'output-styles', name: 'Output styles', path: 'output-styles/terse.md', lines: [{ depth: 0, kind: 'folder', text: 'output-styles/' }, { depth: 1, kind: 'file', text: 'terse.md' }], href: '/en/plugins/components#themes-and-output-styles', linkText: 'Go to the Themes and output styles section' }, { id: 'themes', name: 'Themes', path: 'themes/dracula.json', lines: [{ depth: 0, kind: 'folder', text: 'themes/' }, { depth: 1, kind: 'file', text: 'dracula.json' }], href: '/en/plugins/components#themes-and-output-styles', linkText: 'Go to the Themes and output styles section' }, { id: 'workflows', name: 'Workflows', path: 'workflows/audit-routes.js', lines: [{ depth: 0, kind: 'folder', text: 'workflows/' }, { depth: 1, kind: 'file', text: 'audit-routes.js' }], href: '/en/workflows#distribute-a-workflow-in-a-plugin', linkText: 'Go to Distribute a workflow in a plugin' }, { id: 'bin', name: 'Executables', path: 'bin/hello-plugin', lines: [{ depth: 0, kind: 'folder', text: 'bin/' }, { depth: 1, kind: 'file', text: 'hello-plugin' }], href: '/en/plugins/components#executables', linkText: 'Go to the Executables section' }, { id: 'scripts', name: 'Scripts', path: 'scripts/format.sh', lines: [{ depth: 0, kind: 'folder', text: 'scripts/' }, { depth: 1, kind: 'file', text: 'format.sh' }], href: '/en/plugins/components#hooks', linkText: 'Go to the Hooks section' }, { id: 'settings', name: 'Default settings', path: 'settings.json', lines: [{ depth: 0, kind: 'file', text: 'settings.json' }], href: '/en/plugins/components#default-settings', linkText: 'Go to the Default settings section' }, { id: 'mcp', name: 'MCP servers', path: '.mcp.json', lines: [{ depth: 0, kind: 'file', text: '.mcp.json' }], href: '/en/plugins/components#mcp-servers', linkText: 'Go to the MCP servers section' }, { id: 'lsp', name: 'LSP servers', path: '.lsp.json', lines: [{ depth: 0, kind: 'file', text: '.lsp.json' }], href: '/en/plugins/components#lsp-servers', linkText: 'Go to the LSP servers section' }]; const [selectedId, setSelectedId] = useState('manifest'); const [isFullscreen, setIsFullscreen] = useState(false); const rootRef = useRef(null); useEffect(() => { const onFsChange = () => setIsFullscreen(!!document.fullscreenElement); document.addEventListener('fullscreenchange', onFsChange); return () => document.removeEventListener('fullscreenchange', onFsChange); }, []); const toggleFullscreen = () => { if (!rootRef.current) return; if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {}); }; const selected = PIECES.find(p => p.id === selectedId) || PIECES[0]; const onTreeKeyDown = e => { const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End']; if (keys.indexOf(e.key) === -1) return; const i = PIECES.findIndex(p => p.id === selectedId); let next = i; if (e.key === 'ArrowDown') next = Math.min(PIECES.length - 1, i + 1); if (e.key === 'ArrowUp') next = Math.max(0, i - 1); if (e.key === 'Home') next = 0; if (e.key === 'End') next = PIECES.length - 1; e.preventDefault(); if (next === i) return; const id = PIECES[next].id; setSelectedId(id); const el = document.getElementById('pe-node-' + id); if (el) el.focus(); }; const FolderIcon = () => ; const FileIcon = () => ; return <div ref={rootRef} className={isFullscreen ? 'pe-root pe-fullscreen not-prose' : 'pe-root not-prose'} data-selected={selected.id}>

  <div className="pe-head">
    <div className="pe-head-text">
      <div className="pe-title">What goes in a plugin</div>
      <div className="pe-sub">This example plugin, <code>my-plugin</code>, 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.</div>
    </div>
    <button type="button" className="pe-fs-btn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>
      {isFullscreen ? '⤡' : '⛶'}
    </button>
  </div>

  <div className="pe-body">
    <div className="pe-tree-pane">
      <div className="pe-caption" id="pe-tree-caption">Plugin directory</div>
      <div role="group" aria-labelledby="pe-tree-caption" onKeyDown={onTreeKeyDown}>
        <div className="pe-rootline"><FolderIcon /><span>my-plugin/</span></div>
        {PIECES.map(p => <button key={p.id} id={'pe-node-' + p.id} type="button" className="pe-node" aria-pressed={p.id === selected.id} aria-label={p.name + ', ' + p.path} onClick={() => setSelectedId(p.id)}>
            {p.lines.map((line, i) => <span key={i} className="pe-line pe-line-tree" style={{
paddingLeft: line.depth * 18 + 'px'

}}> {line.kind === 'folder' ? : } {line.text} {p.required && i === p.lines.length - 1 ? {p.required} : null} )} {p.path} {p.required ? {p.required} : null} )}

    <div className="pe-panel" role="region" aria-labelledby="pe-panel-caption" aria-live="polite" aria-atomic="true">
      <div className="pe-caption" id="pe-panel-caption">Selected piece</div>
      <div className="pe-name">{selected.name}{selected.required ? <span className="pe-req">{selected.required}</span> : null}</div>
      <div className="pe-path">{selected.path}</div>

      <div className="pe-block">{children}</div>

      <a className="pe-link" href={selected.href}>{selected.linkText}</a>
    </div>
  </div>
</div>;

};

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.

Plugin-Verzeichnis erkunden

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

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.

Das [Manifest](/docs/de/plugins/manifest-reference) 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. Nur `name` ist 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:
```json theme={null}
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review, formatting, and database tools for this team"
}
```
Ein [Skill](/docs/de/skills) 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:
```markdown theme={null}
---
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:
```markdown theme={null}
---
description: Summarize the repository
---

Summarize what this repository does in three sentences.
```
Ein [Subagent](/docs/de/sub-agents) 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:
```markdown theme={null}
---
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](/docs/de/hooks-guide) 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:
```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}
```
Ein Monitor ist ein Shell-Befehl, den Claude Code im Hintergrund startet, wenn die Sitzung startet, und der läuft, bis sie endet, unter Verwendung des [Monitor-Tools](/docs/de/tools-reference#monitor-tool). 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 Fehlerprotokoll:
```json theme={null}
[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]
```
Ein Plugin kann [Output-Stile](/docs/de/output-styles) enthalten, die ändern, wie Claude seine Antworten formatiert und formuliert. Speichern Sie jeden Output-Stil als `output-styles/.md`. Dieser erscheint in `/output-style` als `my-plugin:terse`:
```markdown theme={null}
---
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](/docs/de/terminal-config#create-a-custom-theme) für die Claude Code-Schnittstelle enthalten. Speichern Sie jedes Schema als `themes/.json`. Dieses erscheint in `/theme` als `Dracula`, markiert als von `my-plugin`:
```json theme={null}
{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}
```
Der `workflows/`-Ordner enthält [Workflow](/docs/de/workflows) `.js`-Dateien: einen `meta`-Block, dann einen Script-Text, der mehrere Subagenten orchestriert. Dieser läuft als `/my-plugin:audit-routes`:
```javascript theme={null}
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](#executables) an Ort und Stelle ist `hello-plugin` ein Befehl, den Claude ausführen kann:
```bash theme={null}
#!/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:
```bash theme={null}
#!/bin/bash
npx prettier --write .
```
Eine `settings.json` im Plugin-Root hält [Einstellungen](/docs/de/settings-reference), 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`](/docs/de/settings-reference#agent) und [`subagentStatusLine`](/docs/de/settings-reference#subagentstatusline); jeder andere Schlüssel wird gelöscht. Siehe [Standard-Einstellungen](#default-settings).
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:

```json theme={null}
{
  "agent": "security-reviewer"
}
```
Ein [MCP-Server](/docs/de/mcp) 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`:
```json theme={null}
{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}
```
Ein LSP-Server gibt Claude [Diagnostik und Code-Navigation](/docs/de/plugins/code-intelligence) für eine Sprache. Deklarieren Sie den Server in `.lsp.json` im Plugin-Root. Dieser verbindet den Go-Sprachserver für `.go`-Dateien:
```json theme={null}
{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
```

Fügen Sie jede Art von Komponente hinzu

Jeder Abschnitt unten behandelt eine Art von Komponente: wo ihre Dateien im Plugin gehen, ein Beispiel, das validiert, was der Benutzer sieht, sobald das Plugin geladen wird, und der Manifest-Schlüssel, der den Standard-Speicherort ändert. Fügen Sie die hinzu, die Ihr Plugin benötigt; keine ist erforderlich.

Skills

Ein Skill ist eine SKILL.md-Datei, die Claude laden kann, wenn ihre Beschreibung der Aufgabe entspricht. Der Benutzer kann ihn auch als Befehl ausführen. Speichern Sie jeden Skill in seinem 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 sie verwenden 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:

Sie können auch Skills außerhalb des Standard-skills/-Verzeichnisses platzieren:

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

Für Frontmatter-Felder und unterstützende Dateien siehe Skills.

Befehle

Ein Befehl ist eine einzelne Markdown-Datei, die der Benutzer nach Name ausführt, wie /my-plugin:about.

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

Befehlsdateien nehmen die gleiche Frontmatter wie Skills.

Definieren Sie Befehle im Manifest

Sie brauchen dies nur, wenn Sie Befehlsdateien irgendwo anders als commands/ behalten möchten, oder um einen kurzen Befehl in plugin.json ohne separate Markdown-Datei zu definieren. Setzen Sie den commands-Manifest-Schlüssel, und Claude Code liest ihn statt commands/ zu scannen. Der Schlüssel nimmt einen Pfad, ein Array von Pfaden oder ein Objekt, das jeden Befehlsnamen entweder auf eine source-Datei oder inline content abbildet.

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 es geladen wurde.

Für die vollständige Schlüsselsyntax siehe commands.

Agents

Ein Subagent ist ein separater Assistent mit seinen eigenen Anweisungen und Kontextfenster, dem 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 wird my-plugin:security-reviewer genannt, und der Benutzer kann ihn explizit aufrufen mit @agent-my-plugin:security-reviewer. Die Namensform ist <plugin>:<name>, wobei <name> aus der Frontmatter kommt, oder aus dem Dateinamen, wenn es keine gibt.

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

Organisieren Sie Agents in Unterordnern

Sie können Plugin-Agent-Dateien in Unterordnern von agents/ platzieren. Claude Code lädt sie rekursiv und verbindet den Plugin-Namen, jeden Unterordnernamen und den Dateinamen mit Doppelpunkten, um den scoped Namen des Agenten zu bilden. Zum Beispiel lädt agents/review/security.md in einem Plugin namens my-plugin als my-plugin:review:security. Zwei Einstellungen ändern diesen Namen:

Frontmatter-Felder in Plugin-Agents

Die Frontmatter eines Plugin-Agenten folgt diesen Regeln:

Für das, was jedes Feld tut und die Vorrangregeln, siehe Subagents.

Hooks

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, unter einem Top-Level-"hooks"-Schlüssel, in der gleichen Form wie das hooks-Objekt in settings.json. Das ermöglicht es Ihnen, einen bestehenden Settings-Hook unverändert zu kopieren.

Dieser Hook führt ein gebündeltes Script nach jedem Write oder Edit aus:

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

Speichern Sie das Script 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 0 beendet, zeigt nichts im Transkript, daher bestätigen Sie, dass er mit Debug-Logging oder durch das, was das Script selbst ändert, gelaufen ist.

Hooks in hooks/hooks.json und im hooks-Manifest-Schlüssel laden beide. Für jedes Ereignis und seine Nutzlast siehe Hook-Ereignisse.

Wenn Plugin-Hooks auslösen

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 lösen auf ihren Ereignissen von da an aus. Um einzuschränken, wann ein Hook läuft, verengen Sie seinen matcher.

Wenn ein Hook nie auslöst, siehe Hooks, die nicht auslösen.

Umgebung, Anführungszeichen und Matching von MCP-Tools

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

MCP-Server

Ein MCP-Server gibt Claude Tools von einem externen System. Deklarieren Sie ihn in .mcp.json im Plugin-Root, in der gleichen Form wie ein Projekt .mcp.json. Diese .mcp.json deklariert einen Server namens db:

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

Sie können auch den mcpServers-Wrapper weglassen und db auf der Top-Level der Datei platzieren.

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 überprüft .mcp.json und meldet einen Server-Eintrag, den Claude Code zur Ladezeit als Fehler ablegen würde. Erfordert Claude Code v2.1.281 oder später.

Für wo ein schlechter Eintrag zur Ladezeit angezeigt wird, siehe MCP-Server, die nicht starten.

Der mcpServers-Manifest-Schlüssel nimmt eine inline Server-Map, einen Pfad zu einer JSON-Datei oder ein Array davon. Wenn ein Manifest-Server den gleichen Namen wie einer in .mcp.json hat, ersetzt der Manifest-Server ihn.

Erreichen Sie Benutzer auf claude.ai und Cowork

Ein lokaler Stdio-Server, wie der db-Server unter MCP-Server, läuft in Claude Code und in einer Cowork-Sitzung, die auf Ihrem Computer in der Claude Desktop-App läuft, aber nicht auf claude.ai. Um Benutzer dort auch zu erreichen, referenzieren Sie einen Remote-Server durch seine https://-URL, die claude.ai und Cowork dem Benutzer als Connector anbieten.

Server-Namen, Tool-Namen und Neuladen

Die Namen des Servers, die Variable-Substitution und das Neuladen-Verhalten folgen diesen Regeln:

Schließen Sie einen verpackten MCPB-Server ein

Der mcpServers-Schlüssel akzeptiert auch einen verpackten Server als MCPB-Datei, deren Erweiterung .mcpb oder die ältere .dxt ist. Zeigen Sie den Schlüssel auf die Datei, als Pfad im Plugin oder eine https://-URL:

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

Der Server nimmt seinen Namen aus dem name im Manifest des Bundles.

Für Transporte und Authentifizierung siehe MCP.

LSP-Server

Ein LSP-Server gibt Claude Diagnostik und Code-Navigation für eine Sprache. Wenn ein offizielles Code-Intelligence-Plugin Ihre Sprache bereits abdeckt, installieren Sie das statt einen zu schreiben. Andernfalls deklarieren Sie den Server in .lsp.json im Plugin-Root:

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

Die Datei bildet jeden Server-Namen direkt auf seine Konfiguration ab, ohne ein Wrapper-Objekt um die Map. command ist der Name des Binärs, mit seinen Argumenten in args. extensionToLanguage braucht mindestens eine Erweiterung, jede beginnend mit ..

claude plugin validate liest diese Datei nicht. Wenn ein Eintrag ungültig ist, wird die ganze Datei zur Ladezeit übersprungen und Invalid LSP server config for ".lsp.json" erscheint in der /plugin-Registerkarte Errors.

Ihr Plugin konfiguriert die Verbindung, installiert aber nicht das Server-Binär, und jede Dateierweiterung bekommt einen Server:

Der lspServers-Manifest-Schlüssel nimmt die gleiche 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 den gleichen Namen wie einer in .lsp.json hat, ersetzt der Manifest-Server ihn.

Für transport, Timeouts, Neustarts und die anderen Felder siehe lspServers.

Senden Sie Log-Ausgabe an stderr, nicht stdout. Claude Code liest den stdout eines Servers nur als Protokoll-Nachrichten und akzeptiert Nachrichten-Header bis zu 64 KiB und einen Nachrichten-Text bis zu 32 MiB.

Claude Code trennt einen Server, der eines der Limits überschreitet oder nicht-Protokoll-Ausgabe an stdout schreibt, und zählt die Trennung als Absturz für restartOnCrash und maxRestarts. Wenn Sie mit --debug laufen, schreibt Claude Code einen Fehler, der die Ursache benennt, in das Debug-Log.

Ausführbare Dateien

Dateien in bin/ im Plugin-Root sind auf dem PATH der Shell des Bash-Tools, während das Plugin aktiviert ist, daher kann Claude sie als bloße Befehle ausführen. Fügen Sie ein ausführbares Script 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 Bash-Tool-Ergebnis die Ausgabe des Scripts.

Plugin-bin/-Verzeichnisse kommen nach den eigenen PATH-Einträgen des Benutzers, daher kann ein Plugin nicht git, ls oder einen anderen System-Befehl überschatten.

claude.ai und Cowork installieren kein Plugin, das ein Top-Level-bin/-Verzeichnis hat, einschließlich eines, das Sie über claude.ai-Organisationseinstellungen verteilen.

Standard-Einstellungen

Um Standard-Einstellungen zu setzen, die gelten, während das Plugin aktiviert ist, fügen Sie eine settings.json im Plugin-Root hinzu, oder setzen Sie das gleiche Objekt inline im settings-Manifest-Schlüssel. Zwei Schlüssel wirken sich aus, agent und subagentStatusLine, und jeder andere Schlüssel wird gelöscht.

Setzen Sie agent, um einen der eigenen Agents des Plugins als Haupt-Thread auszuführen:

{
  "agent": "security-reviewer"
}

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

Für alles, das der Schlüssel kontrolliert, siehe die agent-Einstellung.

Wenn der gleiche Schlüssel an mehr als einem Ort gesetzt ist, entscheiden diese Regeln, welcher Wert angewendet wird:

Für die subagentStatusLine-Form siehe Subagent-Statuszeilen.

Themen und Output-Stile

Ein Plugin kann Farbschemas und Output-Stile enthalten. Beide erscheinen in den gleichen Pickern wie die des Benutzers. Für jeden setzt der Manifest-Schlüssel den Ordner-Scan.

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

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

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

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

Kanäle

Ein Kanal ermöglicht es einem externen System wie einer Chat-App, Nachrichten in eine Sitzung zu senden. In einem Plugin ist ein Kanal einer der MCP-Server plus ein channels-Eintrag, der sich daran bindet und seine eigene Konfiguration auffordern kann. Dieses Manifest bindet einen Kanal 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. Die pro-Kanal userConfig nimmt die gleiche Form wie der Top-Level-userConfig-Schlüssel.

Für das, was der Server implementieren muss und wie Benutzer einen Kanal-Plugin aktivieren, siehe Als Plugin verpacken in der Kanäle-Referenz. Für die Feldtabelle siehe channels.

Monitore

Ein Monitor ist ein Shell-Befehl, der im Hintergrund für die ganze Sitzung läuft. Was er ausgibt, erreicht Claude als Benachrichtigungen, daher kann Claude auf ein Protokoll oder eine Statusänderung reagieren, ohne gebeten zu werden, es zu beobachten. 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 Arbeitsverzeichnis, in dem die Sitzung gestartet wurde.

Der Befehl eines Monitors ist begrenzt, wo er startet und was er referenzieren kann:

Der experimental.monitors-Manifest-Schlüssel nimmt das gleiche Array inline oder einen Pfad zu einer JSON-Datei und wird statt monitors/monitors.json gelesen.

Für den when-Trigger und die anderen Felder siehe 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 erscheint nur in der interaktiven /plugin-Schnittstelle. Er öffnet sich für jede Option, die noch nicht gesetzt ist, wenn der Benutzer eines der folgenden tut:

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

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. Wenn Optionen ungesetzt bleiben, druckt der Befehl eine userConfig options not yet set-Zeile, die beide Wege benennt, um sie zu setzen. Der userConfig-Dialog erscheint nie zitiert die Zeile.

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:

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