Claude CodeにおけるSkillとsubagentのディレクトリ構造の違い

はじめに

Claude Codeには、作業手順をまとめる Skill と、特定の役割を持たせた subagent という仕組みがあります。

どちらも「Claudeに作業ルールを渡す」という点では似ていますが、ディレクトリ構造の意味を混同すると、次のような誤解が起きやすいです。

• Skill配下に agents/ を置けば、自動でsubagentとして認識される
• references/ に置けば、自動で読まれる
• Skillが発火すれば、subagentも自動で起動する
• agents/*.md は、どこに置いても同じ意味を持つ

結論から言うと、「名前付きsubagentとして正式に登録する場所」と、「そのSkill内でsubagentに読ませるための指示ファイルとして置く場所」は別物です。

この記事では、Claude Codeを中心に、その違いを整理します。

まず結論

Skill配下に agents/ を置くこと自体はできます。

しかし、それは Claude Codeに名前付きsubagentとして自動登録される という意味ではありません。

Skill配下の agents/
→ Skillに同梱された補助ファイル
→ SKILL.md から明示的に参照すれば使える
→ ただし、名前付きsubagentとして自動登録されるわけではない

一方で、Claude Codeに正式なsubagentとして認識させたい場合は、専用の配置場所に置く必要があります。

Claude Code の名前付きsubagent
→ .claude/agents/*.md
→ ~/.claude/agents/*.md

つまり、同じ agents という名前が出てきても、どこに置くかで意味が変わるということです。

Claude CodeのSkillの基本構造

Claude CodeのSkillは、基本的に SKILL.md を持つディレクトリです。

.claude/skills/impact-analysis/
├── SKILL.md
├── references/
│   └── review-criteria.md
├── examples.md
├── scripts/
│   └── validate-impact-report.sh
└── templates/
    └── impact-report.md

SKILL.md には、Skillの名前・説明・作業手順を書きます。

---
name: impact-analysis
description: 影響調査レポートを作成・レビューするときに使うSkill
---

# Impact Analysis

影響調査では、変更点、影響範囲、確認観点、未確認事項を整理してください。

Skill配下には、補助ファイルとして次のようなものを置けます。

配置場所	役割
SKILL.md	Skill本体
references/	詳細な判断基準・仕様
examples.md	入出力例・良い例/悪い例
scripts/	検証・抽出・実行用スクリプト
templates/	レポートやコメントの雛形
assets/	画像・テンプレートなどの素材

ただし、ここで重要なのは、補助ファイルは置いただけで常に読まれるわけではないという点です。

SKILL.md から、どの場面でどのファイルを読むかを明示しておくのが安全です。

## Reference files

- `references/review-criteria.md` — 影響調査結果をレビューするときに読む
- `examples.md` — 出力例に迷ったときに読む
- `templates/impact-report.md` — 最終レポートを作成するときに使う

Claude Codeの正式なsubagent定義

Claude Codeで、名前付きsubagentとして正式に認識させたい場合は、次の場所に置きます。

.claude/agents/
~/.claude/agents/

たとえばプロジェクト内にレビュー用subagentを置くなら、こうです。

.claude/
└── agents/
    └── impact-reviewer.md

impact-reviewer.md は、Claude Codeから独立したsubagentとして扱われます。

---
name: impact-reviewer
description: 影響調査結果の抜け漏れ、根拠不足、未確認事項をレビューする
tools: Read, Grep, Glob
---

あなたは影響調査レビュー担当です。
影響範囲、根拠、未確認事項、テスト観点の抜け漏れを確認してください。

このように置いた場合、impact-reviewer はClaude Codeの名前付きsubagentとして扱えます。

Skill配下に agents/ を置いた場合

では、次のようにSkill配下に agents/ を置いた場合はどうなるでしょうか。

.claude/skills/impact-analysis/
├── SKILL.md
└── agents/
    └── impact-reviewer.md

この agents/impact-reviewer.md は、Claude Codeの名前付きsubagentとして自動登録されるわけではありません。

つまり、次の配置とは意味が違います。

.claude/agents/impact-reviewer.md

整理するとこうです。

.claude/agents/impact-reviewer.md
→ Claude Codeに名前付きsubagentとして登録される

.claude/skills/impact-analysis/agents/impact-reviewer.md
→ impact-analysis Skillに同梱された補助ファイル
→ SKILL.md から参照すれば、subagent用の指示ファイルとして使える

したがって、Skill配下の agents/ は無意味ではありません。

ただし、SKILL.md から明示的に参照しないと、使われない可能性が高いです。

## Subagent instructions

出力のレビューが必要な場合は、`agents/impact-reviewer.md` を読んでください。
subagentが使える環境では、このファイルの内容をreviewer subagentへの指示として使ってください。
subagentが使えない環境では、同じ指示に従ってinlineでレビューしてください。

このように書けば、Skill配下の agents/impact-reviewer.md は、そのSkill専用のsubagent指示ファイルとして使えます。

Skill配下の agents/ と references/ に機能差はあるのか

ここは誤解しやすいポイントです。

Skill配下に置く補助ファイルとして見る限り、agents/ と references/ に本質的な機能差があるわけではありません。

たとえば、次のように references/ に置いたとしても、SKILL.md 側で「レビュー担当subagentに読ませるための役割プロンプトとして使う」と明示すれば、同じような使い方ができます。

.claude/skills/impact-analysis/
└── references/
    └── impact-reviewer.md

レビューが必要な場合は、`references/impact-reviewer.md` を読んでください。
subagentが使える環境では、このファイルの内容をreviewer subagentへの指示として使ってください。
subagentが使えない環境では、同じ指示に従ってinlineでレビューしてください。

一方で、次のように agents/ に置くこともできます。

.claude/skills/impact-analysis/
└── agents/
    └── impact-reviewer.md

レビューが必要な場合は、`agents/impact-reviewer.md` を読んでください。
subagentが使える環境では、このファイルの内容をreviewer subagentへの指示として使ってください。
subagentが使えない環境では、同じ指示に従ってinlineでレビューしてください。

この2つは、Claude Codeにとって「名前付きsubagentとして登録されるか」という意味ではどちらも同じです。

どちらも、.claude/agents/ に置かれていない限り、正式な名前付きsubagentとして自動登録されるわけではありません。

違いがあるとすれば、主に人間とモデルに対する意味づけです。

references/
→ 仕様・判断基準・チェックリスト・詳細手順として見せたい

agents/
→ subagentに読ませる役割プロンプトとして見せたい

つまり、Skill配下の agents/ は、Claude Codeにsubagentとして自動登録するための場所ではありません。

あくまで、そのSkillに同梱するsubagent向けのローカルな指示ファイル置き場として使う、という位置づけです。

したがって、agents/ というディレクトリ名そのものに特別な魔法があるわけではありません。

重要なのは、SKILL.md に「いつ、どのファイルを、何のために読むのか」を明示することです。

「名前付きsubagentとして認識される」とは何か

ここでいう「名前付きsubagentとして認識される」とは、Claude Codeがそのファイルをsubagent定義として読み込み、利用可能なsubagentの1つとして扱うという意味です。

たとえば、次のように配置します。

.claude/
└── agents/
    └── impact-reviewer.md

この場合、impact-reviewer.md のfrontmatterに書かれた name や description が、Claude Codeのsubagent定義として扱われます。

---
name: impact-reviewer
description: 影響調査結果の抜け漏れ、根拠不足、未確認事項をレビューする
tools: Read, Grep, Glob
---

あなたは影響調査レビュー担当です。

正式なsubagentとして認識されると、主に次のような意味があります。

• /agents で管理・確認できる
• Claudeが description を見て、適切な場面でそのsubagentに委譲できる
• ユーザーが自然言語で「impact-reviewer agentを使ってレビューして」のように明示できる
• tools、model、skills などのsubagent用設定を持てる
• メイン会話とは別のコンテキストで実行され、結果だけを返せる

ここで注意したいのは、/impact-reviewer のようなスラッシュコマンドとして呼び出す、という意味ではないことです。

/agents はsubagentを作成・管理するためのコマンドです。

実際に使うときは、たとえば次のように自然言語で依頼します。

impact-reviewer agentを使って、この影響調査結果をレビューしてください。

または、Claudeがタスク内容とsubagentの description を見て、必要だと判断した場合に委譲することがあります。

references/ も agents/ も、SKILL.mdからの導線が重要

ここが一番大事です。

Skill配下に補助ファイルを置いたとしても、Claudeが必ずそれを読むとは限りません。

.claude/skills/impact-analysis/
├── SKILL.md
├── references/
│   └── review-criteria.md
└── agents/
    └── impact-reviewer.md

このように置いただけでは、review-criteria.md も impact-reviewer.md も、十分に活用されない可能性があります。

そのため、SKILL.md 側に「いつ読むのか」「何のために使うのか」を書いておくのが重要です。

## Supporting files

- `references/review-criteria.md` — 影響調査結果をレビューするときに読む
- `agents/impact-reviewer.md` — レビューをsubagentに任せるときに、そのsubagentへ読ませる

さらに、手順の中にも書いておくとより明確です。

## Review process

1. 影響範囲、根拠、未確認事項を整理する
2. `references/review-criteria.md` を読んで、レビュー観点を確認する
3. 必要に応じて、`agents/impact-reviewer.md` を読ませたreviewer subagentにレビューを依頼する
4. subagentが使えない環境では、同じ指示に従ってinlineでレビューする

つまり、Skill配下の補助ファイルは、SKILL.mdから導線を張って初めて効くと考えるのが安全です。

推奨構成：共通subagentとSkill専用指示を分ける

個人的には、プロジェクト内で長く使うsubagentは .claude/agents/ に置き、Skill専用の補助プロンプトだけをSkill配下に置くのがわかりやすいです。

.claude/
├── skills/
│   └── impact-analysis/
│       ├── SKILL.md
│       ├── references/
│       │   └── review-criteria.md
│       ├── examples.md
│       ├── scripts/
│       │   └── validate-impact-report.sh
│       └── templates/
│           └── impact-report.md
└── agents/
    ├── impact-researcher.md
    ├── impact-reviewer.md
    └── impact-test-planner.md

この構成では、役割が明確です。

impact-analysis Skill
→ 影響調査の共通ルール・観点・出力フォーマット

impact-researcher subagent
→ 影響範囲を調査する担当

impact-reviewer subagent
→ 調査結果をレビューする担当

impact-test-planner subagent
→ テスト観点を整理する担当

SKILL.md には次のように書けます。

## Subagents

影響範囲の調査が必要な場合は、`impact-researcher` subagentを使ってください。
調査結果のレビューが必要な場合は、`impact-reviewer` subagentを使ってください。
テスト観点の整理が必要な場合は、`impact-test-planner` subagentを使ってください。

逆に、Skill専用のsubagent指示として同梱したい場合

共通subagentとして登録するほどではなく、そのSkillの中だけで使いたい指示であれば、Skill配下に置くのもありです。

.claude/skills/impact-analysis/
├── SKILL.md
├── references/
│   └── review-criteria.md
└── agents/
    └── impact-reviewer.md

この場合、SKILL.md には次のように書きます。

## Review with local subagent instructions

レビューが必要な場合は、`agents/impact-reviewer.md` を読んでください。
subagentが使える環境では、その内容をreviewer subagentへの指示として使ってください。
subagentが使えない環境では、同じ内容に従ってinlineでレビューしてください。

この構成のメリットは、Skillを配布するときに関連する指示ファイルも一緒にまとめられることです。

一方で、.claude/agents/ に登録されるわけではないため、他のSkillや通常作業から共通subagentとして呼び出したい場合には向いていません。

整理表

配置場所	置けるもの	意味
.claude/skills/<skill-name>/SKILL.md	Skill本体	Skillとして認識される
.claude/skills/<skill-name>/references/	詳細な判断基準・仕様	Skillの補助ドキュメントとして使える
.claude/skills/<skill-name>/examples.md	入出力例・良い例/悪い例	Skillの補助例として使える
.claude/skills/<skill-name>/scripts/	検証・抽出・実行用スクリプト	Skillから参照・実行する補助処理として使える
.claude/skills/<skill-name>/templates/	レポートやコメントの雛形	Skillの成果物テンプレートとして使える
.claude/skills/<skill-name>/agents/	任意の補助ファイル / subagent向けローカル指示	subagentとしては自動登録されないが、SKILL.md から参照すれば使える
.claude/agents/*.md	project-level subagent定義	Claude Codeの名前付きsubagentとして認識される
~/.claude/agents/*.md	user-level subagent定義	全プロジェクト共通の名前付きsubagentとして認識される

---

Codexでも考え方はほぼ同じ

ここまでClaude Codeを前提に説明しましたが、Codexでも考え方はほぼ同じです。

ただし、ディレクトリ名やファイル形式は異なります。

目的	Claude Code	Codex
プロジェクト指示	CLAUDE.md	AGENTS.md
Skill本体	.claude/skills/<skill-name>/SKILL.md	.agents/skills/<skill-name>/SKILL.md
ユーザー共通Skill	~/.claude/skills/<skill-name>/SKILL.md	~/.agents/skills/<skill-name>/SKILL.md
名前付きsubagent / custom agent	.claude/agents/*.md	.codex/agents/*.toml
ユーザー共通subagent / custom agent	~/.claude/agents/*.md	~/.codex/agents/*.toml
Skill内の補助資料	references/, scripts/, assets/ など	references/, scripts/, assets/ など
Skill内のsubagent向け指示	skills/<name>/agents/*.md など	skills/<name>/agents/*.md や subagents/*.toml など

Codexでも、Skill配下に subagents/ や agents/ を置いたとしても、それだけで正式なcustom agentとして自動登録されるわけではありません。

.agents/skills/impact-analysis/subagents/impact-reviewer.toml
→ impact-analysis Skillに同梱された補助ファイル
→ SKILL.md から参照すれば、subagent向けの指示ファイルとして使える

.codex/agents/impact-reviewer.toml
→ Codexに名前付きcustom agentとして登録される

つまり、Codexでもポイントは同じです。

正式に名前付きagentとして登録する場所
≠
Skill内でagentに読ませるための指示ファイル置き場

まとめ

今回のポイントは、置き場所によって意味が変わるということです。

Claude Codeで正式な名前付きsubagentとして登録する場所
→ .claude/agents/
→ ~/.claude/agents/

Skill内でsubagentに読ませるための指示ファイル
→ Skill配下の agents/ に置ける
→ ただし、SKILL.md から明示的に参照しないと使われにくい

つまり、次のように考えるとわかりやすいです。

.claude/agents/*.md
→ Claude Codeに登録するsubagent

.claude/skills/<skill-name>/agents/*.md
→ そのSkillに同梱するsubagent用の指示ファイル

そして、Skill配下の補助ファイルは agents/ であっても references/ であっても、SKILL.mdから導線を張ることが重要です。

この場面では、この補助ファイルを読む。
この場面では、このsubagentを使う。
subagentが使えない場合は、同じ指示に従ってinlineで処理する。

このように書いておくと、Skillとsubagentの役割が混ざらず、運用しやすくなります。