Claude CodeのSkills, Custom Subagents, Dynamic Workflowsを整理

はじめに

Claude Codeには、開発作業を効率化するための拡張機能としてSkills、Custom Subagents、Dynamic Workflowsの3つの仕組みが用意されています。

これらはどれも「Claude Codeにできることを増やす」という目的は共通していますが、それぞれ特徴や向いている用途が異なります。

本記事では、それぞれの仕組みの概要と使い方、そして3つの違いを整理し、どのような場面でどれを使うべきかの判断材料をまとめます。

Skillsとは

SkillsはClaude Codeに特定のタスクを実行するための手順や、知識をパッケージとして一つにまとめて登録し、Claude Codeから実行できるように仕組みです。

• Anthropic公式: ClaudeにSkillsを拡張する

ユースケース

Anthropicのブログではスキルのユースケースとして以下の9種類のスキルが代表例として紹介されています。

• Anthropic公式ブログ: Skillsの用途

1. ライブラリおよびAPI参照

ライブラリ、CLI、SDKの正しい使い方を知識としてClaude Codeに教えるためのスキルです。
内製したソフトウェアなどClaudeモデルにナレッジがないライブラリ、CLI、SDKを使用する際に、使い方や避けるべき落とし穴などを記載することで、 Claude Codeが正しくライブラリ、CLI、SDKを使用できるようなります。

• 代表的なスキル例：
  • billing-lib: 社内請求ライブラリ:エッジケース(境界値入力時のケース、例外ケース)、フットガン(間違った使い方)など。
  • internal-platform-cli: 内製CLIラッパーのすべてのサブコマンドに、いつ使うべきかの例付きです。
  • sandbox-proxy: 開発作業のための社内ネットワークの設定情報:どのホストに到達可能か、「接続拒否」エラーのデバッグ方法、許可リストエントリの追加方法。

2. プロダクトバリデーション

コードが正しく動くかを自動でテスト・検証するための知識、手順を登録するスキルです。
スキル内にスクリプトを組み込み、テストの実行状況を動画を録画して、何がテストされたかを可視化したり、各ステップで結果をプログラム的にチェックさせることが可能になります。

• 代表的なスキル例：
  • signup-flow-driver
    • サインイン → メール検証 → オンボーディングをヘッドレスブラウザで実行し、各ステップで状態をチェック
  • checkout-verifier
    • Stripe のテストカードで決済 UI を操作し、請求書が正しい州に送られるか確認
  • tmux-cli-driver
    • TTY が必要な CLI のインタラクティブテストを自動化

3. データ取得と解析

プロダクトのデータ基盤（DWH、ログ、モニタリングツール）と Claude をつなぎ、 「必要なデータを正しく取得し、分析できるようにする」 させるためのスキルです。

以下のような情報を指定します。

• データ取得時に使用する認証情報付きのデータ取得ライブラリ

• 使用するダッシュボードのID、テーブル、メトリクスなどの 正しい参照方法を教える

• 分析ワークフロー（ファネル、コホート、保持率など）

• 代表的なスキル例：

  • funnel-query
    • イベント参加したユーザーのうち課金者の割合をファネル分析を自動化.
    • 参照すべきテーブルなどをスキルに記載
  • grafana
    • データソースのUID、クラスタ名、問題 -> ダッシュボードのルックアップテーブル

4. ビジネスプロセスとチームの自動化

進捗報告などチーム内の定型作業を一つのコマンドで自動化するスキルです。

これらのスキルに関しては、過去の結果をログファイルに保存することで、モデルが一貫性を保ち、ワークフローの過去の実行を反映するのに役立ちます。

• 代表的なスキル例：
  • standup-post: チケットトラッカー、GitHubの活動、過去のSlackなどから差分算出し、定型的な進捗報告(スタンドアップ)する
  • create--ticket: 必要フィールドの設定してチケット作成、作成後のワークフロー(レビュアーへの通知、Slackにリンク投稿など)を実施
  • weekly-recap: マージされたPR+クローズドチケット+デプロイなどから1週間の活動状況をまとめて報告

5. コードのスキャフォールディングとテンプレート

新しいコードの土台（scaffold）や雛形(template)を、組織仕様に合わせて生成するスキル。

• 代表的なスキル例：
  • new--workflow— 注釈で新しいサービス/ワークフロー/ハンドラーをスキャフォールドする
  • new-migration— あなたの移行ファイルテンプレートと一般的な落とし穴
  • create-app— 認証、ログ、デプロイ設定が事前に配線された新しい内部アプリ

6. コード品質とレビュー

コード品質を維持し、レビューを強化するためのスキル群。 このスキルは決定論的スクリプトや自動化ツールを含み、Git hooks や GitHub Actions に組み込み、自動で実行することを想定しています。

• 代表的なスキル例：

  • adversarial-review

    • サブエージェントを新規に生成
    • コードを批評 → 修正 → 再批評を繰り返す
    • 指摘が「細かい指摘レベル」まで減衰するまで継続

  • code-style

    • 組織独自のコードスタイルを強制
    • 特に「Claude がデフォルトで苦手なスタイル」を補正

  • testing-practices

    • 「何をテストすべきか」「どう書くべきか」のガイドライン

7. CI/CDと展開

これらはコードベース内でコードを取得・プッシュ・デプロイするのに役立つスキルです。
これらのスキルは、データ収集のために他のスキルを参照することもあります。

• 代表的なスキル例：
  • babysit-pr : PRを監視し、不安定なCIをリトライ、マージの競合を解決、自動マージを有効。
  • deploy- : デプロイ前後のエラーレート比較し、問題があれば自動ロールバックや、段階的なデプロイの構築する。
  • cherry-pick-prod : テンプレート付きPR、コンフリクト解決、独立したワークツリーでの作業

8. ランブック

Slackスレッド、アラート、エラーシグネチャーなどをもとに、ツールによる障害の調査を進め、構造化されたレポートを作成するスキルです。

• 代表的なスキル例：
  • -debugging 特定サービスの障害 → 調査に使用すべきツールやクエリパターンをマッピングする
  • oncall-runner アラートを取得し、問題点を確認し、発見、フォーマットする
  • log-correlator リクエストIDをもとに、それに触れた可能性のあるすべてのシステムから対応するログを取得

9. インフラ運用

定期的なメンテナンスや運用手順を実行するスキル。
危険な作業もユーザーの確認などガードレールを設定した上で、実行が可能。

• 代表的なスキル例：
  • -orphans 孤立ポッドを、ユーザーが確認した上でクリーンアップ
  • dependency-management 組織の依存承認ワークフロー
  • cost-investigation コストの増加要因を分析

Skillsの使い方

Skillsの中身はスキルの実行タイミングや、手順を記載したSKILL.mdファイルや、スキルの実行時に使用するスクリプトなどから構成されるフォルダです。

.claude/skills/配下にSKILL.mdを含むフォルダを配置することで、ClaudeがSkillとして認識します。

# Skillsフォルダの例

my-skill/
├── SKILL.md # スキルの実行タイミングや実行手順を記載
├── template.md # Claude が記入するためのテンプレート
├── examples/
│ └── sample.md # 出力の例
└── scripts/
└── hogehoge.sh # スキルの実行時に実行するスクリプト

Skillの作成はClaude Codeの/skill-creatorコマンドを使って、Claude Code自体に作成させることもできます。

SKILL.mdの記載例

SKILL.mdはSkills用の専用プロパティをyaml形式で指定するフロントマター部分と、フリーフォーマットで記載できるボディ部分から構成されます。

フロントマターに指定できる項目として以下のような項目があります。

• Anthropic公式: ClaudeにSkillsを拡張する
• Anthropic公式: プレースホルダーを用いた動的引数
• Anthropic公式: Path固有のルール
• Anthropic公式: Toolsリファレンス

以下はフロントマターの例です。

---
name: my-todo-skill
description: ファイルからTODOを抽出して一覧を作るスキル。短い説明を先頭に書くこと。
when_to_use: 'タスクを一覧化して' のようなリクエストがあったとき
argument-hint: [path] [format]
allowed-tools: Read, Write, Edit, Glob, Grep
hooks:
  Stop:
    - matcher: "*"
      hooks:
        - type: command
          command: echo "Hook fired at $(date)" > /tmp/hook-test.txt
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

以下はAPIを設計する際に必要な “規約・ガイドライン” を 知識としてClaudeに登録するためのスキル。

---
name: api-conventions
description: このコードベースにおける API 設計パターン
---

API エンドポイントを書くときは:

RESTful な命名規則を使う
一貫したエラーフォーマットを返す
リクエストバリデーションを含める

以下は、アプリケーションをデプロイする手順を登録するスキルです。

---
name: deploy
description: アプリケーションを本番環境にデプロイする
context: fork
disable-model-invocation: true
---

アプリケーションのデプロイ手順：

1. テストスイートを実行する
2. アプリケーションをビルドする
3. デプロイ先へプッシュする

Skillsの実行方法

登録したSkillsはSKILL.mdの内容に基づいて、必要なタイミングやClaude Codeから自動的に呼び出させるようになります。
また、/スキル名のスラッシュコマンドを実行することで、ユーザーが任意のタイミングで実行することもできます。

カスタムサブエージェント

Claude Codeのカスタムサブエージェントは、.claude/agents/ディレクトリにMarkdownファイルを配置するだけで、特定のタスクに特化した専用AIワーカーを定義できる機能です。 使用するモデルやツール（Read, Edit, Bash, Grep, Globなど）を個別に分けることができます。

/agentsコマンドからClaudeに説明を入力するだけで設定ファイルを自動生成してくれるため、初めての方でも始めやすい設計となっています。

• Anthropic公式: カスタムサブエージェント
• Anthropic公式: マルチエージェント連携パターン
• GitHubリポジトリ: awesome-claude-code-subagents

サブエージェントのメリット

特定タスクに特化させることで高い回答精度を得る

何でもできる汎用アシスタントではなく、「あなたはAzureに関する専門家です」のように、特定のタスクに特化した専用の指示を与えることができます。
これにより、対象領域における回答精度が向上します。

モデルを指定することでコストを制御できる

サブエージェントはモデルを個別に指定でき、用途に応じて使い分けることができます。
簡単なタスクには低コストモデル（Haiku等）、仕様設計には高性能なOpusを割り当てるといったコスト最適化が可能です。

コンテキストを分離できる

調査・実装・レビューなど複数のタスクについてCLAUDE.mdにプロンプトで指示をすると、コンテキストウィンドウの汚染が起きやすくなります。

コンテキストウィンドウの汚染（Context Contamination）とは、LLMが一度に処理・記憶できる情報の枠（コンテキストウィンドウ）に、無関係な情報やAI自身の誤った出力などが蓄積し、ハルシネーションや忘却が発生して応答品質が低下する現象です。

サブエージェントで処理を分離することでメインのセッションとコンテキストウィンドウが分割されるため、コンテキストウィンドウの汚染を抑止できます。
また、forkコマンドを使うと、その時点までのメイン会話の履歴をすべて引き継いで起動することができます。

ユースケース

カスタムサブエージェントは、特定の役割に特化させることで高い精度を発揮します。
以下に代表的なユースケースをまとめます。

1. コードレビュー

コードの品質、セキュリティ、ベストプラクティスを専門的にレビューするサブエージェントです。
コミット前の確認やPRのレビュー時に活用します。ツールをRead、Grep、Globに制限することで、読み取り専用の安全なレビューが可能です。
また、memory: projectを設定することで、プロジェクト固有のコーディングパターンや繰り返し発見される問題を記憶し、レビュー精度が継続的に向上します。

• 代表的なエージェント例：
  • code-reviewer: 変更されたコードを対象に、正確性・セキュリティ・パフォーマンス・保守性を多角的にレビュー。Haikuなどの低コストモデルを割り当ててコストを抑えつつ、十分な精度を確保。
  • adversarial-reviewer: コードを意図的に批判する視点でレビューし、見落としを防ぐ。

2. 記事・ドキュメントの作成・レビュー

ブログ記事や技術ドキュメントの作成、編集、プロジェクト規約への準拠確認を行うサブエージェントです。
フロントマターのバリデーション、タグやカテゴリの標準リストとの照合、Markdown記法のチェックなど、プロジェクト固有のルールを適用します。

• 代表的なエージェント例：
  • article-reviewer: Hugoブログプロジェクトの規約に基づき、記事の作成・編集・レビューを行う。フロントマターの形式チェック、タグ・カテゴリの検証、画像パスの確認などを自動実施。

3. デバッグ・障害調査

エラーメッセージの分析、スタックトレースの追跡、根本原因の特定を行うサブエージェントです。
Read、Edit、Bash、Grep、Globなど幅広いツールを許可し、ログの確認や仮説検証を通じて問題を解決に導きます。

• 代表的なエージェント例：
  • debugger: エラーメッセージとスタックトレースから原因を特定し、最小限の修正を実装して検証まで行う。
  • incident-responder: アラートを受け取り、関連ログを相関分析して構造化レポートを作成。

4. データ分析・クエリ実行

SQLクエリの作成、BigQueryなどのデータ基盤との連携、データの取得と分析を行うサブエージェントです。
ツールをBashに制限し、フックでクエリの安全性を検証する仕組みを組み込むことで、意図しないデータ変更を防止できます。

• 代表的なエージェント例：
  • data-scientist: SQLやBigQueryを用いたデータ分析を専門に実行。Sonnetなどの高性能モデルを割り当て、複雑な分析にも対応。
  • db-reader: 読み取り専用のデータベースクエリを実行。フックでINSERT/UPDATE/DELETEをブロックし、安全にデータを参照。

5. セキュリティ監査

コードベースの脆弱性スキャン、依存関係のセキュリティリスク評価、OWASP Top 10に基づく監査を行うサブエージェントです。
読み取り専用のツールに制限し、コードを変更せずにレポートのみを出力する設計が一般的です。

• 代表的なエージェント例：
  • security-auditor: インジェクション脆弱性、認証の欠陥、不適切なデータ検証などをスキャンし、重大度付きのレポートを作成。

6. テスト自動化

テストコードの生成、テストスイートの実行、カバレッジの分析を行うサブエージェントです。
Bash、Read、Edit、Writeなどのツールを許可し、テストファイルの作成から実行、結果の分析までを一貫して実行します。

• 代表的なエージェント例：
  • test-engineer: テストすべきパスを特定し、ユニットテスト・統合テストを自動生成。カバレッジのギャップを検出してレポート。

サブエージェントファイルの例

サブエージェントファイルはSkillsと同様にフロントマター部分とフリーフォーマットのボディ部分からなります。

---
name: code-reviewer
description: コードの品質とベストプラクティスをレビューする
tools: Read,Glob,Grep
model: sonnet
---

あなたはコードレビュー担当者です。  
呼び出された際には、コードを分析し、品質・セキュリティ・ベストプラクティスに関する具体的で実行可能なフィードバックを提供します。

フロントマターの定義

サブエージェントのフロントマターに指定できる項目は以下のとおりです。

memory: projectを活用したレビューの精度向上

コードレビューエージェントにmemory: projectを設定しておくと、レビューのたびにプロジェクト特有のコーディングパターンや繰り返し発見される問題点をMEMORY.mdに記録していきます。
次回のレビュー時にはその知識を踏まえた指摘ができるようになり、継続的にレビュー精度が向上します。

• SERVERWORKSブログ: Claude Codeのカスタムサブエージェント入門ガイド

Dynamic Workflowsとは

Dynamic Workflowsは、複数のサブエージェントを制御するJavaScriptスクリプトを自動生成し、タスクをステップバイステップに分解して複数のサブエージェントを同時に動作させる仕組みです。
Deep Researchのような、複数のエージェントが並列で調査・検証を行い、統合された高品質な回答を提供する仕組みをClaude Code上で実現できます。

具体的な流れは以下の通りです。

1. ユーザーがプロンプトを入力する
2. Claudeがタスクをステップバイステップに分解し、JavaScriptスクリプト（Workflow）を自動生成する
3. スクリプトに基づいて複数のサブエージェントが同時に動作する
4. 各エージェントの出力の整合性をAIがチェックした上で統合し、品質が担保された最終回答をユーザーに提供する

• Anthropic公式: Workflows

ユースケース

• 大規模コードの解析やリファクタリング
• 複数ファイルにまたがるバグ調査
• コードの包括的なセキュリティレビュー

メリット

• 応答が早い：中間結果を必要なときに必要な分だけ参照し、複数のサブエージェントが同時動作するため、応答が早い
• 回答の品質が高い：複数のサブエージェントが動作し、別のエージェントの出力を検証（Adversarial Verify）する仕組みを組み込めるため、最終的な回答の品質が高い

デメリット

• 消費トークンが大きい：複数のエージェントを起動するため、単一のエージェントやSkillと比較して消費トークンは大きい

pipeline と parallel

Workflowのスクリプトでは、サブエージェントの実行方法としてpipelineとparallelの2種類の制御構造を利用できます。

• pipeline：終わったものから次のステップに流す、ライン作業方式です。
  • 各アイテムがステージごとに独立して処理されるため、早く終わったアイテムは待機時間なく次に進みます。
• parallel：全員の結果が揃うまで待機するバリア方式です。
  • 全サブエージェントの完了を待ってから次の処理に進むため、ステージ間で全結果を一度に参照したい場合に適しています。

Skills, Custom Subagents, Dynamic Workflowsとの違い

• SkillsはClaudeに対して特定のタスクを実行するための手順や知識を追加する仕組みです。
  • コンテキストの分離やモデルの選択ができないため、より具体的な単発のタスクを実行させたい場合に使用します。
• Custom Subagentsは特定の分野のタスクに幅広く対応させる場合に使用します。
  • コンテキストの分離やモデルの選択が可能です。
• Dynamic Workflowsは次に実行するタスクをスクリプト自身が自律的に決定する点が最大の違いです。
  • 中間結果を変数に保持し、必要なときに必要な分だけ各ステップで受け渡すため、サブエージェントのように中間結果が会話コンテキストに残って肥大化し応答が遅くなる問題を回避できます。中〜大規模タスクに向いています。

おわりに

本記事では、Claude Codeの拡張機能であるSkills、Custom Subagents、Dynamic Workflowsの3つについて、それぞれの概要と特徴、違いを整理しました。

選び方のポイントを改めてまとめると以下のようになります。

• まずはSkillsから始める。特定のタスクの手順や知識をClaudeに教えたい場合に最も手軽です。
• コンテキストの分離やモデルの使い分けが必要なタスクにはカスタムサブエージェントを検討する。
• 複数エージェントの並列実行や、中間結果を効率的に管理したい中〜大規模なタスクにはDynamic Workflowsを検討する。

Claude Codeの拡張機能を活用することで、単なるコード補完ツールから自律的にタスクを実行する開発パートナーへと活用の幅が大きく広がります。
まずは小さなSkillの作成から始めて、徐々にサブエージェントやWorkflowへと活用範囲を広げてみてはいかがでしょうか。