Claude Agents まわりの仕様整理

Claude Code には「Agent っぽいもの」が複数あって、似た名前で別物。混同するとオーケストレーションを設計できないので、現時点（2026-05）の役割分担を一度メモしておく。

5 つのレイヤー

| レイヤー | 何 | 配置 | 起動方法 | |---|---|---|---| | Slash command | テキスト展開 + 任意ツール許可。/foo で再利用 | .claude/commands/*.md | ユーザーが / を打つ | | Skill | 「やり方」のドキュメント + 補助スクリプト。条件で自動発火 | .claude/skills/<name>/SKILL.md | description にマッチで auto-trigger、または明示呼出 | | Sub-agent | 別 context window で動く専門エージェント | .claude/agents/*.md | 親が Task / Agent ツールで spawn | | Hook | tool イベント前後に実行されるシェル | .claude/settings.json | 自動（PreToolUse / PostToolUse / Stop / SessionStart 等） | | MCP server | 外部 API を tool として exposure | .mcp.json | session start で接続 |

「Claude Agents = sub-agents」と思いがちだが、Skills と Slash command と Hook は別物。並列実行・コンテキスト隔離をしたい時は sub-agent、条件で自動的に発火する手順は Skill、毎回手で打つ短縮は Slash command、tool 呼び出しに対する自動処理は Hook。

Sub-agent の正体

.claude/agents/<name>.md は frontmatter + 指示書。

---
name: explore
description: Fast read-only search agent. Use to locate code.
model: sonnet            # opus / sonnet / haiku / inherit
tools: Glob, Grep, Read  # 省略時は parent と同じ
---
あなたは ... をする agent です。...

ポイント:

  • 別 context window で動く。親の履歴は見えない。だから「グレップして 200 件出てきても親の文脈を汚さない」
  • 親は Task ツールで subagent_type: explore を渡して起動。prompt が唯一の入力
  • 戻り値は 1 メッセージのみ（親はそれだけ見る）
  • isolation: "worktree" を渡すと git worktree も自動作成、ファイル編集を物理隔離できる
  • 複数 sub-agent を 1 メッセージ内で並列起動できる。これがオーケストレーションの基盤

Skill との違い

Skill は description が条件に当たると自動で「使い方説明書」を context に注入する。コードは実行しない（必要なら同梱スクリプトを Bash で呼ぶ）。Sub-agent は独立 LLM 呼び出しで実際に動く。

→ Skill は「Claude が忘れちゃいけないやり方」、Sub-agent は「重い作業を別空間に投げる手段」。

Hook の使いどころ

settings.json の hooks で PreToolUse / PostToolUse / Stop / SessionStart 等に bash を指定。

  • PostToolUse(Edit|Write) で prettier 自動実行
  • Stop で session-save / auto-commit
  • SessionStart で日付・ブランチ・最新コミット表示
  • PreCompact で重要ルール再注入

Hook は LLM ではなくシェル。確実性が要るルールはここに置く。

ECC（everything claudecode）的に統合する時の見方

  • 「複雑なロジックをやらせたい」→ sub-agent
  • 「いつも忘れる手順を覚えさせたい」→ Skill
  • 「決まった文言を再利用したい」→ Slash command
  • 「ツールコールに自動処理を挟みたい」→ Hook
  • 「外部 API を tool 化したい」→ MCP

この 5 つを .claude/ 配下に揃えると、1 セッションが小さい IDE のように振る舞いはじめる。

まだ詰めきれていない部分

  • Sub-agent から sub-agent を spawn する時のコスト感（深くするほど指数で予算が飛ぶ）
  • Skill auto-trigger の精度。description を雑に書くと発火しない／逆に効きすぎる
  • Hook と Skill の責務境界。「自動 commit は Hook、自動 review は Skill」が今の落としどころ
  • Sub-agent と Background job の差。bg は親と context を共有する別プロセス、sub-agent は別 LLM。混ぜない

参考・引用元

2026-05-20

関連ノート