# Claude Code プラグイン SDK 徹底解剖
Claude Code のプラグイン機構は、単なるマクロの集合ではなく、開発者が IDE エージェントの振る舞いを宣言的に拡張するための小さな OS のような存在である。2026 年に入り、`plugin.json` を中核とするマニフェスト駆動の設計が安定し、我々のチームでも社内標準プラグインを複数本番運用している。本稿では SDK の要素を分解し、どのように組み合わせるのが実用的かをまとめる。
マニフェストの骨格
`plugin.json` は四つの主要フィールドを持つ。`commands` はスラッシュコマンドの宣言、`skills` はモデルが自律的に呼び出す専門ツール、`hooks` はセッションのライフサイクルに割り込む実行ポイント、そして `subagents` は独立したコンテキストを持つ補助エージェントの定義である。最低限のマニフェストは次の形に近い。
```json { "name": "kga-review", "version": "1.2.0", "description": "社内コードレビュー用プラグイン", "commands": ["commands/review.md"], "skills": ["skills/style-check/SKILL.md"], "hooks": { "PreToolUse": "hooks/audit.sh" }, "subagents": ["agents/security.md"] } ```
ポイントは、マニフェストが「宣言」に徹していることだ。実行コードを直接書き込まず、参照先のファイルに役割を委譲する。これにより差分レビューがしやすくなり、レビュー担当が SDK の挙動を読み解かずとも構造を把握できる。
Commands と Skills の責務分担
最初につまずきやすいのが、commands と skills の違いである。commands は人間がスラッシュで明示的に呼び出すもので、入力の形式やオプションをユーザーが知っている前提で設計する。一方 skills はモデルが文脈から必要性を判断して呼び出す。したがって skills の説明文は「何ができるか」だけでなく「いつ呼ぶべきでないか」まで書く必要がある。
我々の運用では、ユーザー向けの操作点は commands に寄せ、内部処理や共通ユーティリティは skills として隠蔽している。例えば `/review` というコマンドの裏で `style-check` と `security-scan` という二つの skill が連携する設計である。この分離により、ユーザー体験を崩さずにモデル側の判断を拡張できる。
Hooks による決定論の注入
SDK で最も価値が高いと感じているのが hooks である。LLM の出力は確率的だが、hooks は決定論的に割り込める。特に `PreToolUse` で危険なコマンドを遮断し、`PostToolUse` で監査ログを残すパターンは、企業導入の要件を満たすうえで欠かせない。詳細は次稿で扱うが、SDK としては hooks の戻り値が実行継続に影響する設計になっている点が重要だ。ゼロ以外の終了コードで処理を中断できる。
Subagents と文脈分離
subagents は、メインセッションの文脈を汚さずに専門処理を走らせるための機構である。長い調査や複雑なリファクタリングを subagent に委譲すると、メインの会話履歴が保たれトークン消費も抑えられる。定義ファイルには system prompt と利用可能ツールのスコープを記述し、呼び出し側はタスクを渡すだけでよい。
合成の設計原則
四要素を合成する際の原則として、我々は「入口は一つ、責務は分散」という指針を採用している。ユーザーが触れるのは commands のみ、その裏で skills が実装を担い、hooks が安全性を保証し、subagents が重い処理を肩代わりする。この構造を守れば、プラグインが成長してもマニフェストの可読性は維持できる。
まとめ
Claude Code の SDK は、宣言的マニフェストと実行ファイルの分離によって、拡張性と保守性を両立している。まずは小さな command から始め、需要に応じて skills と hooks を追加するのが、社内展開の現実的な経路である。