Erstellen und Verteilen eines Plugin-Marktplatzes

​

Übersicht

1. Plugins erstellen: Erstellen Sie ein oder mehrere Plugins mit Befehlen, 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).

​

Anleitung: Erstellen Sie einen lokalen Marktplatz

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

​

Marktplatzdatei erstellen

{
  "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 Metadaten

​

Plugin-Einträge

​

Erforderliche Felder

​

Optionale Plugin-Felder

​

Plugin-Quellen

​

Relative Pfade

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

​

GitHub-Repositories

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

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

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

​

Git-Unterverzeichnisse

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

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

​

npm-Pakete

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

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

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

​

Erweiterte Plugin-Einträge

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

• 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.

​

Strict Mode

• strict: true: Das Plugin hat seine eigene plugin.json und verwaltet seine eigenen Komponenten. Der Marktplatz-Eintrag kann zusätzliche Befehle 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 Befehle, 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)

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

​

Auf anderen Git-Services hosten

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

​

Private Repositories

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

Lokal vor der Verteilung testen

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

​

Marktplätze für Ihr Team erforderlich machen

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

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

​

Plugins für Container vorab ausfüllen

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

• 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.
• 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

​

Häufige Konfigurationen

{
  "strictKnownMarketplaces": []
}

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

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

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

​

Wie Einschränkungen funktionieren

• 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

​

Versionsauflösung und Release-Kanäle

​

Richten Sie Release-Kanäle ein

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

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

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

​

Validierung und Tests

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Fehlerbehebung

​

Marktplatz wird nicht geladen

• Ü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 und das Frontmatter wohlgeformt ist, indem Sie claude plugin validate oder /plugin validate verwenden
• Bestätigen Sie für private Repositories, dass Sie Zugriffsberechtigung haben

​

Marktplatz-Validierungsfehler

• Marketplace has no plugins defined: Fügen Sie mindestens ein Plugin zum plugins-Array hinzu
• No marketplace description provided: Fügen Sie metadata.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

• Ü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

​

Authentifizierung für private Repositories schlägt fehl

• Ü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

• 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

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Git-Operationen zeitüberschreitung

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 Minuten

​

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

• 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

​

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