
Claude Codeのプラグインの作り方|スキル・エージェント・フックを1つにまとめて配る手順と、毎回の土台が増える量を実測【2026年10月】
Claude Code では、スキル・サブエージェント・フックを、それぞれ自分で作って使えます。ただ、いくつも作ると、「別のプロジェクトでも同じものを使いたい」「同僚に配りたい」という場面が出てきます。そのためにある仕組みが、プラグインです。
この記事は、小さなプラグインを自分で作りながら、次の3つの疑問に、実機で答えます。
プラグインは、どんなフォルダの形で、何を書けばよいのか
作ったプラグインを、どう試して、どう配るのか
入れたプラグインは、使わなくても毎回の使用量を増やすのか。増えるなら、どれくらいか
私は Claude Code と Codex を毎日使って、教材づくり、note や Gumroad への出品、画像づくりを自動化している個人です。プラグインを配布する立場ではなく、手元で作って試した結果をまとめます。全文無料です。
情報の扱いを書いておきます。公式のドキュメント(Claude Code の plugins のページと、marketplace のページ)は、2026年10月23日に読みました。公式の文は「要約すると」と断って、私の言葉で書きます。実測は、Windows 11、Claude Code 2.1.306、2026年10月23日、claude -p(画面なしの実行)で、モデルは Haiku 5.5 です。
この記事で分かること
プラグインとは何か。単体のスキルとの使い分け
最小のプラグインの作り方(実物のファイルつき)
検証(claude plugin validate)と、試す方法(--plugin-dir)
スキル・エージェント・フックが、実際に動く様子
自作のマーケットプレイスで、インストールから削除まで
入れたプラグインが、毎回の土台を増やす量(実測)
試していないこと
先に結論
プラグインは、スキル・エージェント・フック・MCP サーバーを、1つのフォルダにまとめたものです。目印は、.claude-plugin/plugin.json というファイルです(無くても読み込めますが、プラグインの名前がフォルダの名前になります)
plugin.json を書くなら、必須なのは name だけです。この名前が、スキルやエージェントの前につく名前(/note-helper:title-check のような形)になります
作ったら、claude plugin validate ./フォルダ で検証します。claude --plugin-dir ./フォルダ で、インストールせずに、その会話だけ読み込めます
私が作った例(スキル2つ・エージェント1つ・フック1つ)のうち、スキル1つ・エージェント・フックの3つが動きました(人が / で呼ぶ専用にしたスキル char-count は、呼んでいません)。確かめたのは、スラッシュで呼ぶ、Claude が自分で呼ぶ、エージェントとして呼ばれる、会話の開始時にフックが動く、の4つです
入れたプラグインは、使わない会話でも、毎回読み込まれます。私の例では、+133トークンでした。同じ形のスキル30個では、+2,430トークン(1つあたり約81トークン)でした。claude plugin details が出す見積もりは、142と2,377で、実測にほぼ合っていました
配るには、marketplace.json を置いたフォルダを作り、claude plugin marketplace add と claude plugin install 名前@マーケット名 を使います。自分のパソコンの中だけで、一通り動きました
試していないこと:GitHub での配布、MCP サーバーを含むプラグイン、claude plugin eval、バージョンの更新

プラグインとは
公式のドキュメントを要約すると、プラグインは「スキル・エージェント・フック・MCP サーバーなどを、1つのフォルダにまとめて、Claude Code が1つの単位として読み込むもの」です。
単体で作ったスキル(~/.claude/skills/ に置いたもの)は、すでに、すべてのプロジェクトで使えます。公式も、「1つのプロジェクトだけ、または自分だけなら、単体のままでよい」という趣旨で書いています。プラグインにしたほうがよい場面は、次のとおりです。
複数のスキル・エージェント・フックを、ひとまとまりとして扱いたい
同僚に配りたい、または、たくさんのプロジェクトに入れたい
バージョンをつけて、更新を届けたい
もう1つ、名前の違いがあります。プラグインのスキルは、プラグインの名前が前につきます。たとえば note-helper というプラグインの title-check スキルは、/note-helper:title-check で呼びます。ほかのプラグインに同じ名前のスキルがあっても、ぶつかりません。
スキル・サブエージェント・フックの作り方は、それぞれ別の記事に書きました(記事の最後の「次に読む」に載せています)。この記事は、それらをまとめる部分に絞ります。
最小のプラグインを作る
試験用に、「note の記事の題名を点検する」プラグイン note-helper を作りました。形は、次のとおりです。
note-helper/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ ├── title-check/SKILL.md
│ └── char-count/SKILL.md
├── agents/
│ └── title-reviewer.md
└── hooks/
└── hooks.json大事な注意が1つあります。公式が警告しているとおり、.claude-plugin/ の中に入れるのは、plugin.json だけです。skills/ などをそこに入れると、読み込まれません。
plugin.json
{
"name": "note-helper",
"description": "note 記事の題名と字数を点検する小さなプラグイン(試験用)",
"version": "1.0.0",
"author": { "name": "masa" }
}name は必須で、空白は使えません。この名前が、スキルとエージェントの前につきます。description は、/plugin の画面に出る説明です。version は、省略できます。付けると、あなたが変えるまで、使う人の版が固定されます。
スキル
skills/title-check/SKILL.md です。
---
name: title-check
description: note 記事の題名を点検する。題名の長さ(90字以内)と、先頭に検索語があるかを確かめるときに使う
---
渡された題名について、次の3つを短く答えてください。
1. 文字数(数えた数字)
2. 90字以内か
3. 先頭の20字に、検索されそうな語が入っているかもう1つ、skills/char-count/SKILL.md は、disable-model-invocation: true を付けました。これは、Claude が自分では呼ばず、人が / で呼んだときだけ動くスキルにする指定です。
エージェント
agents/title-reviewer.md です。
---
name: title-reviewer
description: 題名の案を3つ受け取り、いちばん良い1つを選んで理由を1行で答える
tools: Read
---
題名の案を比べて、いちばん良い1つを選び、理由を1行で答えてください。フック
hooks/hooks.json です。会話の開始時に、一言出すだけの、試験用のものです。
{
"hooks": {
"SessionStart": [
{ "hooks": [ { "type": "command", "command": "echo note-helper-loaded" } ] }
]
}
}形は、設定ファイル(settings.json)の hooks と同じです。単体のフックを、プラグインに移すときは、設定ファイルの hooks の部分を、外枠の { "hooks": … } ごと、hooks/hooks.json に移します。
検証する:claude plugin validate
作ったら、まず検証します。
claude plugin validate ./note-helper結果は、最後の行が ✔ Validation passed、終了コードは 0 でした。
途中に、Anthropic のディレクトリに提出するときの検査の結果も出ました。
README と LICENSE が無い:「提出を断られる問題」として表示(README.md: README missing・LICENSE: License missing)
アイコンが無い:警告として表示(icon: No icon)
これらは、ふつうの結果(✔ Validation passed・終了コード 0)を変えません。--profile directory を付けると、README と LICENSE の欠落で ✘ Validation failed(終了コード 1)になりました。--strict だけでは、終了コード 0 のままでした。自分で使うだけなら、無視してよいと、私は受け取りました。配るときは、README・LICENSE・アイコンを足すとよいようです。
試す:--plugin-dir
インストールしないで、その会話だけ読み込むには、--plugin-dir を使います。
claude --plugin-dir ./note-helperclaude --plugin-dir ./note-helper plugin list で、note-helper@inline(Status: ✔ loaded)と出ました。inline は、--plugin-dir で読み込んだことを表すようです。
1. スラッシュで呼ぶ
claude -p --plugin-dir ./note-helper "/note-helper:title-check 題名" で、スキルが動きました。題名は「Claude Codeのプラグインの作り方|skillsとhooksをまとめて配る手順を実機で確認【2026年10月】」で、答えは「文字数:59字」「90字以内:はい」「先頭20字に検索語:あり」でした。Python で数えると、この題名は59字で、合っていました。
起動時の情報には、note-helper:title-check と note-helper:char-count が、スラッシュコマンドの一覧に並んでいました。
2. Claude が自分で呼ぶ
「次の題名は長すぎないか、検索語が先頭にあるかを点検してください:…」と頼むと、Claude は、自分で Skill の道具を呼び、note-helper:title-check を使いました。description に「いつ使うか」を書いておいたので、呼ばれたのだと考えられます(description を変えて比べてはいません)。
3. エージェントとして呼ぶ
「note-helper:title-reviewer のエージェントに、次の3つの題名案から1つを選ばせてください」と頼むと、Agent の道具が、subagent_type に note-helper:title-reviewer を指定して呼ばれました。3案の中から「案2:Claude Codeのプラグインの作り方」が選ばれ、理由は、「Claude Code」と「作り方」が題名に明示されていて、読者が得るものが最も明確に伝わる、というものでした。
4. フックが動く
会話の開始時に、SessionStart のフックが動きました。画面なしの実行で、イベントを見ると、hook_started と hook_response が出ていて、出力は note-helper-loaded、終了コード 0 でした。
毎回の土台は、どれだけ増えるか
ここが、実測のいちばん知りたかった所です。公式のドキュメントを要約すると、有効なプラグインは、使わない会話でも、毎回の文脈に載ります。Claude が自分で呼べるスキルやエージェントは、名前と説明が、毎ターン文脈に入ります。この分は、使用量に数えられて、文脈の空きも減ります。スキルやエージェントの本文は、使われたときだけ読み込まれます。
実測しました。「OK とだけ答えてください」を、3回ずつ動かして、入力の合計(通常の入力+キャッシュへの書き込みと読み取り)を比べました。プラグインは --plugin-dir で読み込んだ状態で測り(インストールした版では測っていません)、ユーザー設定は読ませていません。
プラグインなし:25,108トークン(3回とも同じ値)
note-helper(スキル2・エージェント1・フック1):25,241トークン。+133
スキル30個だけのプラグイン(各スキルの説明は約63字):27,538トークン。+2,430。1つあたり約81トークン
claude --plugin-dir ./フォルダ plugin details プラグイン名 で、入れる前に、見積もりが見られます(インストールしたあとは、--plugin-dir なしの claude plugin details プラグイン名 で見られます)。
Projected token cost
Always-on: ~142 tok added to every sessionnote-helper は 142、スキル30個のものは 2,377 と出ました。実測は、133 と 2,430 で、どちらもほぼ合っていました。フックは、「harness-only — no model context cost」(モデルの文脈には載らない)と出ました。
つまり、説明の長いスキルを、たくさん入れたプラグインほど、毎回の土台が増えます。30個で約2,400トークンですから、大きくはありませんが、複数のプラグインを入れると積み重なります。claude plugin details で、入れる前に見る習慣をつけるとよいと、私は思います。
配る:自作のマーケットプレイス
公式を要約すると、マーケットプレイスは、プラグインの目録です。.claude-plugin/marketplace.json を置いたフォルダで、場所は、Git のリポジトリでも、ローカルのフォルダでもよいそうです。私は、自分のパソコンの中のフォルダで、一通り試しました。
フォルダを作る
mp/
├── .claude-plugin/
│ └── marketplace.json
└── plugins/
└── note-helper/ ← 上で作ったプラグインを、コピーmarketplace.json は、次のとおりです。name・owner・plugins(各プラグインの name と source)が必須です。
{
"name": "masa-tools",
"description": "note の記事づくりの小さな道具",
"owner": { "name": "masa" },
"plugins": [
{
"name": "note-helper",
"source": "./plugins/note-helper",
"description": "note 記事の題名と字数を点検する"
}
]
}source は、マーケットプレイスのフォルダ(.claude-plugin/ を含むフォルダ)からの相対パスです。.. は使えません。また、ここの name と、プラグインの plugin.json の name は、同じにします。違うと、名前で入れようとして見つからない、というエラーになるそうです。
検証して、登録して、入れる
claude plugin validate ./mp
claude plugin marketplace add ./mp
claude plugin install note-helper@masa-tools --scope local結果は、次のとおりでした。
検証:✔ Validation passed
登録:✔ Successfully added marketplace: masa-tools (declared in user settings)
インストール:✔ Successfully installed plugin: note-helper@masa-tools (scope: local)
claude plugin list を見ると、note-helper@masa-tools・Scope: local・Status: ✔ enabled と出ました。「どこから読んでいるか」(Read from)は、mp/plugins/note-helper の、手元のフォルダそのものでした。公式は、ローカルのマーケットプレイスなら、手元のフォルダのファイルを直接読む(編集は、次の起動か /reload-plugins で反映される)と書いています。ただし、私の環境では、インストールのときに、~/.claude/plugins/cache の下にも複製ができていました。
入れる範囲(スコープ)は、3つです。user(自分の全プロジェクト)、project(そのリポジトリの全員)、local(自分のそのリポジトリだけ)。私は local で試しました。local で入れると、そのプロジェクトの .claude/settings.local.json に、次の設定が書かれました。
{
"enabledPlugins": {
"note-helper@masa-tools": true
}
}インストールしたものを使う
--plugin-dir なしで、claude -p "/note-helper:title-check Claudeプラグインの作り方" を動かすと、スキルが動きました。答えは「文字数:15字(Claude 6字 + プラグイン 5字 + の 1字 + 作り方 3字)」で、数え方も合っていました。
後片付け
試験が終わったら、次の2つで元に戻せます。
claude plugin uninstall note-helper@masa-tools --scope local
claude plugin marketplace remove masa-toolsそれぞれ ✔ Successfully uninstalled plugin と ✔ Successfully removed marketplace と出て、claude plugin list は「No plugins installed」に戻りました。marketplace add は、ユーザー設定(~/.claude/settings.json)に記録されるので、試験のあとは、marketplace remove で消しておくのがよいと思います。
入れる前に:セキュリティ
公式の「Plugin security and trust」のページは、プラグインについて、こう書いています(要約)。プラグインが動かすものは、あなたの権限で動きます。フックはコマンドを動かし、MCP サーバーはプロセスとして動きます。知らない人のプラグインは、入れる前に、hooks/hooks.json と、スクリプトの中身を読んでください。Anthropic の公式のマーケットプレイスでも、第三者のものでも、考え方は同じです。
注意点と限界
試したのは、スキル・エージェント・フックだけです。MCP サーバーや LSP サーバーを含むプラグインは、試していません
配布は、自分のパソコンの中のマーケットプレイスだけです。GitHub に置いて、他の人が入れる流れは、試していません
claude plugin eval(プラグインの効き目を試験する機能)、claude plugin init(~/.claude/skills/ に雛形を作る)、バージョンの更新、userConfig は、試していません
土台の増え方は、Haiku 5.5・1つの環境の値で、--plugin-dir で読み込んだ状態で測りました(インストールした版では測っていません)。説明の長さで変わります(今回の30個は、1つが約63字の説明)
disable-model-invocation: true のスキルが、土台にどう数えられるかは、確かめていません(plugin details の見積もりには、このスキルの分も入っていました)
名前の前につく「プラグイン名:」の形は、スキルとエージェントで確かめました。フックは、名前がつかないので、同じフックを、設定ファイルとプラグインの両方に書くと、2回動くそうです(公式の説明で、試していません)
まとめ
プラグインは、スキル・エージェント・フック・MCP を、1つのフォルダにまとめたもの。目印は .claude-plugin/plugin.json(書くなら、必須は name だけ)
試すのは claude --plugin-dir ./フォルダ、検証は claude plugin validate、配るのは marketplace.json + claude plugin marketplace add + claude plugin install 名前@マーケット名
入れたプラグインは、使わなくても毎回の土台を増やす。私の例は +133トークン、30スキルで +2,430トークン。claude plugin details で、入れる前に見積もれる
配る・入れる前に、フックとスクリプトの中身を読む
次の一歩は、すでにあるスキルを1つ選んで、my-plugin/skills/名前/SKILL.md に置き、plugin.json を書いて、claude --plugin-dir ./my-plugin で動かしてみることです。10分で、できます。
次に読む
Claude Codeのスキル(Skills)の作り方(無料):SKILL.md で毎回の頼み方を手順書にする
Claude Codeのフック(hooks)の使い方(無料):settings.json の書き方と実用例5つ
Claude Codeのサブエージェントの使い方(無料):.claude/agents の作り方・tools・model の指定
MCPとは?Claude Codeにつなぐ方法(無料):claude mcp add の書き方・設定ファイル
Claude Codeの『mods』入門(¥100):数行の TypeScript で自分専用に改造する。入れる前の権限の話
Claude Code テンプレート集(¥9,800):CLAUDE.md・スキル12本・フック10本・自動化の実物パック
このアカウントをフォローすると、Claude Code や Codex の新しい手順の記事が届きます。ぜひフォローしてください。
この先で分かること(今後の有料記事)
自分のスキル・フックを、プラグインにまとめて、複数のプロジェクトに配る手順の実物
GitHub に置いた自作マーケットプレイスから、チームに配る手順
プラグインの効き目を試験する claude plugin eval の使い方
まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。