Claude Code Skills ガイド｜Skill自作7パターン+配布【2026】

「コードレビューのたびに”セキュリティ観点でもチェックして”と打ち直している…」

先日、あるチームのコードベースにClaude Codeを導入した際、こんな状況に気づきました。メンバー全員が独自の長いプロンプトをコピペして使っていて、プロジェクト固有のコンテキスト（使用しているフレームワーク、命名規則、セキュリティ要件）がセッションをまたいで引き継がれない。毎回同じことを説明し直す無駄が積み重なっていたのです。

Claude Code Skillsは、この問題を解決するために設計された仕組みです。「いつも使う専門的なワークフロー」をMarkdownファイルに書き下ろし、特定のトリガー語句でClaudeが自律的に読み込む。設定不要、APIキーなし、10分で動き始めます。

この記事では、公式仕様の全貌と、実務で使える7パターンの自作Skill実装例を、コピペ可能なコード付きで解説します。

Claude Code Skillsとは何か：CLAUDE.mdとの違い

Claude Code Skillsを正しく理解するには、Claude Codeのメモリ体系全体を把握する必要があります。公式ドキュメントによると、Claude Codeの持続的記憶は大きく3層に分かれています。

最大の違いは「常時読み込みか、オンデマンドか」です。CLAUDE.mdはセッション開始時に毎回コンテキストウィンドウに載りますが、Skillsは「あなたが呼び出した瞬間にだけ」読み込まれます。

これはコンテキスト効率の観点で非常に重要です。コードレビューのSkillはコードレビュー時だけ、ドキュメント生成Skillはドキュメントを書く時だけ発火する。CLAUDE.mdを肥大化させずに済む設計になっています。

公式の定義（Claude Code公式ドキュメントより）
“Skills package repeatable workflows that load on demand. Unlike CLAUDE.md which loads every session, skills only activate when you invoke them or when Claude determines they’re relevant.”
（参照: Claude Code Skills 公式ドキュメント・2026年6月確認）

Skills ディレクトリ構造：どこに何を置くか

Skillsは.claude/skills/ディレクトリに格納します。以下が推奨の構成です。

your-project/
├── .claude/
│   ├── CLAUDE.md              # メインのプロジェクト指示書
│   ├── rules/                 # パス別ルール
│   │   ├── api-design.md
│   │   └── testing.md
│   └── skills/                # Skills置き場
│       ├── code-review/
│       │   └── SKILL.md       # コードレビューSkill
│       ├── test-generator/
│       │   └── SKILL.md       # テスト生成Skill
│       ├── security-audit/
│       │   └── SKILL.md       # セキュリティ監査Skill
│       └── doc-writer/
│           ├── SKILL.md       # ドキュメント生成Skill
│           └── templates/     # テンプレートファイル（任意）
│               └── jsdoc.md

ポイントは「Skill一つ＝サブディレクトリ一つ」の構成です。SKILL.mdがエントリーポイントになり、テンプレート・サンプル・リファレンスなどの補助ファイルを同じディレクトリに置けます。

SKILL.mdの必須構造

SkillのコアはSKILL.mdのYAMLフロントマターです。以下が最小構成です。

---
name: code-review
description: "コードレビューを実施する。'レビューして' 'コードチェック' 'review' と言われたら起動。"
allowed-tools: Read, Bash(grep:*), Bash(git:*), WebSearch
---

# コードレビュー Skill

## レビュー観点
1. ロジックの正確性（境界値、エラーハンドリング）
2. セキュリティ（インジェクション、認証漏れ、機密情報ハードコード）
3. パフォーマンス（N+1クエリ、不要なループ、メモリリーク）
4. 可読性（命名規則、コメント、関数の単一責任）
5. テスト（カバレッジ、エッジケース）

## 出力フォーマット
- 🔴 Critical（必修正）
- 🟡 Major（推奨修正）
- 🟢 Minor（提案）

## プロジェクト固有のルール
- TypeScript strict mode必須
- `any`型の使用禁止
- async/awaitを優先（コールバック地獄回避）

フロントマターの各フィールドの意味を整理します。

Allowed Tools の設計：最小権限の原則

allowed-toolsはセキュリティ観点で最も重要なフィールドです。Skill実行中にClaudeが使えるツールを明示的に宣言します。

---
name: security-audit
description: "セキュリティ監査。'セキュリティチェック' 'security audit' ' 脆弱性確認'で起動。"
# ファイル読み込みと静的解析ツール呼び出しのみ許可
allowed-tools: Read, Glob, Grep, Bash(grep:*), Bash(npm:audit), Bash(semgrep:*)
# WebSearchは許可しない（外部通信を最小化）
---

指定の書き方には2種類あります。

• ツール名のみ（例: Read, Write, Glob）: そのツール全体を許可
• コロン区切りで絞り込み（例: Bash(git:*)）: gitコマンドのみ許可、rmなどは不可

注意：本番環境で使うSkillは、必ず必要最小限のtoolsだけをallow-listに入れてください。特にBash(*)のような全許可は避けましょう。

自作Skill 7パターン：コピペ可能な実装例

実務で頻繁に使われる7パターンのSkillを紹介します。各パターンはそのままコピーして使えます。

パターン1：コードレビューSkill

---
name: code-review
description: "コードレビューを実施。'review' 'レビューして' 'コードチェック' 'PR確認'で起動。"
allowed-tools: Read, Glob, Grep, Bash(git:diff), Bash(git:log)
---

# コードレビュー Skill

## チェックリスト
- [ ] ビジネスロジックの正確性
- [ ] エラーハンドリング（try-catch、null check）
- [ ] セキュリティ（SQL injection, XSS, 認証漏れ）
- [ ] パフォーマンス（N+1, 不要な再描画）
- [ ] テスト（ハッピーパス + エッジケース）

## 出力フォーマット
🔴 Critical: [問題] → [修正方法]
🟡 Major: [問題] → [推奨]
🟢 Minor: [提案]

## プロジェクトルール（カスタマイズしてください）
- ESLint/Prettierに準拠
- コメントは日本語でOK
- 関数は単一責任原則を守る

パターン2：テスト生成Skill

---
name: test-generator
description: "テストコードを生成。'テスト書いて' 'test生成' 'unit test' 'spec作成'で起動。"
allowed-tools: Read, Write, Glob, Bash(npm:test), Bash(jest:*)
---

# テスト生成 Skill

## テスト設計方針
1. Arrange-Act-Assert (AAA) パターンを使う
2. テスト名は「〜のとき〜すること」形式（例: `it('入力が空のとき、エラーを返すこと')`）
3. ハッピーパスとエッジケースの両方をカバー
4. 外部依存（API, DB）はモックする

## テスト生成手順
1. 対象ファイルを読み込む
2. パブリックな関数・メソッドをリストアップ
3. 各関数の入出力パターンを列挙
4. Jestで実装（TypeScript対応）
5. `npm test` で実行確認

## 優先度
- P0: 外部公開API、認証ロジック
- P1: ビジネスロジックの中核
- P2: ユーティリティ関数

パターン3：リサーチSkill

---
name: research
description: "技術調査・情報収集。'調べて' 'リサーチして' 'research' '〜の最新情報'で起動。"
allowed-tools: WebSearch, WebFetch, Read, Write
---

# リサーチ Skill

## 調査フロー
1. キーワードを英語・日本語で各3件WebSearch
2. 公式ドキュメントを必ずWebFetchで確認
3. 信頼性評価（公式 > 査読論文 > 著名エンジニアブログ > SNS）
4. 矛盾する情報は両論を記載し、信頼性の高い方を推奨

## 出力形式
### 概要（3行サマリー）
### 詳細（箇条書き、出典付き）
### 実装への示唆
### 注意点・制約
### 参考URL（取得日付付き）

## 禁止事項
- 知識から推測して出典なしで断言しない
- 最終更新日が1年以上前の記事を唯一の根拠にしない

パターン4：ドキュメント生成Skill

---
name: doc-writer
description: "ドキュメントを生成・更新。'ドキュメント作って' 'README更新' 'JSDoc' 'API仕様書'で起動。"
allowed-tools: Read, Write, Glob, Bash(git:log)
---

# ドキュメント生成 Skill

## ドキュメント種別と優先度
| 種別 | トリガー | テンプレート |
|------|---------|-------------|
| README | "README" "使い方" | ./templates/readme.md |
| JSDoc | "JSDoc" "関数コメント" | - (インライン生成) |
| API仕様書 | "API仕様" "OpenAPI" | - |
| アーキテクチャ | "設計書" "構成図" | - |

## README必須セクション
1. プロジェクト概要（1-2文）
2. クイックスタート（コピペで動く手順）
3. インストール
4. 使用方法（コード例付き）
5. 設定オプション
6. コントリビューション

## 品質基準
- コードブロックには言語指定を付ける
- コピペで動くコマンド例を入れる
- 「詳細は〜を参照」で逃げない（最低限の情報をインラインで書く）

パターン5：セキュリティ監査Skill

---
name: security-audit
description: "セキュリティ監査を実施。'セキュリティチェック' 'vulnerability check' '脆弱性確認'で起動。"
allowed-tools: Read, Glob, Grep, Bash(grep:*), Bash(npm:audit), Bash(git:diff)
---

# セキュリティ監査 Skill

## チェック観点（OWASP Top 10準拠）
1. **A01: アクセス制御の不備** — 認証・認可のバイパス、権限昇格
2. **A02: 暗号化の失敗** — 平文保存、弱い暗号アルゴリズム
3. **A03: インジェクション** — SQL injection, XSS, コマンドインジェクション
4. **A04: 安全でない設計** — シークレットのハードコード、不適切なCORS設定
5. **A07: 認証・セッション管理** — JWTの検証漏れ、セッション固定

## 自動チェック手順
```bash
# 依存パッケージの脆弱性スキャン
npm audit --audit-level=moderate

# シークレットの漏洩チェック（grepで簡易確認）
grep -rn "api_key|password|secret|token" --include="*.ts" --include="*.js" src/

# ハードコードされた認証情報を検索
grep -rn "sk-|Bearer |password=" src/
```

## 出力フォーマット
- Critical（即時修正必須）
- High（今リリース前に修正）
- Medium（次スプリントで対応）
- Low（情報として記録）

パターン6：翻訳Skill

---
name: translator
description: "テキストを翻訳。'翻訳して' 'translate' '英訳' '和訳' '〜に訳して'で起動。"
allowed-tools: Read, Write, WebSearch
---

# 翻訳 Skill

## 翻訳方針
- **技術用語**: 業界標準に従う（例: "repository" = "リポジトリ"、"merge" = "マージ"）
- **UIテキスト**: 短く、動詞起点で（例: "Submit" = "送信する" より "送信"）
- **エラーメッセージ**: ユーザーに次のアクションを促す形に
- **マーケティング文**: 原文のトーンを保ちつつ、自然な日本語に

## 翻訳フロー
1. 原文の意図・トーンを確認
2. 技術用語は業界標準の訳語を使用
3. 文化的なニュアンス（ジョーク、慣用句）は注釈付きで意訳
4. 翻訳後、逆翻訳で意味ズレを確認（重要な文書の場合）

## 日英技術用語対応表（プロジェクト固有に追記してください）
- deploy → デプロイ
- staging → ステージング
- pull request → プルリクエスト

パターン7：業界固有Skill（SaaS企業向けカスタマーサクセス例）

---
name: cs-response
description: "CS対応文を生成。'CSメール' '顧客返信' 'サポート文章' 'お詫び文'で起動。"
allowed-tools: Read, WebSearch
---

# カスタマーサクセス対応 Skill

## 対応テンプレート選択ガイド
| 問い合わせ種類 | 使うテンプレート |
|--------------|----------------|
| 機能の使い方 | how-to-template |
| バグ報告 | bug-report-template |
| 解約申し出 | retention-template |
| 機能要望 | feature-request-template |

## 文章スタイルガイド
- 一文60字以内（長いと読みにくい）
- 受動態より能動態（「〜されています」より「〜しています」）
- 謝罪より解決策を先に（「ご不便をおかけして…」より「解決策は…です」）
- 専門用語に(括弧で補足)

## 禁止表現
- 「確認いたします」単体（いつ回答するか不明）
- 「できかねます」単体（代替案がない）
- 「ご理解ください」（一方的）

## 必須確認事項
1. 顧客名・社名は間違いなしか
2. 解決策は技術的に正しいか
3. 期日・約束事項を明記したか

5ステップ：Skillを作って動かすまでの手順

1. ディレクトリを作成する
   プロジェクトルートでmkdir -p .claude/skills/your-skill-nameを実行。Skill名は英数字ハイフン区切りにする。

2. SKILL.mdを作成する
   .claude/skills/your-skill-name/SKILL.mdを作成し、YAMLフロントマターにname・description・allowed-toolsを書く。descriptionにはトリガー語句を自然言語で含める。

3. Skill本文を書く
   フロントマターの下に、Claudeへの指示を書く。見出し・箇条書き・表を使って構造化すると遵守率が上がる。重要なルールは太字かcode blockで強調。

4. テスト発火させる
   Claude Codeで/your-skill-nameとスラッシュコマンドを入力するか、descriptionに書いたトリガー語句を自然に含んだプロンプトを送る。/memoryでSkillが認識されているか確認できる。

5. Gitにコミットしてチームに共有する
   git add .claude/skills/ && git commit -m "feat: add code-review skill"でコミット。以降はpull/cloneした全メンバーが同じSkillを使える。個人専用のSkillは~/.claude/skills/に置く（リポジトリ外）。

公式Skillと自作Skillの違い

Anthropicが公式に配布しているSkillと、自分で作るカスタムSkillにはいくつかの違いがあります。

注目すべきは、公式Skillはオーバーライドできないという点です。例えば「claude-codeレビュー」という公式Skillと名前が衝突する自作Skillを作った場合、動作が予測不能になる可能性があります。自作Skillのnameは意図的にプロジェクト固有のプレフィックスを付けると安全です（例: myapp-code-review）。

チーム配布の2パターン：Git管理 vs シンボリックリンク

パターンA：リポジトリに含めてGit管理（推奨）

# プロジェクトリポジトリに skills を追加
git add .claude/skills/
git commit -m "feat: add team skills for code-review and testing"
git push

# チームメンバーは pull するだけで使える
git pull
# → .claude/skills/code-review/SKILL.md が自動で有効化される

この方法の利点は、Skillとコードベースのバージョンが同期する点です。フレームワークやコーディング規約が変わったとき、Skillも同じPRで更新できます。

パターンB：ユーザーレベルに共有Skills（個人横断）

# 共有Skills置き場を用意
mkdir -p ~/shared-skills

# 各プロジェクトからシンボリックリンクを張る
ln -s ~/shared-skills/security-audit .claude/skills/security-audit
ln -s ~/shared-skills/translator .claude/skills/translator

# これで複数プロジェクトで同じSkillを再利用できる
# ~/shared-skills/ を更新すると全プロジェクトに即時反映される

個人の汎用Skillは~/.claude/skills/に置くと全プロジェクトで自動利用可能になります。

# 個人用の汎用翻訳Skillを追加
mkdir -p ~/.claude/skills/translator
cat > ~/.claude/skills/translator/SKILL.md <<'EOF'
---
name: translator
description: "翻訳。'translate' '翻訳して' '英訳' '和訳' で起動。"
allowed-tools: Read, Write
---
# 翻訳Skill
...（内容省略）
EOF

# 以降は全プロジェクトで「翻訳して」と言うだけで発火する

【要注意】よくある失敗パターン3つ

失敗1：descriptionのトリガー語句が被って混乱する

# ❌ NG: 複数のSkillで同じ語句を使うと競合する
# skill-A/SKILL.md
description: "コードをチェックして改善提案。'チェックして' 'check' で起動。"

# skill-B/SKILL.md
description: "型エラーをチェック。'チェックして' 'check' で起動。"  # ← 競合！

# ✅ OK: 固有のトリガー語句を使う
# skill-A/SKILL.md
description: "コードレビュー全般。'コードレビュー' 'code review' 'PR確認' で起動。"

# skill-B/SKILL.md
description: "TypeScript型チェック専用。'型チェック' 'type check' 'tsc確認' で起動。"

失敗2：allowed-toolsを全許可にしてセキュリティホールを作る

# ❌ NG: Bash全許可はリスクが高い
allowed-tools: Read, Write, Bash(*), WebSearch, WebFetch

# ✅ OK: 必要なコマンドを明示的にリスト
allowed-tools: Read, Glob, Bash(npm:test), Bash(jest:*), Bash(git:status)

特にBash(*)やWriteの全許可は、意図しないファイル削除やシステムコマンド実行のリスクがあります。Skill設計は「最小権限の原則」に従って、本当に必要なツールだけを列挙してください。

失敗3：SKILL.mdが長すぎてClaudeが発火しなくなる

# ❌ NG: 500行超のSKILL.md（コンテキスト消費が大きすぎて発火率が下がる）
SKILL.md: 600行
- 詳細なルール: 200行
- テンプレート: 200行
- 事例集: 200行

# ✅ OK: 本体はシンプルに、詳細は別ファイルに分離
SKILL.md: 80行（コアルールとトリガーのみ）
templates/
  code-review-output.md: 詳細なフォーマット
  checklist.md: チェックリスト全量

SKILL.mdはClaude Codeのコンテキストウィンドウに読み込まれます。1Skill=100行以内を目安にし、詳細な指示は同じスキルディレクトリ内の別ファイルに分けて@./templates/checklist.mdで参照させるとコンテキスト効率が上がります。

Skillが発火しないときのデバッグ手順

Skillが期待通り動かないときの調査ステップを整理します。

1. /memoryコマンドで読み込み確認
   セッション中に/memoryを実行。Skillのリストに目的のSkillが表示されるか確認。表示されない場合はファイルパスが間違っているか、YAMLフロントマターの構文エラーの可能性。

2. descriptionのトリガー語句を明示的に使う
   自動発火しない場合は/skill-nameのスラッシュコマンドで明示起動。それでも動かなければフロントマターを確認。

3. YAML構文を検証する

   python3 -c "
   import yaml
   with open('.claude/skills/your-skill/SKILL.md') as f:
       content = f.read()
   # YAMLフロントマターを抽出してパース
   front = content.split('---')[1]
   data = yaml.safe_load(front)
   print('OK:', data)
   "
   

4. ファイル権限を確認する
   ls -la .claude/skills/your-skill/でパーミッションを確認。644（読み取り可能）になっているか。

企業でのチーム導入：settings.jsonとの組み合わせ

組織全体にSkillsを展開する場合、settings.jsonと組み合わせてSkillの動作を制御できます。

// .claude/settings.json（プロジェクト共有）
{
  "autoMemoryEnabled": true,
  "permissions": {
    "deny": [
      // セキュリティ監査Skill以外でのnpm publish禁止
      "Bash(npm:publish)"
    ]
  }
}

マネージドポリシー（IT/DevOpsが全ユーザーに強制する設定）は以下のパスに置きます。

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux/WSL: /etc/claude-code/CLAUDE.md

ここにOrgレベルの共通Skillへの@importを書くことで、全開発者が同じベースラインのSkillを使える環境を作れます。

実際に100社以上のAI活用支援をしてきた経験からいうと、Skillsを最も効果的に使っているチームは「コードレビューのコメント品質が均一になった」という効果を真っ先に実感します。シニアエンジニアのレビュー観点をSkillに落とし込むことで、ジュニアメンバーのレビューにも同等のフィードバックが出るようになるのです。

よくある質問（FAQ）

Q1：SkillsはCLAUDE.mdと何が違うのですか？

CLAUDE.mdはセッション開始時に毎回コンテキストウィンドウに読み込まれる「常時有効な指示書」です。一方SkillsはPushオンデマンドで、呼び出した時だけ読み込まれます。毎回必要なルール（コーディング規約など）はCLAUDE.md、特定タスク時だけ必要な深い指示（コードレビュー詳細観点など）はSkillsに書くのが最適な分担です。

Q2：Skillのdescriptionはどう書けばいいですか？

Claudeがそのユーザー発話を見たときに「これはこのSkillを使う場面だ」と判断できる文章を書きます。具体的なトリガー語句を括弧内に列挙する形が効果的です。例："コードレビューを実施する。'review' 'レビューして' 'PR確認' 'コードチェック' で起動。"

Q3：チームメンバーに共有する最も簡単な方法は？

.claude/skills/ディレクトリをGitリポジトリにコミットするだけです。git pullを行えば全メンバーが同じSkillを使える状態になります。個人専用のSkillは~/.claude/skills/（ホームディレクトリ下）に置くと、リポジトリを汚さずに管理できます。

Q4：Skillの数が増えすぎるとどうなりますか？

公式ドキュメントでは特定の上限は示されていませんが、descriptionのトリガー語句が多すぎると発火の曖昧さが生じる場合があります。実務では5〜10個程度で十分なケースがほとんどです。使わなくなったSkillは_deprecated/サブフォルダに移すか削除してください（2026年6月時点）。

Q5：allowed-toolsを省略した場合の動作は？

allowed-toolsを省略した場合、そのSkill実行中はClaudeの通常の権限（セッションの設定に準じたもの）が使われます。Skillの外で許可されていないツールはSkill内でも使えません。セキュリティの観点から、本番環境向けSkillは必ずallowed-toolsを明示することを推奨します。

まとめ：今日から始める3つのアクション

1. 今日やること：プロジェクトに.claude/skills/code-review/SKILL.mdを1つ作り、よく使うレビュー観点を書き込む（パターン1のコードをコピペするだけでOK）。
2. 今週中：チームで「どのワークフローをSkillにしたいか」を話し合い、上位3つのSkillをGitリポジトリに追加してチームで使い始める。
3. 今月中：各Skillの発火ログをレビューし、descriptionのチューニングとallowed-toolsの最小化を行い、セキュリティと使いやすさを両立させる。

Skillsは「プロジェクトの知識をコードと同じようにバージョン管理する」ための仕組みです。スタートはSKILL.md一枚。チームの暗黙知をClaudeが扱える形式に変換するだけで、開発者全員の作業品質が引き上げられます。

あわせて読みたい：

• Claude Code Hooks 完全ガイド｜PreToolUse/PostToolUse/Stop 7パターン実装
• コンテキストエンジニアリング完全ガイド｜AI管理・圧縮・予算設計

参考・出典

• Claude Code Skills — Anthropic公式ドキュメント（参照日: 2026-06-03）
• How Claude remembers your project — Anthropic公式ドキュメント（参照日: 2026-06-03）
• Claude Code Memory System Explained: 4 Layers, 5 Limits, and a Fix — Milvus Blog（参照日: 2026-06-03）

Claude Code Skills × MCP × Agent SDK 3層統合アーキテクチャ

2026年以降のClaudeエコシステムは、3つの層が明確に役割分担する構造へと進化しました。Anthropicが公式に解説している設計思想を整理すると、以下の関係図になります。

┌─────────────────────────────────────────────────────┐
│              Agent SDK (オーケストレーション層)        │
│  query() ループ / Hooks / Subagents / Sessions       │
│  ↓ 呼び出し                  ↑ 結果返却              │
├──────────────────┬──────────────────────────────────┤
│   Skills 層      │         MCP 層                   │
│  ドメイン知識     │  外部サービス接続                  │
│  手順・ワークフロー │  認証・APIコール自動化             │
│  .claude/skills/ │  Slack / GitHub / DBなど          │
│  SKILL.md        │  standardized protocol           │
└──────────────────┴──────────────────────────────────┘

各層の責務分担

Skills層（手順・知識層）はドメイン固有のワークフローをClaudeに注入します。SKILL.mdで記述されたプロセデュラルな知識が、タスクの「やり方」を担います。Anthropicが「Progressive Disclosure（段階的開示）」と呼ぶ設計により、必要になった瞬間だけフルコンテキストをロードするため、トークン消費を最小化できます（Anthropic Engineering Blog「Equipping agents for the real world with Agent Skills」2026年）。

MCP層（接続・認証層）は外部サービスとの接続を標準化します。Slack・GitHub・Google Drive・データベースといった外部システムへのOAuth認証やAPIコールを自動処理し、開発者がカスタム連携コードを書く必要をなくします。2025年12月にはAnthropicがMCPをLinux Foundation傘下の「Agent AI Foundation」に移管し、OpenAI・Blockなどが参加するオープンスタンダードとなりました（PulseMCP 2025年12月16日報道）。

Agent SDK層（実行・オーケストレーション層）はエージェントループそのものを提供します。query()関数がasyncジェネレータベースでメッセージをストリームし、ToolCall・ToolResult・ResultMessageの3種類のメッセージを逐次返します。Claude Codeを動かしているのと同じ機構がPython/TypeScriptライブラリとして利用できます。

設計原則：SkillsはMCPを「補完」する。Skillsがドメイン固有ワークフローをエージェントに与え、MCPがサービスへの接続を処理する。（Anthropic Agent Skills リリースページ）

3層を合わせた実装例（Python）

以下は3層を同時に活用する構成例です。Skillsでコードレビュー手順を定義し、MCP経由でGitHubに接続し、Agent SDKがオーケストレーションします。

# 動作環境: Python 3.11+, claude-agent-sdk 最新版
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def integrated_review_agent():
    async for message in query(
        prompt="GitHubのPR #42のコードレビューを実施してください。"
               "社内のcode-review Skillを使い、セキュリティと可読性を確認してください。",
        options=ClaudeAgentOptions(
            # Skills層: .claude/skills/code-review/ が自動ロード
            # Agent SDKはWORKING_DIR内の .claude/skills/ を自動探索
            allowed_tools=["Read", "Grep", "WebFetch", "Agent"],
            # MCP層: GitHub接続を自動化
            mcp_servers={
                "github": {
                    "command": "npx",
                    "args": ["@anthropic-ai/mcp-server-github@latest"],
                    "env": {"GITHUB_TOKEN": "YOUR_TOKEN"}  # 実際はenv変数から
                }
            },
            # サブエージェントでセキュリティ監査を分離
            agents={
                "security-auditor": {
                    "description": "セキュリティ脆弱性の専門監査エージェント",
                    "prompt": "OWASP Top 10の観点からコードを精査してください。",
                    "tools": ["Read", "Grep"]
                }
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(integrated_review_agent())

ポイント

• mcp_serversにGitHubサーバーを渡すだけで認証・APIコールが自動処理される
• Skillsは .claude/skills/ を自動探索するため、optionsへの追記不要
• セキュリティ監査はサブエージェントに分離することで、コンテキスト汚染を防ぐ

Agent SDK でオーケストレーション実装する4パターン

実際に10社以上のAIエージェント導入を支援してきた経験から、用途によって4つのパターンに整理できます。どのパターンを選ぶかで、保守性・スケーラビリティ・コストが大きく変わります。

パターン1：シンプル単一エージェント（~500行のシステムまで推奨）

最も基本的な構成で、1つのquery()呼び出しで完結します。プロトタイプや単発タスクの自動化に最適です。

# Python: シンプルパターン
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def simple_agent(task: str) -> str:
    result = ""
    async for message in query(
        prompt=task,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Write", "Bash", "Glob"]
        )
    ):
        if hasattr(message, "result"):
            result = message.result
    return result

# 使用例
asyncio.run(simple_agent("src/以下のすべてのPythonファイルにdocstringを追加してください"))

// TypeScript: シンプルパターン
import { query } from "@anthropic-ai/claude-agent-sdk";

async function simpleAgent(task: string): Promise {
  let result = "";
  for await (const message of query({
    prompt: task,
    options: { allowedTools: ["Read", "Write", "Bash", "Glob"] }
  })) {
    if ("result" in message) result = message.result as string;
  }
  return result;
}

パターン2：ハイブリッド（オーケストレーター + 専門サブエージェント）

1つの親エージェントが全体を統括し、専門タスクを子エージェントに委任します。Anthropicが推奨するマルチエージェントの基本構成です。

# Python: ハイブリッドパターン
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def hybrid_pipeline(codebase_path: str):
    """コードレビュー→テスト生成→ドキュメント生成の3段パイプライン"""
    async for message in query(
        prompt=f"{codebase_path}のコードを分析し、"
               "code-reviewerでレビュー、test-generatorでテスト追加、"
               "doc-writerでドキュメント生成してください。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Write", "Glob", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="コード品質とセキュリティのレビュー専門家",
                    prompt="SOLID原則とOWASP Top10の観点でレビューしてください。",
                    tools=["Read", "Glob", "Grep"]
                ),
                "test-generator": AgentDefinition(
                    description="pytestユニットテスト生成の専門家",
                    prompt="カバレッジ80%以上を目標にテストを生成してください。",
                    tools=["Read", "Write", "Bash"]
                ),
                "doc-writer": AgentDefinition(
                    description="Google Styleドキュメント生成の専門家",
                    prompt="型アノテーション付きのdocstringを生成してください。",
                    tools=["Read", "Edit"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(f"[ハイブリッド完了] {message.result[:200]}")

asyncio.run(hybrid_pipeline("./src"))

パターン3：フェデレーション（チーム別エージェント分離）

チームや機能ドメインごとにエージェントを独立させ、相互に呼び出す構成です。大規模プロダクトでのマイクロサービス的アーキテクチャに対応します。セッションIDを活用してコンテキストを共有します。

# Python: フェデレーションパターン（セッション継続活用）
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

async def federated_agents():
    # Step 1: 分析エージェントが調査 → セッションIDを取得
    session_id = None
    async for message in query(
        prompt="このリポジトリのアーキテクチャを分析して、改善点を洗い出してください。",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]  # セッションIDを保存

    # Step 2: 実装エージェントが同一コンテキストで改善を実施
    async for message in query(
        prompt="先ほどの分析結果を踏まえて、最も優先度の高い改善を実装してください。",
        options=ClaudeAgentOptions(resume=session_id)  # セッション引き継ぎ
    ):
        if hasattr(message, "result"):
            print(f"[実装完了] {message.result}")

asyncio.run(federated_agents())

パターン4：エンタープライズ（Hooks + 権限制御 + 監査ログ）

本番環境での運用に必要な監査・権限制御・ロギングを完備した構成です。Hooksで全ツール呼び出しをキャプチャし、allowed_toolsで最小権限を徹底します。

# Python: エンタープライズパターン（監査ログ + 権限制御）
import asyncio
import json
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

# 監査ログへの記録関数
async def audit_log(input_data, tool_use_id, context):
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "tool": input_data.get("tool_name"),
        "input": input_data.get("tool_input"),
        "session": context.get("session_id")
    }
    with open("/var/log/agent-audit.jsonl", "a") as f:
        f.write(json.dumps(log_entry, ensure_ascii=False) + "n")
    return {}  # 空dictを返せばツール実行は続行

# 危険コマンドをブロックする関数
async def block_dangerous_commands(input_data, tool_use_id, context):
    cmd = input_data.get("tool_input", {}).get("command", "")
    blocked = ["rm -rf", "DROP TABLE", "kubectl delete"]
    for dangerous in blocked:
        if dangerous in cmd:
            raise PermissionError(f"危険なコマンドをブロックしました: {cmd}")
    return {}

async def enterprise_agent(task: str):
    async for message in query(
        prompt=task,
        options=ClaudeAgentOptions(
            # 最小権限: 読み取りと限定的な書き込みのみ
            allowed_tools=["Read", "Glob", "Grep", "Edit"],
            permission_mode="acceptEdits",
            hooks={
                "PreToolUse": [
                    HookMatcher(matcher="Bash", hooks=[block_dangerous_commands])
                ],
                "PostToolUse": [
                    HookMatcher(matcher=".*", hooks=[audit_log])  # 全ツールを記録
                ]
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(enterprise_agent("本番DBの設定ファイルをレビューしてください"))

4パターンの選び方まとめ

3層統合の失敗事例5選

複数のエージェント統合プロジェクトで観察してきた失敗パターンを整理します。これらを先に知っておくだけで、実装時間を大幅に短縮できます。

失敗事例1：MCP認証トークンをコードにハードコード

最も多い初歩的ミスです。GitHub TokenやSlack Bot Tokenをmcp_serversのenvに直書きし、コードをGitにコミットしてしまうケースが後を絶ちません。

# ❌ NG: トークンをコードに直書き
options=ClaudeAgentOptions(
    mcp_servers={
        "github": {
            "env": {"GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"}  # 絶対にやらない
        }
    }
)

# ✅ OK: 環境変数から取得
import os
options=ClaudeAgentOptions(
    mcp_servers={
        "github": {
            "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]}
        }
    }
)

回避策：python-dotenvやAWS Secrets Managerを活用し、シークレットは環境変数経由で注入します。CI/CDパイプラインではsecretsストアを使います。

失敗事例2：allowed_toolsの過剰付与でコンテキスト汚染

「とりあえず全ツールを許可しておこう」という発想が、後の問題の温床になります。使わないツールの定義がコンテキストウィンドウを圧迫し、コスト増加と応答精度の低下を招きます。

# ❌ NG: 全ツール許可（コンテキスト肥大化・コスト増）
allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep",
               "WebSearch", "WebFetch", "Agent", "Monitor"]

# ✅ OK: タスクに必要な最小セットのみ
# ファイル分析専用なら読み取りツールだけ
allowed_tools=["Read", "Glob", "Grep"]

回避策：タスクを分析し、「このタスクに絶対必要なツール」だけをリストアップします。最小権限の原則を徹底することで、エラー発生時の影響範囲も限定できます。

失敗事例3：Skillsのdescriptionが曖昧でトリガーされない

SKILL.mdのdescriptionフィールドが不明確だと、エージェントがSkillを「関係ない」と判断して無視します。Anthropicの設計では、descriptionがSkillの自動選択に使われるためです。

# ❌ NG: 抽象的なdescription（エージェントがスキップする）
---
name: code-review
description: "コードに関するスキル"
---

# ✅ OK: 具体的なトリガー条件を含むdescription
---
name: code-review
description: "PRレビュー・コード品質チェック・セキュリティ監査が必要なときに使う。
              OWASP Top10・SOLID原則・パフォーマンス最適化の観点で分析する。"
---

回避策：descriptionには「どんな場面で使うか」「どんな観点を適用するか」を具体的に書きます。トリガーとなる動詞（レビュー・監査・チェック・分析）と対象領域を明示します。

失敗事例4：エラーハンドリングなしの長時間エージェント

Agent SDKのquery()は非同期ジェネレータです。ネットワーク断・MCPサーバーダウン・APIレート制限などで例外が投げられても、適切なハンドリングがないと処理が無言で失敗します。

# ❌ NG: エラー無視（なぜ止まったか分からない）
async for message in query(prompt="..."):
    pass

# ✅ OK: 適切な例外処理と再試行
import asyncio
from claude_agent_sdk import ClaudeAgentSDKError

async def robust_agent(prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            async for message in query(
                prompt=prompt,
                options=ClaudeAgentOptions(allowed_tools=["Read", "Bash"])
            ):
                if hasattr(message, "result"):
                    return message.result
        except ClaudeAgentSDKError as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 指数バックオフ
            print(f"エラー発生（{e}）。{wait}秒後に再試行...")
            await asyncio.sleep(wait)

失敗事例5：本番でのエージェント動作を監視していない

エージェントが自律的に動くからこそ、人間が気づかない箇所でコスト爆発・意図しないファイル書き換え・API quota超過が起きます。Hooksを使った監視なしでの本番稼働は推奨しません。

# ✅ OK: コスト監視Hookで異常を早期検知
async def cost_monitor(input_data, tool_use_id, context):
    """PostToolUse Hookでトークン使用量を監視"""
    usage = context.get("usage", {})
    total_tokens = usage.get("total_tokens", 0)
    if total_tokens > 50000:  # 閾値を超えたらSlackに通知
        import requests
        requests.post(
            os.environ["SLACK_WEBHOOK_URL"],
            json={"text": f"⚠️ エージェントのトークン使用量が閾値超過: {total_tokens:,} tokens"}
        )
    return {}

回避策：本番エージェントには必ずPostToolUse Hookでトークン使用量・実行時間・エラー率を記録します。異常検知は自動化し、Slackなどへ通知する仕組みを事前に整えます。

2026年6月版 Skills / MCP / Agent SDK 最新動向

AI業界はモデルと同じ速度でツール・プロトコルも進化しています。2026年6月時点の主要アップデートをまとめます。

Agent Skills の公式リリースとクロスベンダー標準化

Anthropicは2025年10月にAgent Skillsを正式リリースし、Claude.ai・Claude Code・Claude Agent SDK・Claude Developer Platformのすべてで利用可能にしました（Anthropic Engineering Blog「Equipping agents for the real world with Agent Skills」）。

さらに2025年12月には、OpenAIがCodexおよびChatGPT自体でAgent Skillsのサポートを表明しました。Anthropicが設計したSkillsの仕様が、事実上のクロスベンダー標準になりつつあります（PulseMCP 2025年12月16日）。

MCPの Linux Foundation 移管（2025年12月）

Anthropicはプロジェクトメンバーと共にMCPを「Agent AI Foundation」（Linux Foundation傘下）に移管しました。OpenAI・Blockを含む複数企業が加盟し、年間500万ドル超の資金拠出でコミュニティ運営に移行しています。これにより、MCPはAnthropicの製品ではなく「コミュニティ所有の標準」となりました。

MCP 2026年ロードマップの主要変更点

MCP Steering Committeeが公開しているロードマップ（2026年内実施予定）では、以下の変更が計画されています（Ted Tschopp「MCP’s 2026 Roadmap」）。

• ステートレス化（2026年6月目標）：初期化ハンドシェイクを廃止し、メタデータをリクエストヘッダーに格納。Kubernetes・ロードバランサー・サーバーレス環境での大規模運用が容易になる
• Server Discovery：.well-known URLにMCP機能のメタデータを標準公開。フル接続前に機能確認が可能に
• エンタープライズ認証：Google Workspace・OktaなどのIdPとの統合で、組織内のOAuth認証を一元管理
• Triggers（イベント駆動）：Webhookによるイベントドリブンワークフローの正式サポート。ユーザー操作なしで起動するエージェントパイプラインが標準化
• ストリーミング出力：大規模処理の段階的出力に対応。レイテンシの削減とコンテキスト肥大化の防止

Agent SDK の最新仕様（2026年6月時点）

Claude Agent SDK（旧: Claude Code SDK）は名称変更と同時に機能強化されています（code.claude.com/docs/en/agent-sdk/overview 2026年6月時点）。

• 利用可能プラットフォーム：Python 3.10+（pip install claude-agent-sdk）、TypeScript（npm install @anthropic-ai/claude-agent-sdk）
• 組み込みツール数：Read・Write・Edit・Bash・Monitor・Glob・Grep・WebSearch・WebFetch・AskUserQuestionなど14+種類
• サードパーティ認証：Amazon Bedrock・Google Vertex AI・Microsoft Azure AI Foundryでの認証に公式対応
• 注意点（2026年6月15日以降）：Claude.ai サブスクリプションプランでAgent SDKやclaude -pを使うと、インタラクティブ使用とは別の月次「Agent SDKクレジット」から消費される（Anthropic公式サポート「Use the Claude Agent SDK with your Claude plan」）

コード実行型MCPによる大幅なトークン削減

Anthropic Engineering Blogが報告した「Code execution with MCP」（2026年）では、ツール定義をコードAPIとして扱うアーキテクチャにより、従来比98.7%のトークン削減（15万→2,000トークン）を達成しています。

この設計では、エージェントがファイルシステム型の構造を通じてツール定義を必要に応じて取得します。Skills层の「Progressive Disclosure」と同じ哲学を、MCP層にも適用した形です。

2026年後半に向けての実装指針

今後3〜6ヶ月でのSkills/MCP/Agent SDK活用にあたり、実際に構築してきた経験から3点の実装指針をお伝えします。

1. Skillsは「チームの暗黙知」の外部化に最も効果的：コードレビューの観点・QAのチェックリスト・デプロイ前確認手順など、ベテランが頭の中に持っている手順をSKILL.mdに書き出すと、エージェントが再現できるようになります
2. MCPはまず「読み取り専用」から始める：GitHub・Slackとの連携は、最初はread-onlyのスコープで始め、動作確認後に書き込み権限を付与する段階的アプローチが安全です
3. Agent SDKの本番投入はHooks必須：監査ログ・コスト監視・危険コマンドブロックの3点セットをHooksで実装してから本番稼働させることを強くお勧めします

関連記事: HANDBOOK.md解説｜長文ポリシーはエージェントを縛れない【2026】