# プラグイン作者のためのベストプラクティス 2026
Claude Code のプラグインを書き始めて最初に迷うのは、ディレクトリ構造と `plugin.json` の書き方、そしてどう配布するかである。本稿では公式の `plugins-reference` を踏まえ、現場で破綻しにくい型を提案する。あくまで Anthropic が公開している仕様の範囲で論じ、推測が混じる部分は明示する方針を採る。
ディレクトリ構造の基本形
公開情報によれば、プラグインのルートには `.claude-plugin/` ディレクトリを置き、その中に `plugin.json` を配置する。実装ファイル群、すなわち `commands/`・`skills/`・`agents/`・`hooks/`・`.mcp.json` はプラグインのルート直下に置き、`README.md` も同階層に揃える。マニフェスト自体に実行ロジックを書かず、参照先に役割を委譲するのが基本姿勢だ。これにより、レビュー時に「マニフェストで構造を把握してから個別ファイルを読む」流れが自然に組み立てられ、規模が大きくなっても見通しが保たれる。レイアウトを途中で変えると周辺ツールやドキュメントが揃って崩れるため、最初の段階で標準レイアウトを採用しておくのが合理的である。
```text my-plugin/ .claude-plugin/ plugin.json commands/ review.md skills/ style-check/ SKILL.md hooks/ audit.sh agents/ security.md README.md ```
plugin.json の必須フィールドと省略時挙動
`plugin.json` には name・version・description のほか、author 情報・homepage・repository・license・keywords を入れておく。skills・commands・agents・hooks・MCP サーバー・出力スタイル・テーマ・LSP サーバーといった構成要素のパスも記述できる。マニフェストを省略した場合は既定の場所が自動探索され、ディレクトリ名が name に流用される仕様だが、配布を意識するなら明示する方が無難だ。バージョン番号はセマンティックバージョニングに従い、互換性を破る変更ではメジャーを進める。description はマーケットプレイス検索で表示されるため、検索キーワードを意識して 100 文字以内に収めるのが実用的である。keywords には機能名と対象領域を併記すると検索性が高まる。author 情報を充実させることは信頼性のシグナルにもなるため、メンテナの連絡先や所属を載せておくと、ユーザーが安心して採用判断を下せる。
SKILL.md のフロントマターと自動起動の扱い
Skill のフロントマターには起動条件を丁寧に書く。自動呼び出しを許す場合は `disable-model-invocation` を未設定にし、説明文に「いつ呼ぶべきでないか」まで書くと暴発を抑えられる。逆にユーザーが手で叩く前提なら `disable-model-invocation: true` を入れる。Command との二重定義時は Skill が優先される点も覚えておきたい。Skill の本文（SKILL.md 内）は、起動条件・前提・手順・例の順で構成すると LLM が読みやすい。補助ファイルとして外部リファレンスを参照させると、本体を軽く保ったまま深い知識を扱えるが、参照頻度が低いものは inline せず外に出す方がトークン効率がよい。Skill の起動説明は単なる解説文ではなく、判定ロジックそのものとして機能する。あいまいな表現は予期しない発火を生み、運用混乱の温床になるため、肯定形と否定形の両方で条件を書き分けるのが安全だ。
marketplace.json と配布の実務
第三者にも届けたいなら、自前の `marketplace.json` を持つ Git リポジトリを用意する。ユーザーは `/plugin marketplace add` で登録し、`/plugin install` で個別プラグインを取り込む流れだ。GitHub・Git URL・ローカルパス・npm パッケージのいずれでも source として指定できる。社内利用ならプライベートリポジトリでも問題ないが、認証フローは事前に整備しておくべきだ。`marketplace.json` に列挙する各プラグインには、name・description・source の三点を最低限揃え、可能なら version 範囲も明記する。これによりユーザー側で固定版を選ぶ運用が可能になる。マーケットプレイスを公開する際は、CHANGELOG をプラグインごとに用意し、互換性破壊の履歴を辿れるようにしておくと、利用者の安心感が増す。組織内マーケットプレイスでも、社内向けのリリースノートを残す習慣をつけると、運用の透明性が大きく上がる。
テスト・検証・配布前チェックリスト
公開情報が示すとおり、Skill のオートコンプリートはフルネーム入力後に色が変わる仕様などクセがある。検証時はサンドボックス用のリポジトリを別に用意し、`/plugin` 系コマンドで実際の挙動を確認する。Hook はゼロ以外の終了コードで処理を中断できるため、決定論的なテストを書きやすい。Skill は LLM が呼ぶ性質上、起動条件のプロンプト文を変えながらの A/B 検証が現実的だ。公開前のチェックリストとしては、第一に README に最小利用例があるか、第二に plugin.json のメタ情報が網羅されているか、第三に危険操作に対する PreToolUse フックがあるか、第四に Skill の説明文が「使うべきでない場面」を含むか、第五に marketplace.json の source 表記が正しいか、を確認したい。これらを抑えておくと、後発のユーザーが事故りにくい。さらに、テスト用のシナリオを README に併記しておくと、利用者が自分の環境で安全性を確認できるため、初動の信頼を得やすくなる。
アンチパターンと KGA IT 内部の標準
最後にアンチパターンを挙げる。マニフェストに大量のロジックを書き込む、Skill と Command で同名・別実装を二重に持つ、Hook を握り潰して全許可にする、依存ライブラリのバージョン固定を怠る、外部 API キーをハードコードする、テスト用フィクスチャを本番用ディレクトリに混在させる、などである。KGA IT 内部の標準テンプレートでも、これらを避けるレビュー観点をチェックリスト化しており、新規プラグインのマージ前に必ず通す運用にしている。プラグインは便利な拡張機構だが、設計を疎かにすると保守不能なブラックボックスになりやすい。本稿で挙げた構造・テスト・配布の観点を押さえれば、長期的に保てるプラグイン群を組み立てられるはずだ。さらに重要なのは、プラグインを「育てる文化」を組織に根付かせることである。一度書いて終わりではなく、利用ログを見ながら起動条件や手順を磨き込み、不要になったものは潔く外す。この運用サイクルを回せるチームは、Claude Code の生態系を最大限に活用できる。逆に書きっぱなしの文化が定着すると、半年後には誰も触れない化石プラグインが転がる結果になる。