【Anthropic Academy】Agent Skills入門 完全ガイド ― Claude Codeを自分好みに拡張する

Introduction to Agent Skills ってどんなコース？

「Introduction to Agent Skills」は、Anthropicが公式に提供するClaude Codeのスキル機能に特化した開発者向けコースです。Anthropic Academyの13コースのうち中級に位置し、Claude Codeの基本操作を理解している開発者が次のステップとして受講することを想定しています。

「スキル（Skills）」とは、Claude Codeに再利用可能なMarkdown指示を登録して、特定のタスクを自動で実行させる仕組みです。一度スキルを作れば、スラッシュコマンドひとつでClaude Codeが適切なタイミングで自動的にそのスキルを適用してくれます。このコースでは、スキルのゼロからの作成、チームへの共有、プラグインとしての配布、エンタープライズ展開、そしてトラブルシューティングまでを体系的に学びます。

このコースはこんな人におすすめ

Introduction to Agent Skillsは、Anthropic Academyの中で明確に開発者をターゲットにしたコースです。以下のような人に特に適しています。

• Claude Codeを日常的に使っている開発者 ― 基本操作はできるが、「毎回同じことを繰り返している」「チームメンバーによって使い方がバラバラ」という課題を感じている人
• 開発チームのリード・テックリード ― チーム全体のClaude Code活用を標準化・効率化したい人。スキルをリポジトリにコミットすれば、チーム全員が同じ品質のワークフローを使える
• DevOpsエンジニア ― デプロイ、CI/CD、インフラ管理のワークフローをClaude Codeに組み込みたい人
• CLAUDE.mdが肥大化して困っている人 ― プロジェクトのルールをCLAUDE.mdにすべて詰め込んだ結果、コンテキストを圧迫している。スキルに分離する方法を学びたい人
• エンタープライズでClaude Codeを導入している組織の管理者 ― 組織全体でスキルを統一的に配布・管理したい人

コースで学ぶ内容を徹底解説

ここからはIntroduction to Agent Skillsで学ぶ内容を、コースの流れに沿って詳しく解説します。実際のコード例も交えて、受講前の予習・受講後の復習に使えるようにまとめています。

レッスン1: スキルの基本概念 ― CLAUDE.mdやHooksとの違い

コースの最初のパートでは、Claude Codeにおける3つのカスタマイズ手段の違いを明確にします。スキルを効果的に使うには、まず「何をどこに書くべきか」の判断基準を持つことが重要です。

• CLAUDE.md ― プロジェクト全体のルールブック。毎セッション自動読み込み。コーディング規約、セキュリティポリシーなど「常に適用されるべきルール」を記述する
• Skills（スキル） ― 特定タスクの専門知識。必要な時だけ読み込まれる。デプロイ手順、レビュー基準、特定フレームワークの知識など「特定の場面で必要な情報」を記述する
• Hooks ― イベントドリブンの自動処理。コマンド実行前後にシェルスクリプトを自動実行する仕組み。lintの自動実行、ファイルのバックアップなど「自動的にトリガーされる処理」を設定する

この3つは競合するものではなく、レイヤーとして組み合わせて使うのが正しい設計です。

レッスン2: はじめてのスキルを作る ― SKILL.mdの書き方

コースの核心部分です。実際に手を動かして最初のスキルをゼロから作成します。スキルは驚くほどシンプルな構造で、ディレクトリとSKILL.mdファイルひとつで成立します。

スキルの最小構成

# ディレクトリ構造
~/.claude/skills/          # 個人用スキル置き場
  deploy-checker/          # スキル名のディレクトリ
    SKILL.md               # スキル定義ファイル（必須）

SKILL.mdの基本構造

SKILL.mdは、YAMLフロントマター（メタデータ）とMarkdown本文（指示内容）の2つのパートで構成されます。

---
name: deploy-checker
description: デプロイ前のチェックリストを実行し、問題があれば報告する
---

# デプロイ前チェック

以下の項目を順番に確認してください:

1. **テスト実行**: `npm test` を実行し、全テストがパスすることを確認
2. **lint チェック**: `npm run lint` でエラーがないことを確認
3. **環境変数**: `.env.example` と `.env` を比較し、不足がないか確認
4. **マイグレーション**: 未適用のマイグレーションがないか確認
5. **ビルド**: `npm run build` が成功することを確認

すべて問題なければ「デプロイ準備完了」と報告してください。
問題があれば、問題箇所と修正方法を提案してください。

これだけで完成です。/deploy-checker というスラッシュコマンドが使えるようになり、Claude Codeに「デプロイ前チェックして」と頼むだけで、このスキルが自動的に適用されます。

YAMLフロントマターの詳細

フロントマターに記述できるフィールドは以下の通りです。

---
name: code-reviewer          # スラッシュコマンド名（必須）
description: |                # スキルの説明（推奨・250文字以内）
  PRのコードをレビューし、バグ・パフォーマンス・
  セキュリティの観点でフィードバックを提供する
allowed-tools:                # 使用可能なツールを制限（任意）
  - Read
  - Grep
  - Glob
disable-model-invocation: false  # 自動実行を無効にするか（任意）
---

レッスン3: スキルディレクトリの設計 ― Progressive Disclosureパターン

コースの3つ目のレッスンでは、スキルのディレクトリ構造を最適化する方法を学びます。コンテキストウィンドウを効率的に使うための「Progressive Disclosure（段階的開示）」という設計パターンがキーコンセプトです。

スキルが複雑になると、すべての情報をSKILL.md1ファイルに詰め込むのは非効率です。Claude Codeはスキル読み込み時にまずSKILL.mdだけを読み、必要に応じて追加ファイルを段階的に参照します。

# 推奨ディレクトリ構造
api-integration/
  SKILL.md                  # 概要と基本手順（最初に読まれる）
  reference/
    endpoints.md            # APIエンドポイント一覧（必要時に参照）
    error-codes.md          # エラーコード一覧（必要時に参照）
    rate-limits.md          # レート制限の詳細（必要時に参照）
  examples/
    auth-flow.md            # 認証フローのサンプルコード
    pagination.md           # ページネーション実装例
  scripts/
    validate-config.sh      # 設定検証スクリプト

SKILL.mdには概要とメインの手順を書き、詳細な仕様やリファレンスは別ファイルに分離します。これにより、単純なタスクではSKILL.mdだけで完結し、複雑なケースでのみ追加ファイルが読み込まれるという効率的な動作が実現します。

scriptsディレクトリの活用

スキルディレクトリにはシェルスクリプトも配置できます。scripts/に置いたスクリプトは、Claude Codeのコンテキストを消費せずに実行されるため、重い検証処理やデータ取得を効率的に行えます。

# scripts/validate-config.sh の例
#!/bin/bash
# 設定ファイルの整合性チェック

echo "=== 設定ファイル検証 ==="

# .envファイルの存在確認
if [ ! -f ".env" ]; then
  echo "ERROR: .env ファイルが見つかりません"
  exit 1
fi

# 必須環境変数の確認
required_vars=("DATABASE_URL" "API_KEY" "NODE_ENV")
for var in "${required_vars[@]}"; do
  if ! grep -q "^${var}=" .env; then
    echo "WARNING: ${var} が .env に未設定"
  fi
done

echo "=== 検証完了 ==="

レッスン4: descriptionの書き方 ― 自動マッチングを制する

スキルにはスラッシュコマンド（/deploy-checkerのように明示的に呼び出す方法）のほかに、Claude Codeが会話の文脈から自動的に適切なスキルを選んで適用する「自動マッチング」の仕組みがあります。

この自動マッチングの精度を左右するのが、YAMLフロントマターのdescriptionフィールドです。

# NG例: 曖昧なdescription
---
name: deploy-checker
description: デプロイに関するスキル
---

# OK例: 具体的なdescription
---
name: deploy-checker
description: |
  本番環境へのデプロイ前に実行するチェックリスト。
  テスト実行、lint検証、環境変数の確認、マイグレーション
  の適用状態、ビルドの成功を順次検証する。
---

descriptionには「いつ」「何を」「どのように」行うスキルなのかを250文字以内で具体的に記述します。Claude Codeはこの説明文を手がかりに、ユーザーの依頼内容とスキルをマッチングします。曖昧な記述では、呼ばれるべき場面で呼ばれない（偽陰性）や、不要な場面で呼ばれてしまう（偽陽性）が発生します。

disable-model-invocationの活用

自動マッチングをあえて無効にしたいケースもあります。例えばデプロイ実行スキルのような破壊的操作を含むスキルは、ユーザーの明示的な意思なく実行されるべきではありません。

---
name: deploy-production
description: 本番環境へのデプロイを実行する
disable-model-invocation: true    # 自動実行を無効化
---

# 本番デプロイ

⚠️ このスキルは /deploy-production コマンドでのみ実行されます。

1. mainブランチの最新コミットを確認
2. ステージング環境でのテスト結果を確認
3. `git push origin main:production` を実行
4. デプロイ完了を監視

レッスン5: スキルの共有と配布 ― チームからエンタープライズまで

スキルは個人で使うだけでなく、チーム全体、さらには組織全体に配布できます。このレッスンでは3つの配布方法を学びます。

方法1: リポジトリへのコミット（チーム共有）

最もシンプルな共有方法です。スキルをプロジェクトの.claude/skills/ディレクトリに置いてgitにコミットするだけです。

# プロジェクトのディレクトリ構造
my-project/
  .claude/
    skills/
      deploy-checker/
        SKILL.md
      code-reviewer/
        SKILL.md
        reference/
          review-criteria.md
  src/
  package.json
  CLAUDE.md

リポジトリをクローンした全員が同じスキルを使えます。新しいメンバーがチームに参加しても、スキルがそのまま使えるため、Claude Codeの使い方のオンボーディングコストが大幅に下がります。

方法2: プラグインとしての配布（広域共有）

スキルをnpmパッケージとして公開し、他のプロジェクトからインストールして使えるようにする方法です。社内の複数プロジェクトで共通のスキルを使いたい場合や、オープンソースとして公開したい場合に適しています。

# スキルのnpmパッケージ化
{
  "name": "@myorg/claude-skills-frontend",
  "version": "1.0.0",
  "description": "フロントエンド開発用Claude Codeスキルパック",
  "files": [
    "skills/"
  ]
}

方法3: エンタープライズ管理設定（組織展開）

Claude for Enterpriseを導入している組織では、管理者がスキルを組織全体に一括配布できます。セキュリティポリシーに基づくレビュースキル、コンプライアンスチェックスキルなどを全社員に強制適用できるため、ガバナンスの確保に有効です。

レッスン6: サブエージェント連携とトラブルシューティング

最後のレッスンでは、スキルをサブエージェントに紐づけて専門タスクを委譲する方法と、スキルに関するよくある問題の解決方法を学びます。

サブエージェントとの連携

Claude Codeには「サブエージェント」という機能があり、メインのClaude Codeとは別のコンテキストで独立した処理を実行できます。スキルをサブエージェントに紐づけることで、メインの会話のコンテキストを汚さずに専門タスクを実行できます。

# SKILL.md内でサブエージェント用の指示を定義
---
name: security-audit
description: |
  コードベースのセキュリティ監査を実施する。
  依存パッケージの脆弱性、ハードコードされた秘密情報、
  SQLインジェクション等の脆弱性を検出して報告する。
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# セキュリティ監査

このスキルはサブエージェントとして実行されます。
メインの会話とは独立したコンテキストで動作します。

## チェック項目

1. `npm audit` で依存パッケージの脆弱性を確認
2. ソースコード内のハードコードされた秘密情報を検索
3. SQLクエリの動的構築箇所を検出
4. 認証・認可の実装漏れを確認

## 報告フォーマット

| 重要度 | 箇所 | 内容 | 推奨対応 |
|--------|------|------|----------|
| ... | ... | ... | ... |

よくあるトラブルと解決法

コースの最後では、実務でよく遭遇するスキル関連の問題と対処法を学びます。

• スキルがトリガーされない ― descriptionの記述が曖昧、またはユーザーの指示とdescriptionが乖離している。descriptionをより具体的に書き直す
• 意図しないスキルが発動する ― 複数スキルのdescriptionが類似しすぎている。各スキルの適用範囲を明確に区別する記述に変更する
• スキルの優先度が競合する ― 個人スキルとプロジェクトスキルで矛盾が発生。プロジェクトスキルが優先されるルールを理解し、個人スキルの記述を調整する
• コンテキスト不足でスキルの品質が低い ― SKILL.mdの指示が不十分。referenceディレクトリに補足資料を追加し、Progressive Disclosureを適用する
• スクリプトの実行エラー ― パスの問題、権限の問題、環境依存の問題。スクリプトに適切なエラーハンドリングを追加する

実用的なスキル例 ― 今日から使えるスキルレシピ

ここからはコースの内容を踏まえて、実際の開発現場ですぐに使えるスキルの具体例をいくつか紹介します。自分のプロジェクトに合わせてカスタマイズしてみてください。

例1: コミットメッセージ生成スキル

---
name: commit
description: |
  ステージングされた変更を分析し、Conventional Commits形式の
  日本語コミットメッセージを生成する。
allowed-tools:
  - Bash
  - Read
---

# コミットメッセージ生成

## 手順
1. `git diff --staged` でステージングされた変更を確認
2. 変更の性質を分析（新機能、バグ修正、リファクタリング等）
3. Conventional Commits形式でメッセージを生成

## フォーマット
```
type(scope): 日本語の要約（50文字以内）

変更の詳細説明（必要に応じて）
```

## type一覧
- feat: 新機能
- fix: バグ修正
- refactor: リファクタリング
- docs: ドキュメント変更
- style: コードフォーマット
- test: テスト追加・修正
- chore: 雑務（ビルド設定、依存更新等）

例2: PR作成スキル

---
name: create-pr
description: |
  現在のブランチの変更内容を分析し、GitHub PRを作成する。
  タイトル、概要、テスト計画を自動生成する。
---

# PR作成

## 手順
1. `git log main..HEAD` でコミット履歴を取得
2. `git diff main...HEAD` で全変更差分を確認
3. 変更の全体像を把握し、PRタイトルと概要を作成
4. `gh pr create` でPRを作成

## PRテンプレート
```markdown
## 概要
（変更の目的と背景を1-3文で）

## 変更内容
- （箇条書きで主な変更点）

## テスト計画
- [ ] （テスト項目）

## スクリーンショット
（UIの変更がある場合）
```

例3: コードレビュースキル

---
name: review
description: |
  指定されたファイルまたはPRのコードをレビューする。
  バグ、パフォーマンス、セキュリティ、可読性の4観点で
  フィードバックを提供する。
allowed-tools:
  - Read
  - Grep
  - Glob
---

# コードレビュー

## レビュー観点
1. **バグ**: ロジックエラー、エッジケースの未処理、型の不整合
2. **パフォーマンス**: N+1問題、不要な再レンダリング、メモリリーク
3. **セキュリティ**: インジェクション、XSS、秘密情報の露出
4. **可読性**: 命名、関数の長さ、コメントの適切さ

## 報告フォーマット
各指摘は以下の形式で報告:
- 🔴 Critical: 即座に修正が必要
- 🟡 Warning: 修正を推奨
- 🔵 Suggestion: より良いコードのための提案
- 💡 Nitpick: 些細な改善点

コースを最大限活用するためのコツ

ただコースを見るだけと、実際に手を動かしながら受講するのでは、身につくスキル（技能としてのスキル）のレベルが全く異なります。以下のコツを意識してみてください。

コツ1: 自分のワークフローの「繰り返し」を棚卸しする

受講前に、日々の開発で「毎回やっている定型作業」をリストアップしましょう。コミットメッセージの作成、PRの作成、コードレビュー、デプロイ、テスト実行、ドキュメント更新など。このリストが、あなたが作るべきスキルの候補リストになります。

コツ2: 最初のスキルは「小さく・具体的に」

いきなり「全部入りデプロイスキル」を作ろうとせず、まずは1つの明確なタスクだけを行うスキルから始めましょう。例えば「git statusを見てコミットメッセージを提案するだけ」のスキル。小さく作って動作を確認し、そこから徐々に拡張していくのが失敗しないアプローチです。

コツ3: CLAUDE.mdとスキルの分離を実践する

コース受講中に、自分のプロジェクトのCLAUDE.mdを見直してみましょう。「これはCLAUDE.mdに書くべき内容か？ スキルに分離すべきか？」という目で見ると、たいていの場合CLAUDE.mdには不要な情報が含まれています。分離の判断基準は「毎セッション必要か」「特定タスクでのみ必要か」です。

コツ4: チームメンバーにスキルを共有する

作ったスキルをプロジェクトの.claude/skills/にコミットし、チームメンバーにフィードバックをもらいましょう。「このスキルが自動で呼ばれるべきシナリオ」を他の人にも確認してもらうことで、descriptionの精度が上がります。

CLAUDE.md・Hooks・MCPとの関係を整理する

スキルはClaude Codeのカスタマイズ手段のひとつですが、他の手段との関係を理解しておくことで、より効果的な設計ができます。

CLAUDE.md + スキル = 最強の組み合わせ

CLAUDE.mdにはプロジェクトの基本ルール（コーディング規約、セキュリティポリシー、ディレクトリ構成）を書き、特定タスクの詳細な手順はスキルに分離する。この2つは対立するものではなく、補完関係にあります。

# CLAUDE.md（常時読み込み）
- コーディング規約: TypeScript, ESLint, Prettier
- セキュリティ: .envをgitに含めない
- テスト: PR前にテストを必ず実行

# .claude/skills/deploy-checker/SKILL.md（必要時のみ読み込み）
- ステージング環境へのデプロイ手順（20ステップ）
- 環境変数の設定値一覧
- ロールバック手順

Hooks + スキル = 自動化の深化

Hooksはイベントドリブン（コマンド実行前後に自動発火）、スキルはタスクドリブン（特定タスクで読み込まれる）です。組み合わせることで、スキルの実行結果をHooksで自動検証するといった高度な自動化が可能になります。

MCP + スキル = 外部連携の拡張

MCP（Model Context Protocol）は外部ツールやAPIとの接続を担います。スキルの中でMCPを活用すれば、外部サービスと連携した高度なワークフローを構築できます。例えば「JIRAのチケット情報をMCP経由で取得し、スキルの指示に基づいてPR descriptionに自動反映する」といった運用です。

次に進むコース ― スキルの先にあるもの

Introduction to Agent Skillsを修了したら、あなたの目的に応じて次のコースを選びましょう。

• Claude APIでアプリを作りたい → Building with the Claude API（Python/TypeScriptでClaude をアプリに組み込むコース。スキルで学んだ「再利用可能な指示設計」の知識がAPI設計にも活きます）
• 外部ツールとの連携を深めたい → Introduction to MCP（Model Context Protocolで外部サービスと接続するコース。スキルとMCPの組み合わせで高度なワークフローが可能に）
• より高度なClaude Code活用を学びたい → Agentic Patterns in Claude Code（マルチエージェントパターン、並列処理、エラーハンドリングなどの上級テクニック）
• プロンプトエンジニアリングを深めたい → Real World Prompting（実務で使えるプロンプト設計のコース。スキルのSKILL.mdに書く指示の品質向上に直結します）

まとめ ― Claude Codeを「自分専用ツール」に育てる

Introduction to Agent Skillsは、Claude Codeを「汎用AIアシスタント」から「自分のワークフローに最適化された専門ツール」に変える方法を教えてくれるコースです。

• スキルとは: Markdownで書いた再利用可能な指示ファイル。Claude Codeに特定タスクの専門知識を教える仕組み
• SKILL.mdの構造: YAMLフロントマター（name, description, allowed-tools等）+ Markdown本文（指示内容）
• Progressive Disclosure: SKILL.mdには概要だけ書き、詳細はreferenceディレクトリに分離。コンテキストウィンドウを効率的に使う
• descriptionが鍵: 自動マッチングの精度はdescriptionの書き方で決まる。「いつ・何を・どのように」を具体的に書く
• 共有方法は3つ: gitリポジトリ（チーム）、npmパッケージ（広域）、エンタープライズ管理（組織全体）
• サブエージェント連携: 重い専門タスクはサブエージェントに委譲し、メインのコンテキストをクリーンに保つ
• まず「小さく」始める: 毎日やっている定型作業から1つ選んでスキル化する。そこから徐々に拡張していく

「Claude Codeは便利だけど、毎回同じことを説明するのが面倒」と感じている開発者は、このコースでスキルの作り方を学ぶことで日々の開発体験が劇的に変わります。自分だけの「開発パートナー」を育てる第一歩として、まずはこのコースから始めてみてください。