Create a Claude Code plugin

原典: Create a Claude Code plugin ／ 日本語版

一行要約

plugin はマニフェスト（plugin.json）と部品のディレクトリで、--plugin-dir で marketplace 無しに試せる。原典が警告する置き場所の間違いは2つで、.claude-plugin/ に部品を入れることと ~/.claude/ を plugin ルートとみなすこと（どちらも読まれない）。既存の .claude/ から移すと skill と agent は名前に接頭辞が付くので共存するが、hook は接頭辞が無いので二重に走る。

要点

単体のままにするか、plugin にするか

Skills, agents, hooks, and MCP servers all work standalone in your project or home directory. Keep that standalone setup while it serves one project or only you. Make a plugin when you want to share the setup with teammates, install it in several projects, or publish versioned releases.

skill・agent・hook・MCP サーバは、どれもプロジェクトかホームディレクトリで単体で動く。1つのプロジェクトか自分だけのためなら、単体の構成のままにしておけ。 チームメイトと共有したい、いくつものプロジェクトに入れたい、バージョン付きで公開したいときに plugin にせよ。

plugin に移すと、置き場所と名前が変わる:

• 置き場所 —— plugin 自身のディレクトリ（plugin ルート）の下の skills/ agents/ hooks/hooks.json .mcp.json
• 名前 —— plugin の skill と agent には plugin 名の接頭辞が付く（/my-plugin:hello）。2つの plugin がそれぞれ hello を持っても衝突しないため

マニフェスト

フィールド	意味
name	必須。 plugin を識別し、その plugin が提供するすべての skill と agent の接頭辞になる。空白を入れない
description	/plugin でユーザーに見える説明
version	任意。設定すると、変えるまでユーザーはその版に留まる
author	中の name が必須。email と url は任意

--plugin-dir で読んだ plugin にマニフェストが無ければ、ディレクトリ名が plugin 名になる。

置き場所

plugin ルートからの場所	中身
.claude-plugin/plugin.json	マニフェスト
skills/	skill ごとに <name>/SKILL.md のディレクトリ
commands/	平たい Markdown ファイル。skill の古い形。新しい plugin では skills/ を使う
agents/	subagent ごとに Markdown ファイル1つ
hooks/hooks.json	トップレベルの "hooks" キーの値が、設定ファイルの hooks と同じ形
.mcp.json	MCP サーバの定義

使うディレクトリだけを足せばよい。これ以外の場所はマニフェストのリファレンスにある。

Only plugin.json goes inside .claude-plugin/. Components saved there don’t load.

The plugin root is the plugin’s own directory, not ~/.claude/ itself. A .mcp.json saved at ~/.claude/.mcp.json doesn’t load.

.claude-plugin/ の中に入るのは plugin.json だけ。そこに置いた部品は読み込まれない。

plugin ルートとは plugin 自身のディレクトリで、~/.claude/ そのものではない。 ~/.claude/.mcp.json に置いた .mcp.json は読み込まれない。

marketplace 無しで試す

1セッション限りで読み込む方法が3つある。どれも設定には何も書かない。 セッション中にファイルを直したら /reload-plugins。

• --plugin-dir —— plugin ルートのディレクトリか、その .zip。繰り返せば複数読める
  • フォルダごと渡せる（v2.1.265 以降）。トップレベルに .claude-plugin/ も部品も無ければ「plugin を並べたフォルダ」と見なし、.claude-plugin/plugin.json を持つ直下のサブフォルダだけを1つずつ読む。それ以外はエラー無しで飛ばす（マニフェストの無いサブフォルダを含む）
  • .claude-plugin/marketplace.json を並べて置いたフォルダでも、その .claude-plugin/ に plugin.json が無ければ plugin は読まれる（v2.1.281 以降）。marketplace ファイルは読まれないので、そこから何もインストール・有効化されない
  • 対話セッションでは起動後もフォルダを見ており、サブフォルダを足せば読み、消せば外す。prompt cache を壊す変更は保留され、/reload-plugins を促すメッセージが出る
• --plugin-url —— .zip の URL（CI が出すビルド成果物など）。起動時に取得する。自分が管理しているか信頼できるアーカイブだけを指すこと。 取得に失敗しても起動はし、/plugin の Errors タブに記録が残る
• CLAUDE_CODE_PLUGIN_DIRS —— フラグを足せないセッション用に、絶対パスを並べる（v2.1.280 以降）。--plugin-dir と併用できる。project / local settings からは設定できない（env-vars）

managed settings は --plugin-dir と CLAUDE_CODE_PLUGIN_DIRS を止められる。

毎セッション読ませる（claude plugin init）

~/.claude/skills/ の下で .claude-plugin/plugin.json を持つフォルダは、フラグもインストールも無しに毎セッション plugin として読まれる。 claude plugin init <name>（v2.1.157 以降）がその雛形を作る。

• 作られるのは ~/.claude/skills/<name>/ に .claude-plugin/plugin.json とルートの SKILL.md。<name>@skills-dir として次のセッションから読まれる（skills-dir は marketplace 名の位置に入る）
• ルートの SKILL.md は個人の skill でもあるので /<name> で呼ぶ（/<name>:<name> ではない）。skills/ の下に足した skill には接頭辞が付く
• 止めるにはディレクトリを消すか、claude plugin disable <name>@skills-dir
• リポジトリの全員に読ませるなら、同じ形を <project>/.claude/skills/<name>/ に自分で作る

変更が反映されないときの確認順

1. claude plugin validate <path> —— マニフェストと、すべての skill / agent / command のフロントマターを検査する。--strict で警告でも失敗にする
2. /reload-plugins —— ディスク上の変更を反映する
3. /plugin —— Installed タブに見つかった部品、Errors タブに読めなかったものと理由
4. claude plugin list —— セッション限りの plugin と skills ディレクトリの plugin が別の節に出る

MCP サーバは /mcp で状態を見る。hook はそのイベントを起こしてから debug log を読む（hooks）。

開発中に当たりやすい失敗:

症状	原因
Errors タブに <component> path not found	マニフェストの部品パスが何も指していない
marketplace のルートを --plugin-dir に渡すと、plugins/ の下の plugin が読まれない。エラーも出ない	--plugin-dir は marketplace.json を読まない。plugin 1つのフォルダを渡すか、marketplace を追加する
plugin は読まれるが skill が無い	skills/ が .claude-plugin/ の中にあるか、マニフェストの skills がファイルを指している
userConfig のダイアログが出ない	ダイアログは /plugin からのインストールの一部。--plugin-dir でも claude plugin install でも出ない。/plugin configure <plugin-name> で開く

A plugin that loads without errors can still fail to steer Claude the way you intend.

エラー無しで読み込まれる plugin でも、意図したとおりに Claude を導けていないことはある。

それを測るのが claude plugin eval（テストケースを plugin あり / なしで走らせ、差を採点する）。

既存の .claude/ を移す

書き直さずに移せる。.claude/ の commands agents skills を plugin ルートにコピーし、hook は設定ファイルの hooks オブジェクトをそのまま hooks/hooks.json に写す（形式は同じ）。移したら新しい名前で確かめる（/deploy だった skill は /my-plugin:deploy、reviewer だった agent は my-plugin:reviewer）。

元のファイルが .claude/ に残っている間は、plugin 側と並んで読み込まれる:

• skill と agent —— 接頭辞があるので衝突しない。/deploy も /my-plugin:deploy も動き、Claude には reviewer と my-plugin:reviewer が別の subagent に見える

Hooks: hooks have no prefix, so a hook that is in both your settings file and hooks/hooks.json runs twice each time its event fires.

hook: hook には接頭辞が無いので、設定ファイルと hooks/hooks.json の両方にある hook は、イベントが起きるたびに2回走る。

plugin が動くのを確かめたら、.claude/ の元ファイルを消し、設定ファイルから hooks オブジェクトを取り除く。

配る方法は3つ

方法	向いている場面
ディレクトリか .zip を直接渡す	数人に。何も公開しない
自分の marketplace に載せる	チームメイトが一度追加すれば名前で入れられ、更新が届く
Anthropic のディレクトリに申請する	審査を通ると claude.ai と Cowork で追加でき、アカウント経由で Claude Code にも届く

大きめの plugin を Claude と一緒に作るなら、公式 marketplace の plugin-dev plugin を入れて /plugin-dev:create-plugin を実行する。

そのまま使える具体例

mkdir -p my-first-plugin/.claude-plugin     # .claude-plugin/ にはマニフェストだけ
mkdir -p my-first-plugin/skills/hello       # 部品は plugin ルート直下
claude plugin validate ./my-first-plugin    # ✔ Validation passed を確かめる
claude --plugin-dir ./my-first-plugin       # このセッション限りで読む

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

my-first-plugin/skills/hello/SKILL.md（disable-model-invocation: true なので Claude が自分からは走らせない）:

---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---
 
Greet the user warmly and ask how you can help them today.

セッションで /my-first-plugin:hello と打つ。

原典で言及されている関連文書

• plugins — plugin が要るかどうか、marketplace
• skills — skill のフロントマター
• env-vars — CLAUDE_CODE_PLUGIN_DIRS
• hooks — hook の debug log