メインコンテンツへスキップ
見出し画像

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-helper

    claude --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 session

    note-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 や Codex の新しい手順の記事が届きます。ぜひフォローしてください。

    この先で分かること(今後の有料記事)

    • 自分のスキル・フックを、プラグインにまとめて、複数のプロジェクトに配る手順の実物

    • GitHub に置いた自作マーケットプレイスから、チームに配る手順

    • プラグインの効き目を試験する claude plugin eval の使い方

    まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。

    あなたへのおすすめ