Claude Code の Plugin Marketplace でスキルをオプトイン配布にする

Claude Code のスキルが数十個に増えてきたのですが、全員に一律で適用されるのがつらくなってきたので、Plugin Marketplace を使ってオプトイン配布に移行しました。

スキルが増えると何が起きるか

Claude Code のスキルは .claude/skills/ に配置すると、リポジトリを開いた全員に適用されます。数個なら問題ないのですが、数十個に増えてくるとスキルの description マッチングで意図しないスキルまで発火するようになってきました。QA 向けのスキルがバックエンドエンジニアの作業中に反応したり、フロントエンド向けのスキルがインフラの作業で発火したりといった具合です。

使わないスキルの description がコンテキストウィンドウに載り続けてトークンを消費するのも気になっていました。改めてスキルの棚卸しをしたところ、全員に必須と言えるものは半分以下で、残りは「あると便利だが、全員には要らない」ものでした。

Plugin と Marketplace

Claude Code には Plugin と Marketplace という2つのネイティブ機能があります。

Plugin は skills、hooks、agents をひとつのパッケージにまとめる仕組みです。Marketplace はその Plugin のカタログで、source の種類によって配布方法を選べます。

Marketplace の source は3種類あります。

directory はローカルディレクトリを指定する方法です。外部に公開する必要がなく、そのリポジトリ限定の Marketplace を作れます。リポジトリを clone するだけで使える状態になるので、社内のモノレポで使うなら一番手軽です。

github は GitHub リポジトリを owner/repo 形式で指定します。Marketplace を独立したリポジトリとして管理できるので、組織をまたいだ配布に向いています。

url は Git の URL を直接指定する方法で、GitLab やセルフホストの Git サーバーなど GitHub 以外のホスティングに対応できます。

今回は directory を採用しました。モノレポなので同じリポジトリを見ている人が多く、clone するだけで Marketplace が使える状態になります。

この仕組みで「チーム向け」「QA 向け」のようにロール別のスキルパックを作り、各自が必要なものだけインストールする運用が可能になります。

リポジトリ内に Marketplace を作る

.ai/marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-team/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── some-skill/
                └── SKILL.md

marketplace.json でカタログ全体を定義しています。

{
  "name": "my-org",
  "plugins": [
    {
      "name": "my-team",
      "source": "./plugins/my-team",
      "description": "チーム向けスキルパック",
      "version": "0.1.0",
      "strict": false
    }
  ]
}

社内向けであれば plugin.json は名前だけで十分です。strict: false を marketplace.json 側で指定しておけば、メタデータはカタログに一元管理されます。

{
  "name": "my-team"
}

あとはリポジトリの .claude/settings.json に Marketplace を登録しておきます。この設定がリポジトリに含まれているので、他のメンバーは pull するだけで Marketplace が利用可能になり、すぐに Plugin をインストールできる状態になります。

{
  "extraKnownMarketplaces": {
    "my-org": {
      "source": {
        "source": "directory",
        "path": "./.ai/marketplace"
      }
    }
  }
}

インストール

/plugin で一覧を確認して、必要なものをインストールします。

/plugin install my-team@my-org

不要になったらアンインストールするだけです。

/plugin uninstall my-team@my-org

Namespace の設計

Plugin 名がスキルの namespace になるため、ディレクトリ名に my-team- のような prefix を付ける必要はありません。

ただし、スキルを呼び出すときの補完候補には namespace を除いた名前が表示されます。既存スキルと名前が被ると区別しにくいので、SKILL.md の name フィールドで明示的に namespace を含めておくのがおすすめです。

# skills/prd-guide/SKILL.md
name: my-team:prd-guide

こうしておくと、補完時に my-team:prd-guide と表示され、どの Plugin のスキルか一目で分かります。

やってみての所感

まだ移行を始めたばかりなので、誤発火やコンテキスト汚染が実際に減ったかはまだ分かりません。ただ、「全員に適用されるのはちょっと……」と追加を迷っていたスキルを Plugin に気軽に足せるようになったのは良い変化でした。

ちなみに、Claude Code 以外の Agent を使う人のために、1つのソースから各 Agent 向けの設定を自動生成する仕組みを作っていました。Marketplace は Claude Code 特有の機能なので、ここだけポータビリティが落ちているのが気になっています。

どうやら Codex にも最近入った同様の Plugin Marketplace の仕組みがあり、1つのソースから両方のプラグインを生成できるようにしたいなと企んでいます。

newmo 技術ブログ

技術で地域をカラフルに