Plugins-Referenz

​

Plugin-Komponenten-Referenz

​

Skills

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

• Skills und Befehle werden automatisch erkannt, wenn das Plugin installiert wird
• Claude kann sie automatisch basierend auf dem Task-Kontext aufrufen
• Skills können unterstützende Dateien neben SKILL.md enthalten

​

Agents

---
name: agent-name
description: Worauf sich dieser Agent spezialisiert und wann Claude ihn aufrufen sollte
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailliertes System-Prompt für den Agent, das seine Rolle, Expertise und sein Verhalten beschreibt.

• Agents erscheinen in der @-mention Typeahead unter ihrem scoped Namen, wie my-plugin:code-reviewer, sobald das Plugin aktiviert ist
• Claude kann Agents automatisch basierend auf dem Task-Kontext aufrufen
• Agents können manuell von Benutzern aufgerufen werden
• Plugin-Agents funktionieren neben integrierten Claude-Agents

​

Hooks

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

• command: Shell-Befehle oder Skripte ausführen
• http: Das Event JSON als POST-Anfrage an eine URL senden
• mcp_tool: Ein Tool auf einem konfigurierten MCP-Server aufrufen
• prompt: Ein Prompt mit einem LLM evaluieren (verwendet $ARGUMENTS Platzhalter für Kontext)
• agent: Einen agentic Verifier mit Tools für komplexe Verifikationsaufgaben ausführen

​

MCP-Server

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

• Plugin MCP-Server starten automatisch, wenn das Plugin aktiviert wird
• Server erscheinen als Standard MCP-Tools in Claudes Toolkit
• Server-Fähigkeiten integrieren sich nahtlos mit Claudes vorhandenen Tools
• Plugin-Server können unabhängig von Benutzer MCP-Servern konfiguriert werden

​

LSP-Server

• Sofortige Diagnose: Claude sieht Fehler und Warnungen sofort nach jeder Bearbeitung
• Code-Navigation: Gehe zu Definition, finde Referenzen und Hover-Informationen
• Sprachbewusstsein: Typinformationen und Dokumentation für Code-Symbole

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

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

Monitore

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

​

Themes

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

​

Plugin-Installationsbereiche

​

Skills-Verzeichnis-Plugins

​

Wählen Sie, von wo das Plugin geladen wird

• MCP-Server, die es deklariert, durchlaufen die gleiche Pro-Server-Genehmigung wie ein Projekt .mcp.json
• LSP-Server starten nur, nachdem Sie dem Workspace vertrauen
• Hintergrund-Monitore werden nicht geladen

​

Bearbeiten, neu laden und deaktivieren Sie ein Skills-Verzeichnis-Plugin

claude plugin disable my-tool@skills-dir

​

Plugin-Manifest-Schema

​

Vollständiges Schema

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Erforderliche Felder

​

Nicht erkannte Felder

claude plugin validate ./my-plugin --strict

​

Metadaten-Felder

​

Standardaktivierung

• Die Einstellung des Benutzers: Ein Eintrag für das Plugin in enabledPlugins in jedem Einstellungsbereich. Einmal geschrieben, bleibt es über Plugin-Updates und Neuinstallationen bestehen, daher ändert das Ändern von defaultEnabled in einer späteren Version nicht einen bestehenden Benutzer.
• Eine Abhängigkeitsanforderung: Wenn ein Plugin von einem anderen erforderlich ist, das aktiv ist, schreibt Claude Code true dafür bei Installation oder Aktivierung. Das gibt ihm eine explizite Einstellung, daher gilt sein eigener Standard nicht mehr. Siehe Aktivieren oder Deaktivieren eines Plugins mit Abhängigkeiten.

​

Komponentenpfad-Felder

​

Experimentelle Komponenten

​

Benutzerkonfiguration

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

​

Kanäle

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

​

Pfad-Verhaltensregeln

• Ersetzt den Standard: commands, agents, outputStyles, experimental.themes, experimental.monitors. Beispielsweise wird das Standard-Verzeichnis commands/ nicht gescannt, wenn das Manifest commands angibt. Um den Standard zu behalten und mehr hinzuzufügen, listen Sie ihn explizit auf: "commands": ["./commands/", "./extras/"]
• Fügt zum Standard hinzu: skills. Das Standard-Verzeichnis skills/ wird immer gescannt, und Verzeichnisse, die in skills aufgelistet sind, werden zusammen mit ihm geladen. Ausnahme: für einen Marktplatz-Eintrag, dessen source zum Marktplatz-Root aufgelöst wird, ersetzt das Deklarieren spezifischer Unterverzeichnisse den Scan
• Eigene Merge-Regeln: hooks, MCP-Server und LSP-Server. Siehe jeden Abschnitt für die Kombinationsweise mehrerer Quellen

• Alle Pfade müssen relativ zum Plugin-Root sein und mit ./ beginnen
• Komponenten aus benutzerdefinierten Pfaden verwenden die gleichen Benennungs- und Namensgebungsregeln
• Mehrere Pfade können als Arrays angegeben werden
• Wenn ein Skill-Pfad auf ein Verzeichnis verweist, das direkt ein SKILL.md enthält, beispielsweise "skills": ["./"] verweist auf den Plugin-Root, bestimmt das Frontmatter-Feld name in SKILL.md den Aufrufen-Namen des Skills. Dies gibt einen stabilen Namen unabhängig vom Installationsverzeichnis. Wenn name nicht im Frontmatter gesetzt ist, wird der Verzeichnis-Basename als Fallback verwendet.

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

​

Umgebungsvariablen

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

​

Persistentes Datenverzeichnis

{
  "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\""
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

​

Plugin-Caching und Dateiauflösung

• Durch claude --plugin-dir oder claude --plugin-url, für die Dauer einer Session.
• Durch einen Marktplatz, installiert für zukünftige Sessions.

​

Pfad-Traversal-Einschränkungen

​

Dateien innerhalb eines Marktplatzes mit Symlinks freigeben

• Innerhalb des eigenen Verzeichnisses des Plugins: Der Symlink wird als relativer Symlink im Cache beibehalten, sodass er zur Laufzeit weiterhin zum kopierten Ziel aufgelöst wird.
• Anderswo innerhalb desselben Marktplatzes: Der Symlink wird dereferenziert. Der Inhalt des Ziels wird stattdessen in den Cache kopiert. Dies ermöglicht es einem Meta-Plugin, sein skills/-Verzeichnis mit Skills zu verknüpfen, die von anderen Plugins im Marktplatz definiert werden.
• Außerhalb des Marktplatzes: Der Symlink wird aus Sicherheitsgründen übersprungen. Dies verhindert, dass Plugins beliebige Host-Dateien wie Systempfade in den Cache ziehen.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Plugin-Verzeichnisstruktur

​

Standard-Plugin-Layout

enterprise-plugin/
├── .claude-plugin/           # Metadaten-Verzeichnis (optional)
│   └── plugin.json             # Plugin-Manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills als flache .md Dateien
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent-Definitionen
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Output-Style-Definitionen
│   └── terse.md
├── themes/                   # Farbschema-Definitionen
│   └── dracula.json
├── monitors/                 # Hintergrund-Monitor-Konfigurationen
│   └── monitors.json
├── hooks/                    # Hook-Konfigurationen
│   ├── hooks.json           # Haupt-Hook-Konfiguration
│   └── security-hooks.json  # Zusätzliche Hooks
├── bin/                      # Plugin-Ausführbare Dateien, die zu PATH hinzugefügt werden
│   └── my-tool               # Aufrufbar als bloßer Befehl im Bash-Tool
├── settings.json            # Standardeinstellungen für das Plugin
├── .mcp.json                # MCP-Server-Definitionen
├── .lsp.json                # LSP-Server-Konfigurationen
├── scripts/                 # Hook- und Utility-Skripte
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Lizenzdatei
└── CHANGELOG.md             # Versionsverlauf

​

Datei-Speicherorte-Referenz

​

CLI-Befehle-Referenz

​

plugin init

claude plugin init <name> [options]

• <name>: Plugin-Name. Wird zum Skill-Namespace und zum Verzeichnisnamen unter ~/.claude/skills/, daher kann er keine Leerzeichen oder Pfad-Trennzeichen enthalten.

# Erstellen Sie ein minimales Plugin
claude plugin init my-helper

# Erstellen Sie mit Skill- und Hook-Ordnern
claude plugin init my-helper --with skills hooks

# Überschreiben Sie ein vorhandenes Gerüst
claude plugin init my-helper --force

​

plugin install

claude plugin install <plugin> [options]

• <plugin>: Plugin-Name oder plugin-name@marketplace-name für einen bestimmten Marktplatz

# Installieren Sie im Benutzerbereich (Standard)
claude plugin install formatter@my-marketplace

# Installieren Sie im Projektbereich (geteilt mit Team)
claude plugin install formatter@my-marketplace --scope project

# Installieren Sie im lokalen Bereich (gitignoriert)
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

• <plugin>: Plugin-Name oder plugin-name@marketplace-name

​

plugin prune

claude plugin prune [options]

​

plugin enable

claude plugin enable <plugin> [options]

• <plugin>: Plugin-Name oder plugin-name@marketplace-name

​

plugin disable

claude plugin disable <plugin> [options]

• <plugin>: Plugin-Name oder plugin-name@marketplace-name

​

plugin update

claude plugin update <plugin> [options]

• <plugin>: Plugin-Name oder plugin-name@marketplace-name

​

plugin list

claude plugin list [options]

​

plugin details

claude plugin details <name>

• <name>: Plugin-Name oder plugin-name@marketplace-name

• Always-on: Token, die jeder Sitzung durch den Auflistungstext des Plugins hinzugefügt werden, wie Skill-Beschreibungen, Agent-Beschreibungen und Befehlsnamen, unabhängig davon, ob eine Komponente ausgelöst wird.
• On-invoke: Token, die eine Komponente kostet, wenn sie ausgelöst wird. Wird pro Komponente angezeigt, nicht als Plugin-Gesamtsumme, da eine typische Sitzung nur eine Teilmenge von Komponenten aufruft.

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

​

plugin tag

claude plugin tag [options]

​

Debugging- und Entwicklungstools

​

Debugging-Befehle

• Welche Plugins geladen werden
• Alle Fehler in Plugin-Manifesten
• Skill-, Agent- und Hook-Registrierung
• MCP-Server-Initialisierung

​

Häufige Probleme

​

Beispiel-Fehlermeldungen

• Invalid JSON syntax: Unexpected token } in JSON at position 142: Überprüfen Sie auf fehlende Kommas, zusätzliche Kommas oder nicht zitierte Strings
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: Ein erforderliches Feld fehlt
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON-Syntaxfehler

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: Befehlspfad existiert, enthält aber keine gültigen Befehlsdateien
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: Der source Pfad in marketplace.json verweist auf ein nicht existierendes Verzeichnis
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: Entfernen Sie doppelte Komponentendefinitionen oder entfernen Sie strict: false im Marktplatz-Eintrag

​

Hook-Fehlerbehebung

1. Überprüfen Sie, dass das Skript ausführbar ist: chmod +x ./scripts/your-script.sh
2. Überprüfen Sie die Shebang-Zeile: Erste Zeile sollte #!/bin/bash oder #!/usr/bin/env bash sein
3. Überprüfen Sie, dass der Pfad ${CLAUDE_PLUGIN_ROOT} verwendet: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Testen Sie das Skript manuell: ./scripts/your-script.sh

1. Überprüfen Sie, dass der Event-Name korrekt ist (Groß-/Kleinschreibung beachten): PostToolUse, nicht postToolUse
2. Überprüfen Sie, dass das Matcher-Muster Ihre Tools passt: "matcher": "Write|Edit" für Dateivorgänge
3. Bestätigen Sie, dass der Hook-Typ gültig ist: command, http, mcp_tool, prompt oder agent

​

MCP-Server-Fehlerbehebung

1. Überprüfen Sie, dass der Befehl existiert und ausführbar ist
2. Überprüfen Sie, dass alle Pfade die ${CLAUDE_PLUGIN_ROOT} Variable verwenden
3. Überprüfen Sie die MCP-Server-Logs: claude --debug zeigt Initialisierungsfehler
4. Testen Sie den Server manuell außerhalb von Claude Code

1. Stellen Sie sicher, dass der Server ordnungsgemäß in .mcp.json oder plugin.json konfiguriert ist
2. Überprüfen Sie, dass der Server das MCP-Protokoll ordnungsgemäß implementiert
3. Überprüfen Sie auf Verbindungs-Timeouts in der Debug-Ausgabe

​

Verzeichnisstruktur-Fehler

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Nur Manifest hier
├── commands/            ← Auf Root-Ebene
├── agents/              ← Auf Root-Ebene
└── hooks/               ← Auf Root-Ebene

1. Führen Sie claude --debug aus und suchen Sie nach „loading plugin” Meldungen
2. Überprüfen Sie, dass jedes Komponentenverzeichnis in der Debug-Ausgabe aufgelistet ist
3. Überprüfen Sie Dateiberechtigungen, die das Lesen der Plugin-Dateien ermöglichen

​

Verteilungs- und Versionierungs-Referenz

​

Versionsverwaltung

1. Das Feld version in der plugin.json des Plugins
2. Das Feld version im Marketplace-Eintrag des Plugins in marketplace.json
3. Der Git-Commit-SHA des Plugin-Quellcodes für github, url, git-subdir und relative-path-Quellen in einem Git-gehosteten Marketplace
4. unknown, für npm-Quellen oder lokale Verzeichnisse, die sich nicht in einem Git-Repository befinden

​

Siehe auch

• Plugins - Tutorials und praktische Verwendung
• Plugin-Marktplätze - Erstellen und Verwalten von Marktplätzen
• Skills - Skill-Entwicklungsdetails
• Subagents - Agent-Konfiguration und Fähigkeiten
• Hooks - Event-Handling und Automatisierung
• MCP - Integration externer Tools
• Einstellungen - Konfigurationsoptionen für Plugins