marketplace-builder

Marketplace Builder

コマンド、エージェント、スキル、フック、MCP サーバーを配布するための、Claude Code マーケットプレイスとプラグインの作成に関する包括的なガイドです。

---

クイックリファレンス

マーケットプレイスとプラグインの違い

重要な概念：これらは同じものではありません。

概念	内容	たとえ
マーケットプレイス	プラグインの場所を一覧表示する JSON カタログ	図書館の目録
プラグイン	コンポーネントをまとめたパッケージ	本
コンポーネント	コマンド、エージェント、スキル、フック、MCP サーバー	章

関係：1 つのマーケットプレイス → 複数のプラグイン → プラグインごとに複数のコンポーネント

重要なポイント：マーケットプレイスはプラグインをホストしません。インデックスを作成します。プラグインはどこにでも配置できます（GitHub、GitLab、プライベート Git、ローカルパス）。

---

JSON スキーマのクイックリファレンス

最小限の marketplace.json：

{
  "name": "marketplace-name",
  "owner": {"name": "Owner Name"},
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./path-to-plugin",
      "description": "What this plugin does",
      "version": "1.0.0"
    }
  ]
}

最小限の plugin.json（.claude-plugin/ 内）：

{
  "name": "plugin-name",
  "description": "What this plugin does",
  "version": "1.0.0"
}

チームの settings.json（.claude/ 内）：

{
  "extraKnownMarketplaces": {
    "marketplace-name": {
      "source": {"source": "github", "repo": "owner/repo"}
    }
  },
  "enabledPlugins": {
    "plugin-name@marketplace-name": true
  }
}

---

ソースの種類

種類	構文	最適な用途
GitHub	{"source": "github", "repo": "owner/repo"}	公開プラグイン
Git URL	{"source": "git", "url": "https://..."}	プライベート/GitLab
ディレクトリ	{"source": "directory", "path": "./path"}	モノレポ
相対パス	"./path"	ディレクトリの省略形

---

コマンドリファレンス

# Add a marketplace
/plugin marketplace add owner/repo
/plugin marketplace add https://gitlab.com/org/repo.git
/plugin marketplace add ./local-marketplace

# List marketplaces
/plugin marketplace list

# Update marketplace catalog
/plugin marketplace update marketplace-name

# Browse and install plugins
/plugin                                    # Interactive browser
/plugin install plugin-name@marketplace    # Direct install

# Manage plugins
/plugin enable plugin@marketplace
/plugin disable plugin@marketplace
/plugin uninstall plugin@marketplace

# Validate structure
claude plugin validate .

---

6 フェーズのワークフロー

フェーズ 1：要件の収集

AskUserQuestion を使ってユーザーのニーズを把握します：

1. 何を配布しますか？

   • コマンド（スラッシュコマンド）
   • エージェント（サブエージェント）
   • スキル（モデルが呼び出す機能）
   • フック（イベントハンドラー）
   • MCP サーバー（外部ツール）
   • 上記の組み合わせ

2. プラグインはいくつですか？

   • 単一のプラグイン
   • 関連する複数のプラグイン
   • 大規模なプラグインコレクション

3. 対象ユーザーは誰ですか？

   • 個人利用（自分だけ）
   • チーム（Git 経由の同僚）
   • 組織（全社）
   • 公開コミュニティ

4. どこでホストしますか？

   • GitHub（公開または非公開）
   • GitLab またはその他の Git サービス
   • セルフホストの Git
   • ローカル開発のみ

次に進む前に、回答を記録してください。

---

フェーズ 2：アーキテクチャの決定

要件に基づいて、次のパターンのいずれかを推奨します：

パターン A：基本的なマーケットプレイス（単一プラグイン）

使用する場合：プラグインが 1 つで、配布がシンプルなとき

my-marketplace/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── commands/
└── agents/

パターン B：モノレポ（複数のプラグイン、1 つのリポジトリ）

使用する場合：関連するプラグイン、統一されたバージョン管理、チーム所有のとき

company-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── formatter/
│   │   ├── .claude-plugin/plugin.json
│   │   └── commands/
│   ├── linter/
│   │   ├── .claude-plugin/plugin.json
│   │   └── commands/
│   └── tester/
│       ├── .claude-plugin/plugin.json
│       └── agents/

パターン C：マルチリポジトリ（プラグインが別々のリポジトリにある）

使用する場合：独立したプラグイン、異なる所有者、コミュニティコレクションのとき

# Marketplace repo
my-marketplace/
└── .claude-plugin/
    └── marketplace.json  # Points to other repos

# Plugin repos (separate)
tool-a/
├── .claude-plugin/plugin.json
└── commands/

tool-b/
├── .claude-plugin/plugin.json
└── agents/

パターン D：エンタープライズ（プライベートと公開のハイブリッド）

使用する場合：内部ツールと外部ツールが混在し、厳格なアクセス制御が必要なとき

{
  "plugins": [
    {"name": "internal-tool", "source": {"source": "git", "url": "https://git.corp/..."}},
    {"name": "community-tool", "source": {"source": "github", "repo": "public/tool"}}
  ]
}

判断フロー：

• プラグインが 1 つ？ → パターン A
• 複数のプラグインで、同じチーム？ → パターン B
• 異なるソースのプラグイン？ → パターン C
• プライベートと公開が混在するエンタープライズ？ → パターン D

---

フェーズ 3：プラグインの作成

各プラグインについて、次の構造を作成します：

plugin-name/
├── .claude-plugin/
│   └── plugin.json         # Required: plugin manifest
├── commands/               # Optional: slash commands
│   └── my-command.md
├── agents/                 # Optional: subagents
│   └── my-agent.md
├── skills/                 # Optional: skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                  # Optional: event handlers
│   └── hooks.json
└── .mcp.json              # Optional: MCP servers

plugin.json を作成します：

{
  "name": "plugin-name",
  "description": "Clear description of what this plugin provides",
  "version": "1.0.0",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/owner/repo",
  "license": "MIT"
}

命名規則：

• プラグイン名：kebab-case（例：code-formatter）
• バージョン：セマンティックバージョニング MAJOR.MINOR.PATCH
• コマンド：verb-noun.md（例：format-code.md）
• エージェント：role-name.md（例：code-reviewer.md）

---

フェーズ 4：マーケットプレイスの作成

.claude-plugin/marketplace.json を作成します：

モノレポの場合（プラグインが同じリポジトリにある場合）：

{
  "name": "company-tools",
  "owner": {
    "name": "Company Name",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "Company development tools",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "formatter",
      "source": "./plugins/formatter",
      "description": "Code formatting tools",
      "version": "1.0.0"
    },
    {
      "name": "linter",
      "source": "./plugins/linter",
      "description": "Code linting tools",
      "version": "1.0.0"
    }
  ]
}

マルチリポジトリの場合（プラグインが別々のリポジトリにある場合）：

{
  "name": "community-collection",
  "owner": {
    "name": "Community",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "tool-a",
      "source": {
        "source": "github",
        "repo": "community/tool-a"
      },
      "description": "Tool A description",
      "version": "2.1.0"
    },
    {
      "name": "tool-b",
      "source": {
        "source": "github",
        "repo": "community/tool-b"
      },
      "description": "Tool B description",
      "version": "1.3.0"
    }
  ]
}

---

フェーズ 5：配布の設定

個人利用の場合

追加の設定は不要です。マーケットプレイスをローカルに追加します：

/plugin marketplace add ./path-to-marketplace

チームへの配布の場合

プロジェクトの .claude/settings.json に追加します：

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "formatter@team-tools": true,
    "linter@team-tools": true
  }
}

動作の仕組み：

1. チームメンバーがプロジェクトをクローンします
2. Claude Code が .claude/settings.json を読み取ります
3. 設定済みのマーケットプレイスを信頼するかどうかを確認するプロンプトが表示されます
4. 有効化されたプラグインをインストールするかどうかを確認するプロンプトが表示されます
5. 新しいチームメンバーには、適切な設定が自動的に適用されます

一般公開する場合

1. マーケットプレイスのリポジトリを GitHub にプッシュします

2. README にインストール方法を記載します：

   ## Installation
   
   Add the marketplace:
   ```bash
   /plugin marketplace add owner/repo
   

   プラグインをインストールします：

   /plugin install formatter@owner-tools
   

For Enterprise

1. Set up private git access (SSH keys or tokens)
2. Create internal marketplace with git URL sources
3. Configure .claude/settings.json in project templates
4. Document for IT/security review

---

Phase 6: Validation and Testing

Step 1: Validate JSON Syntax

# Validate marketplace structure
claude plugin validate .

# Manual JSON validation
python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"

ステップ 2：マーケットプレイスの追加をテストする

# Add marketplace locally
/plugin marketplace add ./path-to-marketplace

# Verify it appears
/plugin marketplace list

ステップ 3：プラグインのインストールをテストする

# Browse available plugins
/plugin

# Install a plugin
/plugin install plugin-name@marketplace-name

# Verify components work
/help  # Check commands appear

ステップ 4：チームでのフローをテストする（該当する場合）

1. settings.json を含むプロジェクトを新しい場所にクローンします
2. プロンプトが表示されたらフォルダーを信頼します
3. マーケットプレイスとプラグインが正しくインストールされることを確認します

ステップ 5：すべてのコンポーネントを確認する

• コマンド：/command-name を実行してテストします
• エージェント：/agents を確認するか、Task 経由で呼び出してみます
• スキル：トリガーとなる語句を使って起動します
• フック：イベントを発生させてテストします
• MCP サーバー：MCP ツールが利用可能か確認します

---

アーキテクチャパターン

モノレポパターン

構成：

company-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── plugin-a/
│   ├── plugin-b/
│   └── plugin-c/
└── README.md

メリット：

• 管理するリポジトリが 1 つで済みます
• バージョン管理を統一できます
• プラグイン間の変更が容易です
• CI/CD を簡素化できます

デメリット：

• すべてのプラグインでアクセス制御を共有します
• リポジトリのサイズが大きくなります
• 更新は一括で行われます

最適な用途：チーム向けツール、関連するプラグイン、所有権の一元管理

---

マルチリポジトリパターン

構成：

# Marketplace repo
tools-marketplace/
└── .claude-plugin/marketplace.json

# Separate plugin repos
plugin-a/   # github.com/org/plugin-a
plugin-b/   # github.com/org/plugin-b
plugin-c/   # github.com/org/plugin-c

メリット：

• バージョンを個別に管理できます
• アクセス制御を分けられます
• 所有権を分散できます
• リポジトリを小さく保てます

デメリット：

• 管理するリポジトリが増えます
• バージョンの調整が必要です
• CI/CD が複雑になります

最適な用途：コミュニティのコレクション、所有権が混在する環境、独立したプラグイン

---

ハイブリッドパターン

構成：

{
  "plugins": [
    {"name": "core", "source": "./plugins/core"},
    {"name": "community", "source": {"source": "github", "repo": "community/tool"}},
    {"name": "internal", "source": {"source": "git", "url": "https://git.corp/..."}}
  ]
}

メリット：

• ソースを柔軟に組み合わせられます
• コミュニティのプラグインを含められます
• プライベートとパブリックの両方に対応します

デメリット：

• メンテナンスが複雑になります
• 信頼レベルが混在します
• 更新サイクルが異なります

最適な用途：エンタープライズ、成熟したエコシステム、段階的な移行

---

よくある落とし穴

1. マーケットプレイスとプラグインを混同する

誤り：marketplace.json がプラグインそのものだと考える 正解：marketplace.json はプラグインを指し示します

marketplace.json はカタログです。実際のプラグインコードは、別のディレクトリまたはリポジトリにあります。

2. ソースタイプの誤り

誤り：プライベートリポジトリで GitHub の省略表記を使う

{"source": "github", "repo": "private-org/private-repo"}  // May fail

正解：プライベートリポジトリには git URL を使う

{"source": "git", "url": "[email protected]:private-org/private-repo.git"}

3. 必須フィールドの不足

marketplace.json の必須項目：

• name
• owner.name
• plugins 配列

plugin.json の必須項目：

• name
• description
• version

4. パスの誤り

誤り：間違ったディレクトリを基準にした相対パス

{"source": "../plugins/tool"}  // Relative to what?

正解：marketplace.json の場所を基準にしたパス

{"source": "./plugins/tool"}  // Relative to .claude-plugin/

5. バージョンの不一致

次のバージョンを同期させます：

• plugin.json のバージョン
• marketplace.json のプラグインエントリーのバージョン

プラグインを更新したら、両方のファイルを更新します。

6. 検証の忘れ

公開前に必ず実行します：

claude plugin validate .

7. 信頼モデルの誤解

ユーザーはマーケットプレイスを明示的に信頼する必要があります。チームメンバーにプラグインを強制インストールすることはできません。settings.json は事前設定を行うだけで、ユーザーは引き続き承認する必要があります。

---

このスキルを使う場面

marketplace-builder を使う場合：

• 新しいマーケットプレイスを作成するとき
• 配布用にプラグインを公開するとき
• チーム全体のプラグイン設定を行うとき
• ローカルのプラグインを配布可能なパッケージに変換するとき
• マーケットプレイスまたはプラグインの問題をトラブルシューティングするとき

使わない場合：

• 個別のコマンドを作成するとき（slash-command-builder を使います）
• 個別のエージェントを作成するとき（agent-builder を使います）
• 個別のスキルを作成するとき（skill-builder を使います）
• 既存のプラグインを使うだけの場合（/plugin コマンドを直接使います）

---

ファイルリファレンス

テンプレート

• templates/basic-marketplace.md - 単一プラグインのシンプルなセットアップ
• templates/plugin-structure.md - プラグイン作成の完全ガイド
• templates/multi-plugin.md - モノレポパターン
• templates/multi-repo.md - プラグインを分散するパターン
• templates/enterprise-marketplace.md - チーム設定を備えたエンタープライズ向け

例

• examples/development-tools.md - 6 つの開発ツールプラグイン
• examples/team-workflows.md - 6 つのチームワークフロープラグイン
• examples/specialized-domains.md - 6 つのドメイン特化型プラグイン

リファレンス

• reference/syntax-guide.md - JSON スキーマの完全ガイド
• reference/best-practices.md - 設計原則
• reference/troubleshooting.md - よくある問題とデバッグ