Plugin-Struktur

Anatomie eines Plugins

Ein Plugin ist im Kern ein Verzeichnis mit einer festen Struktur. Das Herzstück ist die Datei plugin.json im Ordner .claude-plugin/ -- sie identifiziert das Verzeichnis als Plugin und enthält die Metadaten.

Verzeichnisstruktur

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest (Pflicht)
├── skills/
│   ├── review.md            # Skill-Definitionen
│   └── deploy.md
├── agents/
│   └── security-agent.md    # Agent-Definitionen
├── hooks/
│   └── hooks.json           # Hook-Konfiguration
├── .mcp.json                # MCP-Server-Konfiguration
└── settings.json            # Plugin-Einstellungen

Nur .claude-plugin/plugin.json ist verpflichtend. Alle anderen Ordner und Dateien sind optional -- du nutzt nur, was dein Plugin braucht.

Das plugin.json Manifest

Das Manifest ist die Visitenkarte deines Plugins:

{
  "name": "my-security-plugin",
  "version": "1.0.0",
  "description": "Security-Toolkit mit Vulnerability-Scans und Code-Reviews",
  "author": {
    "name": "Dein Name"
  }
}

Der name muss eindeutig sein -- er wird zum Namespace-Präfix für alle Skills und Agents im Plugin.

Gebündelt als Einheit

Klicke auf eine Ebene

Das Gesamtpaket: plugin.json Manifest definiert Name, Version, Namespace und gebündelte Komponenten.

mein-plugin/ mit plugin.json

Wiederverwendbare Workflows als Markdown-Dateien. Werden über /slash-Befehle ausgelöst.

/review, /deploy, /test

Spezialisierte Subagent-Konfigurationen mit eigenem Modell, Tools und Instruktionen.

review-agent.md, test-agent.md

Automatisierungs-Hooks und MCP-Server-Konfigurationen die mit dem Plugin installiert werden.

PostToolUse hooks, lokale MCP-Server

Namespace-Isolation im Detail

Namespace-Isolation ist das Feature, das Plugins sicher und konfliktfrei macht. Jeder Skill im Plugin bekommt automatisch das Präfix /plugin-name::

Skill-Datei	Aufruf im Chat
`skills/review.md`	`/my-security-plugin:review`
`skills/deploy.md`	`/my-security-plugin:deploy`

Das bedeutet: Selbst wenn drei verschiedene Plugins jeweils einen Skill namens review definieren, gibt es keine Kollision. Jeder ist über seinen vollqualifizierten Namen eindeutig ansprechbar.

iWarum Namespaces wichtig sind

Ohne Namespaces würde das Installieren eines neuen Plugins möglicherweise bestehende Skills überschreiben. Die Namespace-Isolation garantiert, dass Plugins sich nie gegenseitig stören -- genau wie Module in Python oder Packages in Java.

Sicherheits-Einschränkungen

Plugins werden als weniger vertrauenswürdig behandelt als deine lokale Konfiguration. Deshalb gelten für Plugin-Subagents strenge Einschränkungen:

Keine hooks -- Plugin-Agents dürfen keine eigenen Hooks definieren
Keine mcpServers -- Plugin-Agents bekommen keinen direkten MCP-Zugriff
Kein permissionMode -- Plugin-Agents können ihre Berechtigungsstufe nicht selbst festlegen

Diese Felder werden in Agent-Definitionen innerhalb von Plugins schlicht ignoriert.

!Workaround bei Bedarf

Wenn du einem Plugin-Agent MCP-Zugriff oder Hooks geben musst, kopiere die Agent-Definition nach .claude/agents/ in dein Projekt. Dort gilt sie als lokale, vertrauenswürdige Konfiguration und alle Felder werden respektiert. Das ist eine bewusste Entscheidung -- du übernimmst damit die Verantwortung für die Sicherheit.

Plugins testen und laden

Während der Entwicklung lädst du dein Plugin lokal, ohne es zu installieren:

# Plugin aus lokalem Verzeichnis laden
claude --plugin-dir ./my-plugin

Dieser Befehl startet Claude Code und bindet das Plugin direkt aus dem angegebenen Verzeichnis ein. Änderungen am Plugin werden nach einem Reload wirksam:

/reload-plugins

*Entwicklungs-Workflow

Der typische Workflow beim Plugin-Entwickeln: Terminal 1 für Claude Code mit --plugin-dir, Terminal 2 für Änderungen am Plugin-Code. Nach jeder Änderung ein /reload-plugins im Claude-Code-Terminal -- und du siehst sofort das Ergebnis.

Plugin-Einstellungen

Die settings.json im Plugin-Root kann Standardeinstellungen definieren:

{
  "model": "opus-4",
  "permissions": {
    "allow": ["Read", "Grep", "Glob"],
    "deny": ["Bash"]
  }
}

Diese Einstellungen gelten als Vorschläge -- die lokale Projektkonfiguration hat immer Vorrang.

Zusammenfassung

Ein Plugin ist ein klar strukturiertes Paket mit Manifest, Skills, Agents, Hooks und MCP-Konfiguration. Namespace-Isolation verhindert Konflikte, und Sicherheits-Einschränkungen stellen sicher, dass Plugins keine unkontrollierten Berechtigungen erhalten. Im nächsten Abschnitt schauen wir uns an, wie MCP-Integration im Detail funktioniert.