Claude Code Skills と Subagents：ワークフローの再利用とコンテキストの隔離

Skill はオンデマンドで読み込めるドメイン知識や繰り返しのワークフローであり、API 規約、リリースフロー、定型のトラブルシューティング手順に適している。Subagent は独立したコンテキストとツール群を持つエージェントで、大量のファイル読み込み、専門的なレビュー、並列調査に適している。

リアルタイムの外部システムが必要な場合のみ MCP を使い、ライフサイクルで確実に実行させたい場合は Hooks を使う。短いプロンプトひとつのために拡張一式を作らない。

プロジェクト Skill は .claude/skills/<name>/SKILL.md にある。frontmatter は少なくとも明確な名称と説明を提供し、Claude がいつ読み込むべきか判断できるようにする。本文にはプロジェクト固有のルール、手順、検証方法を記載する。

説明にはトリガーシーンを記し、本文には実行に必要な内容だけを残す。大量の参考資料は Skill ディレクトリ内の別ファイルに切り分け、Claude がオンデマンドで読み込めるようにする。

Skill は Issue の読み込みからテスト、PR の作成までの完全なフローを記述できる。リリース、コミット、外部書き込みの副作用を持つ Skill は、意味の類似性だけでモデルに自動トリガーされないようにすべきである。

手動呼び出しを使えば、パラメータは $ARGUMENTS を経由してワークフローに入る。スクリプトには引き続き権限承認が必要で、Skill 自体が Claude Code のセキュリティルールを回避することはない。

カスタム Subagent は .claude/agents/ に置き、frontmatter で名称、説明、モデル、使用可能なツールを定義する。独立したコンテキストで動作し、最終的に精緻化された結果をメインセッションに返す。

ツール権限はタスクに応じて最小化すべきである。コードレビューのみを行うエージェントは通常 Read、Grep、Glob が必要で、実際に検証を実行する場合にのみ制限付き Bash を追加する。

委譲に適したタスクは、明確な問題、スコープ、戻り値のフォーマットを持つべきである。例えば token refresh パスの特定や、PLAN.md に従って現在の diff のみをレビューするなど。メインエージェントはサブエージェントが読んだすべてのファイルを受け取る必要はない。

実装後の独立レビューは新しいコンテキストを使うことで、エージェントが自身の案を擁護する傾向を減らせる。ただしレビューのプロンプトは真に正確性に関する問題に限定し、発見を産出するために過剰に設計しないようにする。

Skill と Subagent ファイルはコードレビューに含め、代表的なタスクで正しくトリガーされるか、ツールの境界が守られているかを検証する。説明が広すぎると誤トリガーし、本文が長すぎるとコンテキストが増える。

サブエージェントは独立したコンテキストを持つが、それでも token を消費し、並列でファイルを変更する可能性がある。デフォルトでは調査エージェントを読み取り専用にし、並列編集が必要な場合は独立した worktree を使用し、ファイルの所有権を明確にする。