Claude Code Agent Skillsとは - エージェント機能の全体像

はじめに

Claude Codeには、AIの能力を拡張する「Agent Skills（エージェントスキル）」という機能があります。Agent Skillsは、特定のタスクや専門領域に最適化された知識やワークフローをClaude Codeに追加し、開発作業を効率化するための仕組みです。

本記事では、Agent Skillsの基本概念から、サブエージェントとの関係、利用可能なビルトインスキル、スキルの呼び出し方法まで詳しく解説します。この記事を読むことで、以下のことができるようになります。

• Agent Skillsの仕組みと設計思想を理解する
• サブエージェントとスキルの違いと連携方法を把握する
• ビルトインツールとカスタムスキルの活用方法を習得する
• スキルの作成とパラメータ設定を実践できる

実行環境

• オペレーティングシステム: macOS 10.15以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（WSL 1/2またはGit for Windows）
• ハードウェア: 4GB以上のRAM
• Node.js 18以上（npmインストールの場合のみ必要）
• インターネット接続（認証およびAI処理に必要）
• シェル環境: Bash、Zsh、またはFish推奨

前提条件

• Claude Codeがインストール済みであること
• コマンドライン操作の基礎知識
• プログラミングの基礎知識（言語は問わない）

Agent Skillsとは

Agent Skillsは、Claude Codeに特定の専門知識やワークフローを教えるためのMarkdownファイルです。PRレビューの基準、コミットメッセージの書式、データベーススキーマの操作方法など、タスクに特化したガイダンスをClaudeに提供します。

スキルの最大の特徴は「モデル起動型（model-invoked）」である点です。ユーザーが明示的にスキルを呼び出す必要はなく、リクエストの内容がスキルの説明と一致すると、Claudeが自動的にスキルを適用します。

flowchart TB
    A[ユーザーリクエスト] --> B{スキル説明と<br>マッチするか}
    B -->|Yes| C[スキル適用確認]
    C --> D[SKILL.md読み込み]
    D --> E[スキル指示に従って実行]
    B -->|No| F[通常の応答]

スキルの動作フロー

Claude Codeがスキルを使用する流れは以下の通りです。

1. 発見（Discovery）: 起動時にすべてのスキルの名前と説明を読み込む
2. 活性化（Activation）: リクエストがスキルの説明とマッチすると、使用確認を表示
3. 実行（Execution）: 確認後、SKILL.mdの全内容をコンテキストに読み込み、指示に従って動作

スキルの保存場所

スキルは保存場所によってスコープが異なります。

同名のスキルが存在する場合、優先度の高いスコープのスキルが適用されます。

スキルとサブエージェントの関係

Claude Codeには「スキル」と「サブエージェント」という2つのカスタマイズ機構があります。両者は目的と動作が異なりますが、連携して使用することも可能です。

機能の違い

連携のパターン

スキルとサブエージェントは以下のように連携できます。

パターン1: サブエージェントにスキルを付与

カスタムサブエージェントに特定のスキルを事前にロードさせることができます。

1
2
3
4
5

---
name: code-reviewer
description: Review code for quality and best practices
skills: pr-review, security-check
---

skillsフィールドにスキル名をカンマ区切りで指定すると、サブエージェント起動時にスキルがロードされます。ビルトインサブエージェント（Explore、Plan、汎用）にはスキルを付与できません。

パターン2: スキルをサブエージェントコンテキストで実行

スキルを独立したサブエージェントコンテキストで実行することも可能です。

1
2
3
4
5
6

---
name: code-analysis
description: Analyze code quality and generate detailed reports
context: fork
agent: general-purpose
---

context: forkを指定すると、スキルは別のサブエージェントコンテキストで実行されます。agentフィールドで使用するサブエージェントを指定できます。

使い分けの指針

flowchart TD
    A[タスクの性質を判断] --> B{コンテキストの<br>独立が必要?}
    B -->|Yes| C[サブエージェント]
    B -->|No| D{専門知識・<br>ガイダンスが主?}
    D -->|Yes| E[Agent Skills]
    D -->|No| F{ツール制限が<br>必要?}
    F -->|Yes| G[サブエージェント<br>or スキルのallowed-tools]
    F -->|No| H[通常のリクエスト]

ビルトインツール一覧

Claude Codeには、スキルやサブエージェントが使用できる多数のビルトインツールが用意されています。

主要ツール

その他のツール

ツールのパーミッション制御

ツールの使用許可はsettings.jsonで制御できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "WebFetch",
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

スキルファイルの構造

スキルはSKILL.mdというMarkdownファイルで定義します。ファイルはYAMLフロントマター（メタデータ）とMarkdown本文（指示）で構成されます。

基本構造

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
name: your-skill-name
description: スキルの説明（いつ使うべきか）
---

# スキル名

## 指示
Claudeへの具体的な指示を記述します。

## 例
スキルの使用例を示します。

メタデータフィールド

実践的なスキル例

コード説明スキル:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
name: explaining-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

読み取り専用スキル:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
name: reading-files-safely
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

When analyzing files:
- Only read, never modify
- Summarize findings clearly
- Highlight important patterns

allowed-toolsでツールを制限すると、スキル実行中はそのツールのみ許可なしで使用できます。

スキルの呼び出し方法

自動起動

スキルは通常、自動的に起動されます。ユーザーのリクエストがスキルのdescriptionフィールドとマッチすると、Claudeがスキルの使用を提案します。

1
2
3
4

> このコードの動作を説明して

Claude: explaining-codeスキルを使用してよいですか？
[y/n]

descriptionに「use PROACTIVELY」「MUST BE USED」などのフレーズを含めると、より積極的にスキルが使用されます。

手動起動

利用可能なスキルを確認するには、以下のように質問します。

1

> 利用可能なスキルは何ですか？

特定のスキルを明示的に使用したい場合は、スキル名を含めてリクエストします。

1

> explaining-codeスキルを使って、この関数の動作を説明して

スラッシュコマンドとの違い

スキルとスラッシュコマンドは目的が異なります。

スキルの作成手順

手順1: ディレクトリの作成

1
2
3
4
5

# 個人用スキル（全プロジェクトで利用可能）
mkdir -p ~/.claude/skills/my-skill

# プロジェクトスキル（リポジトリ内でのみ利用可能）
mkdir -p .claude/skills/my-skill

手順2: SKILL.mdの作成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

cat > ~/.claude/skills/commit-helper/SKILL.md << 'EOF'
---
name: commit-helper
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

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

## 指示

1. `git diff --staged`を実行して変更を確認
2. 以下の形式でコミットメッセージを提案:
   - 50文字以内のサマリー
   - 詳細な説明
   - 影響を受けるコンポーネント

## ベストプラクティス

- 現在形を使用
- whatとwhyを説明（howではない）
EOF

手順3: 動作確認

1

> 利用可能なスキルは何ですか？

commit-helperがリストに表示されれば成功です。

手順4: テスト

1

> コミットメッセージを作成して

スキルが自動的に適用され、指示に従ったコミットメッセージが生成されます。

複数ファイルで構成するスキル

複雑なスキルは、補助ファイルを使って構成できます。これにより、コンテキストを効率的に管理できます。

プログレッシブディスクロージャー

メインのSKILL.mdには概要を記述し、詳細は別ファイルに分離します。

1
2
3
4
5
6
7

pdf-processing/
├── SKILL.md              # 概要とクイックスタート
├── FORMS.md              # フォームフィールドの詳細
├── REFERENCE.md          # APIリファレンス
└── scripts/
    ├── fill_form.py      # フォーム入力ユーティリティ
    └── validate.py       # バリデーションスクリプト

SKILL.md:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction.
allowed-tools: Read, Bash(python:*)
---

# PDF処理

## クイックスタート

テキスト抽出:
\`\`\`python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

フォーム入力の詳細は[FORMS.md](FORMS.md)を参照。
APIリファレンスは[REFERENCE.md](REFERENCE.md)を参照。

## ユーティリティスクリプト

入力ファイルをバリデートするには:
\`\`\`bash
python scripts/validate.py input.pdf
\`\`\`

スクリプトは実行されるだけでコンテキストに読み込まれないため、トークンを節約できます。

スキルにフックを定義する

スキルのライフサイクルにフックを紐づけることができます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
name: secure-operations
description: Perform operations with additional security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
---

セキュリティ操作を実行する際は、すべてのBashコマンドをセキュリティチェックします。

once: trueオプションを指定すると、セッション中に一度だけ実行されます。

トラブルシューティング

スキルが起動しない

descriptionフィールドが曖昧な可能性があります。具体的なアクションとトリガーワードを含めてください。

1
2
3
4
5

# 悪い例
description: ドキュメントを処理する

# 良い例
description: PDFファイルからテキストとテーブルを抽出し、フォームに入力し、ドキュメントをマージする。PDF、フォーム、ドキュメント抽出に関するタスクで使用。

スキルがロードされない

ファイルパスを確認してください。

YAMLフロントマターの構文も確認してください。

• 1行目が---で始まること
• インデントにタブではなくスペースを使用していること
• フロントマターが---で終了していること

デバッグモードで確認

1

claude --debug

デバッグモードでスキルのロードエラーを確認できます。

ベストプラクティス

明確な説明を書く

descriptionはスキルのトリガーとなる重要なフィールドです。以下の2点を明確にしてください。

1. 何をするか: 具体的なアクションをリストアップ
2. いつ使うか: トリガーとなるキーワードを含める

SKILL.mdは500行以内に

長いSKILL.mdはコンテキストを圧迫します。詳細なリファレンスは別ファイルに分離し、必要なときだけ読み込ませてください。

ツールアクセスを最小限に

allowed-toolsで必要なツールのみを許可することで、セキュリティとフォーカスが向上します。

バージョン管理を活用

プロジェクトスキル（.claude/skills/）をGitで管理し、チーム全体で共有・改善できるようにしてください。

まとめ

Claude CodeのAgent Skillsは、AIの能力を特定のタスクや専門領域に最適化するための強力な仕組みです。本記事で解説した内容を振り返ります。

• Agent Skillsの基本: モデル起動型の専門知識追加機能。SKILL.mdで定義
• スキルとサブエージェントの違い: スキルはコンテキストに知識を追加、サブエージェントは独立したコンテキストでタスクを実行
• ビルトインツール: Read、Edit、Bash、Grep、Globなど多数のツールが利用可能
• スキルの構造: YAMLフロントマター（メタデータ）とMarkdown本文（指示）で構成
• 呼び出し方法: 自動起動（説明マッチ）または明示的な指示
• 複数ファイル構成: プログレッシブディスクロージャーでコンテキストを効率化

Agent Skillsを活用することで、チーム固有のワークフローや品質基準をClaude Codeに教え、開発効率を大幅に向上させることができます。まずは簡単なスキルから作成し、徐々に複雑なスキルへと発展させていってください。

参考リンク

• Claude Code公式ドキュメント
• Agent Skills - Claude Code Docs
• Subagents - Claude Code Docs
• Settings - Claude Code Docs
• Claude Code GitHubリポジトリ
• Equipping agents for the real world with Agent Skills