Create plugins

概要

skill / agent / hook / MCP サーバーなどをまとめて配布できる拡張の仕組み。プロジェクトやチームをまたいで共有する場合に使う。単発の個人用カスタマイズは .claude/ の standalone 構成で足りる。

仕様

standalone 構成との違い

方式	skill 名	向いている用途
Standalone（`.claude/` ディレクトリ）	`/hello`	個人のワークフロー、プロジェクト固有のカスタマイズ、素早い実験
Plugins（skill / agent / hook、または `.claude-plugin/plugin.json` マニフェストを持つ自己完結ディレクトリ）	`/plugin-name:hello`	チームでの共有、コミュニティへの配布、バージョン付きリリース、プロジェクト横断の再利用

plugin の skill は常に名前空間付き（/plugin-name:skill-name）で、複数 plugin の同名 skill の衝突を防ぐ
名前空間の接頭辞は plugin.json の name フィールドで変える

ディレクトリ構成

ディレクトリ	位置	用途
`.claude-plugin/`	plugin root	`plugin.json` マニフェストを置く（コンポーネントが既定位置を使うなら省略可）
`skills/`	plugin root	`<name>/SKILL.md` 形式の skill
`commands/`	plugin root	フラットな Markdown ファイル形式の skill。新規 plugin では `skills/` を使う
`agents/`	plugin root	カスタム agent 定義
`hooks/`	plugin root	`hooks.json` のイベントハンドラ
`.mcp.json`	plugin root	MCP サーバー設定
`.lsp.json`	plugin root	code intelligence 用の LSP サーバー設定
`monitors/`	plugin root	`monitors.json` のバックグラウンドモニタ設定
`bin/`	plugin root	plugin が有効な間、Bash ツールの `PATH` に追加される実行ファイル
`settings.json`	plugin root	plugin が有効なときに適用される既定の settings

skill が 1 つだけの plugin は、skills/ を作らず plugin root に直接 SKILL.md を置ける。この場合 frontmatter の name フィールドが呼び出し名になる

plugin.json のフィールド

フィールド	用途
`name`	一意な識別子であり skill の名前空間。skill はこれを接頭辞に持つ
`description`	plugin マネージャで閲覧・インストール時に表示される
`version`	任意。設定した場合、この値を上げたときにのみユーザーへ更新が届く。省略時は version management の次のソースから決まる
`author`	任意

homepage / repository / license などは plugins-reference の manifest schema を参照。

ローカルでのテスト

claude --plugin-dir ./my-plugin で、インストールせずに plugin を読み込む
.zip アーカイブも指定できる（claude --plugin-dir ./my-plugin.zip）
フラグを複数回指定すると複数 plugin を同時に読み込める
--plugin-dir の plugin がインストール済み marketplace plugin と同名の場合、そのセッションではローカルのコピーが優先される。ただし managed settings が force-enable / force-disable している plugin は --plugin-dir で上書きできない
URL でホストされた .zip は --plugin-url を使う。起動時に取得し、そのセッションのみ読み込む。取得失敗やアーカイブ不正のときは plugin 抜きで起動し、/plugin マネージャの Errors タブに読み込みエラーが記録される
- 複数指定はフラグの繰り返し、またはスペース区切りの 1 引数（引用符で囲む）
変更を反映するには /reload-plugins を実行する。plugin / skill / agent / hook / plugin の MCP サーバー / plugin の LSP サーバーが再読み込みされる
動作確認: skill は /plugin-name:skill-name、agent は /context の Custom Agents に出るか、スコープ付き名で @-mention、hook は対応イベントを発生させる。マッチした hook・終了コード・出力は debug log に記録される

skills ディレクトリでの plugin 開発

claude plugin init my-tool で ~/.claude/skills/my-tool/ に .claude-plugin/plugin.json と初期の SKILL.md を生成する
次のセッションから my-tool@skills-dir として読み込まれ、marketplace もインストール手順も不要

LSP サーバー

.lsp.json を plugin に追加する。インストールするユーザーの環境に language server バイナリが必要
起動確認は /plugin の Errors タブ。起動失敗はここに出る（バイナリ未インストール時は Executable not found in $PATH など）。設定が不正なエントリはスキップされるため、理由は claude --debug で確認する

バックグラウンドモニタ

plugin root の monitors/monitors.json にモニタエントリの配列を書く
plugin が有効なとき Claude Code が各モニタを自動起動する
command の stdout の各行がセッション中に notification として Claude に届く

plugin の settings.json

現在サポートされるキーは agent と subagentStatusLine のみ
agent を設定すると plugin のカスタム agent の 1 つがメインスレッドとして有効になり、その system prompt・ツール制限・モデルが適用される
settings.json の設定は plugin.json で宣言した settings より優先される。未知のキーは黙って無視される

公開 marketplace

claude-plugins-official: Anthropic が管理するキュレーション済みの plugin 群。初めて対話的に Claude Code を起動したときに自動登録される。それ以前に非対話で実行した場合や marketplace policy に阻まれた場合は claude plugin marketplace add anthropics/claude-plugins-official で自分で登録する
claude-community: レビュー後に第三者の投稿が載る公開コミュニティ marketplace。/plugin marketplace add anthropics/claude-plugins-community で追加し、@claude-community としてインストールする
投稿フォーム: claude.ai（Team または Enterprise 組織と directory 管理権限が必要）または Console
投稿前に claude plugin validate ./your-plugin をローカル実行する。成功時は ✔ Validation passed、警告があれば ✔ Validation passed with warnings を出力する。警告は失敗扱いにならないが、--strict を付けるとエラー扱いになる
承認された plugin は anthropics/claude-plugins-community カタログで特定の commit SHA にピン留めされ、リポジトリへの push で CI がピンを自動更新する。公開カタログはレビューパイプラインから毎晩同期されるため、承認から掲載まで遅延がある
official marketplace は別途キュレーションされ、応募手続きは無い。投稿フォームから official marketplace には追加されない

standalone からの移行

Standalone（`.claude/`）	Plugin
1 プロジェクトでのみ利用可能	marketplace 経由で共有できる
`.claude/commands/` のファイル	`plugin-name/commands/` のファイル
`settings.json` の hooks	`hooks/hooks.json` の hooks
共有には手動コピーが必要	`/plugin install` でインストール

hooks の形式は同じなので、.claude/settings.json または settings.local.json の hooks オブジェクトをそのままコピーする
移行後は重複を避けるため .claude/ の元ファイルを削除する。project / user の .claude/agents/ の定義は同名の plugin agent を上書きするため、元ファイルを消すまで plugin 版は有効にならない。plugin skill は名前空間付きなので、元の /skill-name と plugin のコピーは両方残る

設定

// my-first-plugin/.claude-plugin/plugin.json
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

// .lsp.json
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

// monitors/monitors.json
[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

// settings.json（plugin root）
{
  "agent": "security-reviewer"
}

制約・注意点

commands/ / agents/ / skills/ / hooks/ を .claude-plugin/ の中に置いてはいけない。.claude-plugin/ に入るのは plugin.json だけで、それ以外のディレクトリは plugin root に置く
plugin root とは個々の plugin 自身のディレクトリ（--plugin-dir に渡すディレクトリ、または .claude-plugin/plugin.json を含むディレクトリ）であり、~/.claude/ ではない。たとえば ~/.claude/.mcp.json は読まれない
/reload-plugins のサマリに出る skills 数は commands/ ディレクトリのみを数えるため、skills/ の skill を編集した直後でも 0 skills と表示されることがある
plugin をインストールした後、インストールサマリに Run /reload-plugins to activate. と出た場合はそのコマンドを実行する