🤔

Claude Codeのスキル（Skills）とサブエージェントの違いについて

に公開
Claude
Claude Code
tech

１．はじめに

Claude Code の「スキル（Skills）」と「サブエージェント」の違いについてよくわからなかったので、自分なりにまとめてみました。
https://code.claude.com/docs/ja/skills
https://code.claude.com/docs/ja/sub-agents

２．主な違い

■ 役割／状態の管理方法／コンテキスト

スキルは Claude Code にとっての「マニュアル」に近いもので、「メインセッション内で全て完結」します。
サブエージェントは Claude Code にとっての「専門スタッフ」で、「メインセッションとは別の独立したセッション」で動きます。

スキル サブエージェント
Claude Code にとって マニュアルに近い 独立した専門スタッフ
実行場所 メインセッション内 メインセッションとは別の独立したセッション
コンテキスト メインセッション内で共有 メインセッションとは別の独立したコンテキスト
状態管理 メインセッションの一部 独立した状態を持つ

具体例で表現すると下記のようなイメージです。

＜スキルとして実装＞

  1. ユーザー: 「このコードをレビューして」
  2. Claude Code（メインセッション）：スキルの指示を読む
  3. Claude Code（メインセッション）：「わかりました。・・・」
  4. Claude Code（メインセッション）：スキルの指示に従いファイルを読んで直接レビュー
  5. ユーザーに結果を返す

＜サブエージェントとして実装した場合＞

  1. ユーザー: 「このコードをレビューして」
  2. Claude Code（メインセッション）: 「レビュー用サブエージェントに委譲します」
  3. サブエージェント（独立した別セッション）: 新しいコンテキストで起動
  4. サブエージェント（独立した別セッション）: ファイルを読んでレビュー
  5. サブエージェント（独立した別セッション）: 結果をまとめる
  6. Claude Code（メインセッション）: サブエージェントから結果を受け取る
  7. ユーザーに結果を返す

３．ファイル構造の違い

■ ファイルの配置場所

スキル

スキルでは「SKILL.md」に加えてスキルを使用する際の補助ツールなどを含めることができます。
https://code.claude.com/docs/ja/skills#サポート-ファイルを追加する

.claude/skills/my-skill/
├── SKILL.md          # 必須：指示とガイダンス
├── reference.md      # オプション：詳細なドキュメント
├── examples.md       # オプション：使用例
└── scripts/          # オプション：補助ツール
│   └── helper.py
└── templates/
    └── template.txt  # オプション：テンプレート

サブエージェント

サブエージェントではサブエージェント用ファイル（my-agent.md）のみ配置します。
https://code.claude.com/docs/ja/sub-agents#ファイルの場所

.claude/agents/
└── my-agent.md

■ 設定ファイルの違い

スキル（SKILL.md）

エージェントと違ってモデルの指定はできないようです。
（おそらくメインセッションに依存するからだと思います。）
また、スキル内容は Claude Code にとっての「マニュアル」を定義します。

https://code.claude.com/docs/ja/skills#skill-md-を作成する

SKILL.md
---
name: スキル名
description: スキル説明
allowed-tools: スキルで許可するツール（Read, Grep, Globなど）
---

# スキル概要
・・・

## スキル詳細
主にClaude Codeのためのガイドラインを定義

サブエージェント（my-agent.md）

サブエージェントは独立したセッションで実行されるためモデルの指定が可能です。
また、サブエージェント内容は AI エージェントとしての「パーソナリティ的側面」を定義します。
（エージェントのペルソナを考えるイメージです）
https://code.claude.com/docs/ja/sub-agents#ファイル形式

agent.md
---
name: サブエージェント名
description: サブエージェント説明
tools: サブエージェントで許可するツール
model: モデル名（sonnetなど）
---

主に独立したAIエージェントとしてのパーソナリティを定義

４．併用について

■ 併用する場合

スキルとサブエージェントは排他的なものではないので併用することもできます。
併用する場合は王道的ですが次のような流れで使えると思います。

  1. スキルで基本的なガイドラインとベストプラクティスを提供
  2. サブエージェントで複雑なタスクを専門的に処理
  3. スキルで提供されたガイドラインに従って、サブエージェントを実行

また、併用のメリットととして次のメリットがあると感じました。

  • 役割分担の明確化：スキルで「知識」、サブエージェントで「実行」を分離
  • コンテキスト最適化：スキルはメインコンテキストで、複雑なタスクはサブエージェント実行でメインコンテキストの圧迫を回避できます
  • 処理の効率化：単純なタスクはスキルで高速に、複雑なタスクはサブエージェントで専門的に処理させる

■ 併用しない場合

併用しない場合は下記のような使い分けができると感じました。

ユースケース スキル サブエージェント
コンテキストを節約したい ❌ ⭕
応答時間が速い ⭕ ❌（起動時間あるため）
知識・ガイダンス提供する ⭕ ❌
独立したタスク実行する ❌ ⭕

併用しない場合でどちらか迷った場合はこんな風に選ぶかんじですかね？

タスクが来た
↓
軽量でシンプルなタスクか？
├─ YES → スキル
└─ NO
    ↓
    独立したコンテキストが必要？
    ├─ YES → サブエージェント
    └─ NO
        ↓
        複雑な多段階処理？
        ├─ YES → サブエージェント
        └─ NO → スキル

Discussion