Erstellen und Verteilen eines Plugin-Marktplatzes

Erstellen und hosten Sie Plugin-Marktplätze, um Claude Code-Erweiterungen in Teams und Communities zu verteilen.

Ein Plugin-Marktplatz ist ein Katalog, mit dem Sie Plugins an andere verteilen können. Marktplätze bieten zentrale Entdeckung, Versionsverfolgung, automatische Updates und Unterstützung für mehrere Quellentypen (Git-Repositories, lokale Pfade und mehr). Diese Anleitung zeigt Ihnen, wie Sie Ihren eigenen Marktplatz erstellen, um Plugins mit Ihrem Team oder Ihrer Community zu teilen.

Möchten Sie Plugins aus einem vorhandenen Marktplatz installieren? Siehe Entdecken und Installieren vorgefertigter Plugins.

Übersicht

Das Erstellen und Verteilen eines Marktplatzes umfasst:

1. Plugins erstellen: Erstellen Sie ein oder mehrere Plugins mit skills, Agents, hooks, MCP servers oder LSP servers. Diese Anleitung setzt voraus, dass Sie bereits Plugins zum Verteilen haben; siehe Plugins erstellen für Details zum Erstellen von Plugins.
2. Marktplatzdatei erstellen: Definieren Sie eine marketplace.json, die Ihre Plugins und deren Speicherorte auflistet (siehe Marktplatzdatei erstellen).
3. Marktplatz hosten: Pushen Sie zu GitHub, GitLab oder einem anderen Git-Host (siehe Marktplätze hosten und verteilen).
4. Mit Benutzern teilen: Benutzer fügen Ihren Marktplatz mit /plugin marketplace add hinzu und installieren einzelne Plugins (siehe Plugins entdecken und installieren).

Sobald Ihr Marktplatz live ist, können Sie ihn aktualisieren, indem Sie Änderungen in Ihr Repository pushen. Benutzer aktualisieren ihre lokale Kopie mit /plugin marketplace update.

Anleitung: Erstellen Sie einen lokalen Marktplatz

Dieses Beispiel erstellt einen Marktplatz mit einem Plugin: ein quality-review skill für Code-Reviews. Sie erstellen die Verzeichnisstruktur, fügen ein skill hinzu, erstellen das Plugin-Manifest und den Marktplatzkatalog und installieren und testen ihn dann.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0"
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

Um mehr über die Möglichkeiten von Plugins zu erfahren, einschließlich hooks, Agents, MCP servers und LSP servers, siehe Plugins.

Marktplatzdatei erstellen

Erstellen Sie .claude-plugin/marketplace.json im Stammverzeichnis Ihres Repositories. Diese Datei definiert den Namen Ihres Marktplatzes, Eigentümerinformationen und eine Liste von Plugins mit ihren Quellen.

Jeder Plugin-Eintrag benötigt mindestens einen name und eine source (wo man ihn abrufen kann). Siehe das vollständige Schema unten für alle verfügbaren Felder.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marktplatz-Schema

Erforderliche Felder

Eigentümer-Felder

Optionale Felder

description und version werden auch unter metadata für Rückwärtskompatibilität akzeptiert.

Plugin-Einträge

Jeder Plugin-Eintrag im plugins-Array beschreibt ein Plugin und wo man es findet. Sie können jedes Feld aus dem Plugin-Manifest-Schema einbeziehen (wie description, version, author, commands, hooks usw.), plus diese Marktplatz-spezifischen Felder: source, category, tags und strict.

Erforderliche Felder

Optionale Plugin-Felder

Standard-Metadatenfelder:

Komponenten-Konfigurationsfelder:

Plugin-Quellen

Plugin-Quellen teilen Claude Code mit, wo jedes einzelne Plugin in Ihrem Marktplatz abgerufen werden soll. Diese werden im source-Feld jedes Plugin-Eintrags in marketplace.json festgelegt.

Sobald ein Plugin geklont oder auf den lokalen Computer kopiert wird, wird es in den lokalen versionierten Plugin-Cache unter ~/.claude/plugins/cache kopiert.

Die Git-basierten Quellentypen unten sind github, url und git-subdir. Wenn sowohl ref als auch sha auf einem von ihnen gesetzt sind, ist sha die effektive Anheftung. Claude Code ruft den angehefteten Commit direkt ab und checkt ihn aus, sodass die Installation erfolgreich ist, auch wenn der Branch oder Tag, der durch ref benannt wird, inzwischen upstream gelöscht wurde, solange der Commit noch vom Repository aus erreichbar ist.

Relative Pfade

Für Plugins im selben Repository verwenden Sie einen Pfad, der mit ./ beginnt:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Pfade werden relativ zum Marktplatz-Root aufgelöst, das ist das Verzeichnis, das .claude-plugin/ enthält. Im obigen Beispiel verweist ./plugins/my-plugin auf <repo>/plugins/my-plugin, obwohl marketplace.json unter <repo>/.claude-plugin/marketplace.json lebt. Verwenden Sie nicht ../, um Pfade außerhalb des Marktplatz-Root zu referenzieren.

GitHub-Repositories

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Sie können an einen bestimmten Branch, Tag oder Commit anheften:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git-Repositories

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Sie können an einen bestimmten Branch, Tag oder Commit anheften:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git-Unterverzeichnisse

Verwenden Sie git-subdir, um auf ein Plugin zu verweisen, das sich in einem Unterverzeichnis eines Git-Repositories befindet. Claude Code verwendet einen sparsamen, teilweisen Klon, um nur das Unterverzeichnis abzurufen und die Bandbreite für große Monorepos zu minimieren.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Sie können an einen bestimmten Branch, Tag oder Commit anheften:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Das url-Feld akzeptiert auch eine GitHub-Kurzform (owner/repo) oder SSH-URLs (git@github.com:owner/repo.git).

npm-Pakete

Plugins, die als npm-Pakete verteilt werden, werden mit npm install installiert. Dies funktioniert mit jedem Paket in der öffentlichen npm-Registry oder einer privaten Registry, die Ihr Team hostet.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Um an eine bestimmte Version anzuheften, fügen Sie das version-Feld hinzu:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Um von einer privaten oder internen Registry zu installieren, fügen Sie das registry-Feld hinzu:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Erweiterte Plugin-Einträge

Dieses Beispiel zeigt einen Plugin-Eintrag mit vielen optionalen Feldern, einschließlich benutzerdefinierter Pfade für Befehle, Agents, hooks und MCP-Server:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Wichtige Dinge zu beachten:

• commands und agents: Sie können mehrere Verzeichnisse oder einzelne Dateien angeben. Pfade sind relativ zum Plugin-Root.
• ${CLAUDE_PLUGIN_ROOT}: Verwenden Sie diese Variable in hooks und MCP-Server-Konfigurationen, um auf Dateien im Installationsverzeichnis des Plugins zu verweisen. Dies ist notwendig, da Plugins beim Installieren an einen Cache-Speicherort kopiert werden. Verwenden Sie für Abhängigkeiten oder Status, die Plugin-Updates überstehen sollten, stattdessen ${CLAUDE_PLUGIN_DATA}.
• strict: false: Da dies auf false gesetzt ist, benötigt das Plugin keine eigene plugin.json. Der Marktplatz-Eintrag definiert alles. Siehe Strict Mode unten.

Standardmäßig werden die Skills eines Plugins aus dem skills/-Verzeichnis unter seiner source geladen, und alle unter skills aufgelisteten Pfade werden zu diesem Scan hinzugefügt. Die Ausnahme ist eine Marktplatz-Root-Quelle wie source: "./", bei der mehrere Plugin-Einträge einen skills/-Ordner gemeinsam nutzen. In diesem Fall macht das Auflisten bestimmter Unterverzeichnisse unter skills diese Liste zur vollständigen Menge für den Eintrag, und andere Verzeichnisse unter skills/ werden nicht geladen. Das Auflisten des skills/-Verzeichnisses selbst oder des Plugin-Root behält den vollständigen Scan bei. Wenn keiner der aufgelisteten Pfade existiert, wird stattdessen der Standard-Scan ausgeführt.

Strict Mode

Das strict-Feld steuert, ob plugin.json die Autorität für Komponentendefinitionen ist (skills, Agents, hooks, MCP-Server, Ausgabestile).

Wann jeder Modus verwendet werden sollte:

• strict: true: Das Plugin hat seine eigene plugin.json und verwaltet seine eigenen Komponenten. Der Marktplatz-Eintrag kann zusätzliche skills oder hooks hinzufügen. Dies ist der Standard und funktioniert für die meisten Plugins.
• strict: false: Der Marktplatz-Betreiber möchte vollständige Kontrolle. Das Plugin-Repo stellt Rohdateien bereit, und der Marktplatz-Eintrag definiert, welche dieser Dateien als skills, Agents, hooks usw. verfügbar gemacht werden. Nützlich, wenn der Marktplatz die Komponenten eines Plugins anders strukturiert oder kuratiert als vom Plugin-Autor beabsichtigt.

Marktplätze hosten und verteilen

Auf GitHub hosten (empfohlen)

GitHub bietet die einfachste Verteilungsmethode:

1. Repository erstellen: Richten Sie ein neues Repository für Ihren Marktplatz ein
2. Marktplatzdatei hinzufügen: Erstellen Sie .claude-plugin/marketplace.json mit Ihren Plugin-Definitionen
3. Mit Teams teilen: Benutzer fügen Ihren Marktplatz mit /plugin marketplace add owner/repo hinzu

Vorteile: Integrierte Versionskontrolle, Issue-Tracking und Team-Zusammenarbeitsfunktionen.

Auf anderen Git-Services hosten

Jeder Git-Hosting-Service funktioniert, wie GitLab, Bitbucket und selbstgehostete Server. Benutzer fügen mit der vollständigen Repository-URL hinzu:

/plugin marketplace add https://gitlab.com/company/plugins.git

Private Repositories

Claude Code unterstützt die Installation von Plugins aus privaten Repositories. Für manuelle Installation und Updates verwendet Claude Code Ihre vorhandenen Git-Credential-Helper, daher funktioniert HTTPS-Zugriff über gh auth login, macOS Keychain oder git-credential-store genauso wie in Ihrem Terminal. SSH-Zugriff funktioniert, solange der Host bereits in Ihrer known_hosts-Datei vorhanden ist und der Schlüssel in ssh-agent geladen ist, da Claude Code interaktive SSH-Eingabeaufforderungen für den Host-Fingerprint und die Schlüsselpassphrase unterdrückt.

Hintergrund-Auto-Updates werden beim Start ohne Credential-Helper ausgeführt, da interaktive Eingabeaufforderungen Claude Code am Start hindern würden. Um Auto-Updates für private Marktplätze zu aktivieren, legen Sie das entsprechende Authentifizierungstoken in Ihrer Umgebung fest:

Legen Sie das Token in Ihrer Shell-Konfiguration fest (z. B. .bashrc, .zshrc) oder übergeben Sie es beim Ausführen von Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Lokal vor der Verteilung testen

Testen Sie Ihren Marktplatz lokal, bevor Sie ihn teilen:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

Für die vollständige Palette von Add-Befehlen (GitHub, Git-URLs, lokale Pfade, Remote-URLs) siehe Marktplätze hinzufügen.

Marktplätze für Ihr Team erforderlich machen

Sie können Ihr Repository so konfigurieren, dass Teammitglieder automatisch aufgefordert werden, Ihren Marktplatz zu installieren, wenn sie dem Projektordner vertrauen. Fügen Sie Ihren Marktplatz zu .claude/settings.json hinzu:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Sie können auch angeben, welche Plugins standardmäßig aktiviert sein sollen:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Für vollständige Konfigurationsoptionen siehe Plugin-Einstellungen.

Plugins für Container vorab ausfüllen

Für Container-Images und CI-Umgebungen können Sie ein Plugins-Verzeichnis zur Build-Zeit vorab ausfüllen, damit Claude Code mit bereits verfügbaren Marktplätzen und Plugins startet, ohne zur Laufzeit etwas zu klonen. Legen Sie die Umgebungsvariable CLAUDE_CODE_PLUGIN_SEED_DIR fest, um auf dieses Verzeichnis zu verweisen.

Um mehrere Seed-Verzeichnisse zu schichten, trennen Sie Pfade mit : auf Unix oder ; auf Windows. Claude Code durchsucht jedes Verzeichnis in der Reihenfolge, und der erste Seed, der einen bestimmten Marktplatz oder Plugin-Cache enthält, gewinnt.

Das Seed-Verzeichnis spiegelt die Struktur von ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Um ein Seed-Verzeichnis zu erstellen, führen Sie Claude Code einmal während des Image-Builds aus, installieren Sie die benötigten Plugins, kopieren Sie dann das resultierende ~/.claude/plugins-Verzeichnis in Ihr Image und verweisen Sie CLAUDE_CODE_PLUGIN_SEED_DIR darauf.

Um den Kopierungsschritt zu überspringen, legen Sie CLAUDE_CODE_PLUGIN_CACHE_DIR während des Builds auf Ihren Ziel-Seed-Pfad fest, damit Plugins direkt dort installiert werden:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Legen Sie dann CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed in der Laufzeitumgebung Ihres Containers fest, damit Claude Code beim Start aus dem Seed liest.

Beim Start registriert Claude Code Marktplätze, die in der Seed-Datei known_marketplaces.json gefunden werden, in der primären Konfiguration und verwendet Plugin-Caches, die unter cache/ gefunden werden, ohne erneut zu klonen. Dies funktioniert sowohl im interaktiven Modus als auch im nicht-interaktiven Modus mit dem -p-Flag.

Verhaltensdetails:

• Schreibgeschützt: Das Seed-Verzeichnis wird nie geschrieben. Auto-Updates sind für Seed-Marktplätze deaktiviert, da git pull auf einem schreibgeschützten Dateisystem fehlschlagen würde.
• Seed-Einträge haben Vorrang: Marktplätze, die in der Seed deklariert sind, überschreiben alle übereinstimmenden Einträge in der Benutzerkonfiguration bei jedem Start. Um sich von einem Seed-Plugin abzumelden, verwenden Sie /plugin disable, anstatt den Marktplatz zu entfernen.
• Pfadauflösung: Claude Code lokalisiert Marktplatz-Inhalte, indem es $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ zur Laufzeit durchsucht, nicht indem es Pfaden vertraut, die in der Seed-JSON gespeichert sind. Dies bedeutet, dass die Seed korrekt funktioniert, auch wenn sie an einem anderen Pfad als dort, wo sie erstellt wurde, bereitgestellt wird.
• Mutation ist blockiert: Das Ausführen von /plugin marketplace remove oder /plugin marketplace update gegen einen Seed-verwalteten Marktplatz schlägt mit Anleitung fehl, um Ihren Administrator zu bitten, das Seed-Image zu aktualisieren.
• Komponiert mit Einstellungen: Wenn extraKnownMarketplaces oder enabledPlugins einen Marktplatz deklarieren, der bereits in der Seed vorhanden ist, verwendet Claude Code die Seed-Kopie, anstatt zu klonen.

Verwaltete Marktplatz-Einschränkungen

Für Organisationen, die strikte Kontrolle über Plugin-Quellen benötigen, können Administratoren einschränken, welche Plugin-Marktplätze Benutzer hinzufügen dürfen, indem sie die Einstellung strictKnownMarketplaces in verwalteten Einstellungen verwenden.

Wenn strictKnownMarketplaces in verwalteten Einstellungen konfiguriert ist, hängt das Einschränkungsverhalten vom Wert ab:

Häufige Konfigurationen

Deaktivieren Sie alle Marktplatz-Ergänzungen:

{
  "strictKnownMarketplaces": []
}

Nur bestimmte Marktplätze zulassen:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Alle Marktplätze von einem internen Git-Server mit Regex-Musterabgleich auf dem Host zulassen. Dies ist der empfohlene Ansatz für GitHub Enterprise Server oder selbstgehostete GitLab-Instanzen:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Dateisystem-basierte Marktplätze aus einem bestimmten Verzeichnis mit Regex-Musterabgleich auf dem Pfad zulassen:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Verwenden Sie ".*" als pathPattern, um jeden Dateisystempfad zuzulassen und gleichzeitig Netzwerkquellen mit hostPattern zu steuern.

Wie Einschränkungen funktionieren

Einschränkungen werden überprüft, bevor Netzwerk- oder Dateisystemoperationen durchgeführt werden. Die Überprüfung wird beim Hinzufügen von Marktplätzen und beim Installieren, Aktualisieren, Aktualisieren und Auto-Update von Plugins durchgeführt. Wenn ein Marktplatz hinzugefügt wurde, bevor die Richtlinie konfiguriert wurde, und seine Quelle nicht mehr mit der Zulassungsliste übereinstimmt, weigert sich Claude Code, Plugins daraus zu installieren oder zu aktualisieren. Die gleiche Durchsetzung gilt für blockedMarketplaces.

Die Zulassungsliste verwendet exakten Abgleich für die meisten Quellentypen. Damit ein Marktplatz zulässig ist, müssen alle angegebenen Felder genau übereinstimmen:

• Für GitHub-Quellen: repo ist erforderlich, und ref oder path müssen auch übereinstimmen, wenn sie in der Zulassungsliste angegeben sind
• Für URL-Quellen: Die vollständige URL muss genau übereinstimmen
• Für hostPattern-Quellen: Der Marktplatz-Host wird gegen das Regex-Muster abgeglichen
• Für pathPattern-Quellen: Der Dateisystempfad des Marktplatzes wird gegen das Regex-Muster abgeglichen

Exakter Abgleich normalisiert URLs nicht: Ein nachgestellter Schrägstrich, .git-Suffix oder ssh:// versus https://-Form werden als unterschiedliche Werte behandelt. Wenn Ihr Organisations-Marktplatz durch mehr als eine URL-Form geklont werden kann, bevorzugen Sie einen hostPattern-Eintrag gegenüber einer literalen URL, damit alle Formen übereinstimmen.

Da strictKnownMarketplaces in verwalteten Einstellungen festgelegt ist, können einzelne Benutzer und Projektkonfigurationen diese Einschränkungen nicht überschreiben.

Für vollständige Konfigurationsdetails einschließlich aller unterstützten Quellentypen und Vergleich mit extraKnownMarketplaces siehe die strictKnownMarketplaces-Referenz.

Versionsauflösung und Release-Kanäle

Plugin-Versionen bestimmen Cache-Pfade und Update-Erkennung: Wenn die aufgelöste Version mit dem übereinstimmt, was ein Benutzer bereits hat, überspringen /plugin update und Auto-Update das Plugin.

Claude Code löst die Version eines Plugins aus dem ersten dieser Punkte auf, der festgelegt ist:

1. version in der plugin.json des Plugins
2. version im Marktplatz-Eintrag des Plugins
3. Der Git-Commit-SHA der Plugin-Quelle

Für die Git-basierten Quellentypen github, url, git-subdir und relative Pfade innerhalb eines Git-gehosteten Marktplatzes können Sie version ganz weglassen und jeder neue Commit wird als neue Version behandelt. Dies ist die einfachste Einrichtung für interne oder aktiv entwickelte Plugins.

Richten Sie Release-Kanäle ein

Um "stabile" und "neueste" Release-Kanäle für Ihre Plugins zu unterstützen, können Sie zwei Marktplätze einrichten, die auf verschiedene Refs oder SHAs desselben Repos verweisen. Sie können dann die beiden Marktplätze verschiedenen Benutzergruppen über verwaltete Einstellungen zuweisen.

Beispiel

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Kanäle Benutzergruppen zuweisen

Weisen Sie jeden Marktplatz der entsprechenden Benutzergruppe über verwaltete Einstellungen zu. Beispielsweise erhält die stabile Gruppe:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

Die Early-Access-Gruppe erhält stattdessen latest-tools:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Abhängigkeitsversionen anheften

Ein Plugin kann seine Abhängigkeiten auf einen Semver-Bereich beschränken, damit Updates einer Abhängigkeit das abhängige Plugin nicht unterbrechen. Siehe Plugin-Abhängigkeitsversionen einschränken für die {plugin-name}--v{version} Git-Tag-Konvention, Bereichssyntax und wie mehrere Einschränkungen auf die gleiche Abhängigkeit kombiniert werden.

Validierung und Tests

Testen Sie Ihren Marktplatz vor dem Teilen.

Validieren Sie Ihre Marktplatz-JSON-Syntax:

claude plugin validate .

Oder von innerhalb von Claude Code:

/plugin validate .

Fügen Sie den Marktplatz zum Testen hinzu:

/plugin marketplace add ./path/to/marketplace

Installieren Sie ein Test-Plugin, um zu überprüfen, ob alles funktioniert:

/plugin install test-plugin@marketplace-name

Für vollständige Plugin-Test-Workflows siehe Testen Sie Ihre Plugins lokal. Für technische Fehlerbehebung siehe Plugins-Referenz.

Verwalten Sie Marktplätze über die CLI

Claude Code bietet nicht-interaktive claude plugin marketplace Unterbefehle zum Scripting und zur Automatisierung. Diese entsprechen den /plugin marketplace Befehlen, die in einer interaktiven Sitzung verfügbar sind.

Plugin marketplace add

Fügen Sie einen Marktplatz aus einem GitHub-Repository, einer Git-URL, einer Remote-URL oder einem lokalen Pfad hinzu.

claude plugin marketplace add <source> [options]

Argumente:

• <source>: GitHub owner/repo Kurzform, Git-URL, Remote-URL zu einer marketplace.json-Datei oder lokaler Verzeichnispfad. Um an einen Branch oder Tag anzuheften, fügen Sie @ref zur GitHub-Kurzform oder #ref zu einer Git-URL hinzu

Optionen:

Fügen Sie einen Marktplatz aus GitHub mit owner/repo Kurzform hinzu:

claude plugin marketplace add acme-corp/claude-plugins

Heften Sie an einen bestimmten Branch oder Tag mit @ref an:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Fügen Sie von einer Git-URL auf einem nicht-GitHub-Host hinzu:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Fügen Sie von einer Remote-URL hinzu, die die marketplace.json-Datei direkt bereitstellt:

claude plugin marketplace add https://example.com/marketplace.json

Fügen Sie von einem lokalen Verzeichnis zum Testen hinzu:

claude plugin marketplace add ./my-marketplace

Deklarieren Sie den Marktplatz im Projektbereich, damit er mit Ihrem Team über .claude/settings.json geteilt wird:

claude plugin marketplace add acme-corp/claude-plugins --scope project

Für ein Monorepo begrenzen Sie den Checkout auf die Verzeichnisse, die Plugin-Inhalte enthalten:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

Listet alle konfigurierten Marktplätze auf.

claude plugin marketplace list [options]

Optionen:

Mit --json enthält jeder Eintrag name, source und quellenspezifische Felder: repo für GitHub-Quellen, url für Git- und URL-Quellen und path für lokale Quellen. GitHub- und Git-Quellen enthalten auch ein ref-Feld, wenn der Marktplatz mit einem angehefteten Branch oder Tag hinzugefügt wurde.

Plugin marketplace remove

Entfernen Sie einen konfigurierten Marktplatz. Der Alias rm wird auch akzeptiert.

claude plugin marketplace remove <name> [options]

Argumente:

• <name>: Marktplatz-Name zum Entfernen, wie von claude plugin marketplace list angezeigt. Dies ist der name aus marketplace.json, nicht die Quelle, die Sie an add übergeben haben

Optionen:

Plugin marketplace update

Aktualisieren Sie Marktplätze von ihren Quellen, um neue Plugins und Versionsänderungen abzurufen.

claude plugin marketplace update [name]

Argumente:

• [name]: Marktplatz-Name zum Aktualisieren, wie von claude plugin marketplace list angezeigt. Aktualisiert alle Marktplätze, wenn weggelassen

Sowohl remove als auch update schlagen fehl, wenn sie gegen einen Seed-verwalteten Marktplatz ausgeführt werden, der schreibgeschützt ist. Beim Aktualisieren aller Marktplätze werden Seed-verwaltete Einträge übersprungen und andere Marktplätze werden weiterhin aktualisiert. Um Seed-bereitgestellte Plugins zu ändern, bitten Sie Ihren Administrator, das Seed-Image zu aktualisieren. Siehe Plugins für Container vorab ausfüllen.

Fehlerbehebung

Marktplatz wird nicht geladen

Symptome: Kann Marktplatz nicht hinzufügen oder Plugins von ihm nicht sehen

Lösungen:

• Überprüfen Sie, dass die Marktplatz-URL erreichbar ist
• Überprüfen Sie, dass .claude-plugin/marketplace.json im angegebenen Pfad vorhanden ist
• Stellen Sie sicher, dass die JSON-Syntax gültig ist, indem Sie claude plugin validate oder /plugin validate verwenden. Um Skill-, Agent- und Befehl-Frontmatter zu überprüfen, führen Sie den Befehl für jedes Plugin-Verzeichnis aus
• Bestätigen Sie für private Repositories, dass Sie Zugriffsberechtigung haben

Marktplatz-Validierungsfehler

Führen Sie claude plugin validate . oder /plugin validate . aus Ihrem Marktplatz-Verzeichnis aus, um auf Probleme zu überprüfen. Wenn der Validator auf ein Marktplatz-Verzeichnis verweist, überprüft er nur marketplace.json: Schema, doppelte Plugin-Namen, Quellpfad-Traversal und Versionskonflikte gegen jede referenzierte plugin.json.

Um die plugin.json eines einzelnen Plugins und seine Skill-, Agent-, Befehl- und Hook-Dateien zu validieren, führen Sie den Befehl für das Plugin-Verzeichnis selbst aus, zum Beispiel claude plugin validate ./plugins/my-plugin. Häufige Fehler:

Warnungen (nicht blockierend):

• Marketplace has no plugins defined: Fügen Sie mindestens ein Plugin zum plugins-Array hinzu
• No marketplace description provided: Fügen Sie eine Top-Level-description hinzu, um Benutzern zu helfen, Ihren Marktplatz zu verstehen
• Plugin name "x" is not kebab-case: Der Plugin-Name enthält Großbuchstaben, Leerzeichen oder Sonderzeichen. Benennen Sie in Kleinbuchstaben, Ziffern und Bindestriche um (z. B. my-plugin). Claude Code akzeptiert andere Formen, aber die Claude.ai-Marktplatz-Synchronisierung lehnt sie ab.

Plugin-Installationsfehler

Symptome: Marktplatz wird angezeigt, aber Plugin-Installation schlägt fehl

Lösungen:

• Überprüfen Sie, dass Plugin-Quell-URLs erreichbar sind
• Überprüfen Sie, dass Plugin-Verzeichnisse erforderliche Dateien enthalten
• Überprüfen Sie für GitHub-Quellen, dass Repositories öffentlich sind oder Sie Zugriff haben
• Testen Sie Plugin-Quellen manuell durch Klonen/Herunterladen
• Wenn die Quelle sowohl ref als auch sha festlegt, blockiert ein gelöschter Upstream-Branch oder Tag die Installation nicht. Wenn die Installation immer noch fehlschlägt, bestätigen Sie, dass der festgelegte Commit immer noch im Repository vorhanden ist

Authentifizierung für private Repositories schlägt fehl

Symptome: Authentifizierungsfehler beim Installieren von Plugins aus privaten Repositories

Lösungen:

Für manuelle Installation und Updates:

• Überprüfen Sie, dass Sie bei Ihrem Git-Anbieter authentifiziert sind (führen Sie z. B. gh auth status für GitHub aus)
• Überprüfen Sie, dass Ihr Credential-Helper korrekt konfiguriert ist: git config --global credential.helper
• Versuchen Sie, das Repository manuell zu klonen, um zu überprüfen, dass Ihre Anmeldedaten funktionieren

Für Hintergrund-Auto-Updates:

• Legen Sie das entsprechende Token in Ihrer Umgebung fest: echo $GITHUB_TOKEN
• Überprüfen Sie, dass das Token die erforderlichen Berechtigungen hat (Lesezugriff auf das Repository)
• Überprüfen Sie für GitHub, dass das Token den repo-Scope für private Repositories hat
• Überprüfen Sie für GitLab, dass das Token mindestens den read_repository-Scope hat
• Überprüfen Sie, dass das Token nicht abgelaufen ist

Marktplatz-Updates schlagen in Offline-Umgebungen fehl

Symptome: Marktplatz git pull schlägt fehl und Claude Code löscht den vorhandenen Cache, wodurch Plugins nicht mehr verfügbar werden.

Ursache: Standardmäßig entfernt Claude Code den veralteten Klon und versucht erneut zu klonen, wenn ein git pull fehlschlägt. In Offline- oder Airgapped-Umgebungen schlägt das erneute Klonen auf die gleiche Weise fehl, wodurch das Marktplatz-Verzeichnis leer bleibt.

Lösung: Legen Sie CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 fest, um den vorhandenen Cache beizubehalten, wenn der Pull fehlschlägt, anstatt ihn zu löschen:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Mit dieser Variable gesetzt behält Claude Code den veralteten Marktplatz-Klon bei git pull-Fehler bei und verwendet weiterhin den letzten bekannten guten Status. Verwenden Sie für vollständig Offline-Bereitstellungen, bei denen das Repository nie erreichbar sein wird, stattdessen CLAUDE_CODE_PLUGIN_SEED_DIR, um das Plugins-Verzeichnis zur Build-Zeit vorab auszufüllen.

Git-Operationen zeitüberschreitung

Symptome: Plugin-Installation oder Marktplatz-Updates schlagen mit einem Timeout-Fehler fehl, wie "Git clone timed out after 120s" oder "Git pull timed out after 120s".

Ursache: Claude Code verwendet ein 120-Sekunden-Timeout für alle Git-Operationen, einschließlich Klonen von Plugin-Repositories und Abrufen von Marktplatz-Updates. Große Repositories oder langsame Netzwerkverbindungen können dieses Limit überschreiten.

Lösung: Erhöhen Sie das Timeout mit der Umgebungsvariable CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. Der Wert ist in Millisekunden:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 Minuten

Plugins mit relativen Pfaden schlagen in URL-basierten Marktplätzen fehl

Symptome: Einen Marktplatz über URL hinzugefügt (z. B. https://example.com/marketplace.json), aber Plugins mit relativen Pfadquellen wie "./plugins/my-plugin" schlagen mit "path not found"-Fehlern fehl.

Ursache: URL-basierte Marktplätze laden nur die marketplace.json-Datei selbst herunter. Sie laden keine Plugin-Dateien vom Server herunter. Relative Pfade im Marktplatz-Eintrag verweisen auf Dateien auf dem Remote-Server, die nicht heruntergeladen wurden.

Lösungen:

• Verwenden Sie externe Quellen: Ändern Sie Plugin-Einträge, um stattdessen GitHub-, npm- oder Git-URL-Quellen zu verwenden:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Verwenden Sie einen Git-basierten Marktplatz: Hosten Sie Ihren Marktplatz in einem Git-Repository und fügen Sie ihn mit der Git-URL hinzu. Git-basierte Marktplätze klonen das gesamte Repository, wodurch relative Pfade funktionieren.

Dateien nicht gefunden nach Installation

Symptome: Plugin wird installiert, aber Verweise auf Dateien schlagen fehl, besonders Dateien außerhalb des Plugin-Verzeichnisses

Ursache: Plugins werden in ein Cache-Verzeichnis kopiert, anstatt an Ort und Stelle verwendet zu werden. Pfade, die auf Dateien außerhalb des Plugin-Verzeichnisses verweisen (wie ../shared-utils), funktionieren nicht, da diese Dateien nicht kopiert werden.

Lösungen: Siehe Plugin-Caching und Dateiauflösung für Workarounds, einschließlich Symlinks und Verzeichnisumstrukturierung.

Für zusätzliche Debugging-Tools und häufige Probleme siehe Debugging- und Entwicklungstools.

Siehe auch

• Entdecken und Installieren vorgefertigter Plugins - Installieren von Plugins aus vorhandenen Marktplätzen
• Plugins - Erstellen Ihrer eigenen Plugins
• Plugins-Referenz - Vollständige technische Spezifikationen und Schemas
• Plugin-Einstellungen - Plugin-Konfigurationsoptionen
• strictKnownMarketplaces-Referenz - Verwaltete Marktplatz-Einschränkungen