Agent Skillsで実現する特化型エージェント構築 - Claudeの新機能を徹底解説

公開日 2025年10月19日(日)

最終更新日 2025年10月22日(水)

環境

MacOS Apple M4 Max Sequoia 15.1
Claude Code v2.0.20

この記事を読むことで得られるメリット

ここ数ヶ月にわたって実務でMCPサーバーの開発を行っているので、MCPと関連が深そう、かつ今後の機能に大きく影響してきそうなAgent Skillsについてかなりしっかりめに記事を書いてみた

AnthropicのAgent Skillsの仕組みと活用方法を理解できる
MCPとの違いを明確に理解し、使い分けができるようになる
実際にカスタムスキルを作成するための具体的な手順がわかる
トークン消費を最適化した効率的なエージェント開発手法を習得できる
段階的開示(Progressive disclosure)の設計原則を実務に活かせる

この記事を読むのにかかる時間

約15分

要約

AnthropicがリリースしたAgent Skillsは、トークン使用量を抑えながら汎用エージェントを特化型エージェントへと変換できる画期的な機能である。

自然言語で実行可能で、MCPよりも構築ハードルが低く、段階的開示という設計原則により効率的なコンテキスト管理を実現している。

SKILL.mdファイルを中心としたシンプルな構成で、複雑なワークフローも再利用可能なスキルの組み合わせで構築できる。Claude.ai、Claude Codeで利用可能で、今後さらなる機能拡張が予定されている。

Agent Skillsとは何か

Agent Skillsは、トークン使用量を最小限に抑えながら、これまでの汎用エージェントを「ニーズに合った特化型エージェントへと変換できる機能」
最大の特徴は、スキルを自然言語で実行できることである。スラッシュコマンドなどとは異なり、明示的に実行する必要がない。Claudeが必要と判断したら自動的に実行されるため、MCPと近い使用感を持っている
1つ1つの再利用可能なスキルを組み合わせることで、強力なワークフローを構築することも可能
作成したスキルはzipファイルにして共有できるため、複数人での利用時にシェアが簡単であることも大きなメリット
エージェントスキルは現在、Claude.ai、Claude CodeなどClaude全体でサポートされている。

MCPとの違いと棲み分け

自然言語で特定のタスクを実行できるという点ではMCPと近いが、いくつかの重要な違いがある。

MCPはサーバーを構築する必要があり、インフラストラクチャを構築しなければならない
MCP自体の概念を理解する必要があるため、スキルの方が構築のハードルがスキルの方が圧倒的に低い。
スキルには認証を組み込むことができない（保護リソースへのアクセス等は不可）
現時点ではClaude特有の機能であるため、MCPのようなオープンなプロトコルではない点

ただし、MCPと相容れないものではなく、スキルからMCPツールを呼び出して使うことも想定されている。つまり、両者は補完関係にあると言える。

Agent Skillsのデモ - 実際にできること

Anthropicが標準利用できるスキルをいくつか用意してくれている。

GitHub

GitHub - anthropics/skills: Public repository for Skills

具体的には以下のようなスキルが存在する:

canvas-design: .pngおよび.pdfドキュメントで美しいビジュアルアートを作成
slack-gif-creator: Slack向けに最適化されたアニメーションGIFを作成
skill-creator: スキル自体を作成するためのメタスキル

なお、2025年9月9日のアップデートでClaudeがファイル作成をできるようになったが、これは今回取り上げているSkillsの機能を利用している。

www.anthropic.com

Claude can now create and use files

実践例: シーケンス図作成スキル

開発でたびたび利用するシーケンス図を作成するドキュメント作成特化のエージェントを作成し、「OAuth認証のシーケンス図を作成して」と依頼したみたところ、アウトプットがかなり完成度が高く驚くほどである。

余談だが、このmermaid記法のテキストをdraw.ioに取り込み（配置→挿入→Mermaid）、色をつけたり見やすく編集することもできる。

Agent Skillsの構成

基本構造

.claude/skills/ 以下にSKILL.md（およびその関連ファイル群）を作成することで利用できるようになる。スキル=パッケージという考え方である。

sequence-diagram-creator/
  ├── SKILL.md

徹底されたコンテキスト最適化 - 段階的開示

Progressive disclosure(段階的開示)とは

エージェントスキルの柔軟性と拡張性を実現する中核的な設計原則である。これによりトークン消費量を最適化することにつながっている

Level 1: Metadata (always loaded)

スキルのメタデータは常時読み込まれる（SKILL.mdのnameとdescription）

Level 2: Instructions (loaded when triggered)

スキルの詳細な指示は、トリガーされた時に読み込まれる（SKILL.mdの本文

Level 3: Resources and code (loaded as needed)

リソースやコードは、必要に応じて読み込まれる（SKILL.mdから参照するファイルやソースコードなど

実行フロー

Claude起動時にメタデータを読み込む（各スキルの存在と使用タイミングのみを認識）
ユーザーがプロンプトを実行時、スキルの説明と一致すればClaudeがbash経由でファイルシステムからSKILL.mdを読み取る
必要に応じて、リファレンスのmdや、Claudeがbash経由で実行可能プログラム（fill_form.py、validate.pyなど）を実行する
プログラムは「コンテキストを消費せずに決定論的な操作を提供できる」点が重要である。

SKILL.mdの構造

スキルとはSKILL.mdファイルを含むディレクトリである。SKILL.mdには以下の構成が含まれる:

必須メタデータ（名前と説明）を含むYAMLフロントマター（スキルの概要）
本文（スキルの詳細）

スキル実行時、エージェントはスキルの内容全体を読み込まない。インストール済みの全スキルの名前と説明をシステムプロンプトに事前読み込みする。Claudeが現在のタスクに関連すると判断した場合のみ、SKILL.md全文を読み込んでコンテキストに読み込む仕組みである。

シーケンス図作成用スキルの例

.claude/skills/sequence-diagram-creator/SKILL.md

---
name: sequence-diagram-creator
description: Webアプリケーション開発におけるシーケンス図をMermaid記法で作成するスキル。ユーザー認証、CRUD操作、決済処理、ファイルアップロード、非同期処理、エラーハンドリングなどの一般的なWebアプリケーションの処理フローを視覚化する際に使用。「シーケンス図を作成」「フロー図を描いて」「処理の流れを図示」などのリクエストで利用。
---

# Sequence Diagram

## 概要

このスキルは、Webアプリケーション開発における各種処理フローをMermaid記法のシーケンス図として作成する。認証、CRUD操作、決済、ファイル処理、非同期処理、エラーハンドリングなど、一般的なWebアプリケーションで必要となるシーケンス図のパターンを網羅的にサポートする。

## 使用するタイミング
...割愛

フロントマターの制限

name: 最大64文字
description: 最大1024文字

(制限の詳細)

リファレンスディレクトリの活用

スキルの内容が複雑になると、SKILL.mdの肥大化を防ぐため、エージェントはスキル作成時に必要に応じて「references」ディレクトリを作成し、マークダウンファイルを作成する。
例えば以下の例では、ドキュメントを書く際のMermaidのシーケンス図記法の完全なリファレンスを用意し、Webアプリケーション開発でよく使用されるシーケンス図のパターンなども用意している:

sequence-diagram-creator/
  ├── SKILL.md
  └── references/
      ├── mermaid-syntax.md
      └── patterns.md

Claudeは必要に応じてのみ、それらをたどって発見することを選択できる。

SKILL.mdでのリファレンス呼び出し

それぞれのリファレンスドキュメントをバンドルして呼び出していることがわかる:

---
name: sequence-diagram-creator
description: Webアプリケーション開発におけるシーケンス図をMermaid記法で作成するスキル。ユーザー認証、CRUD操作、決済処理、ファイルアップロード、非同期処理、エラーハンドリングなどの一般的なWebアプリケーションの処理フローを視覚化する際に使用。「シーケンス図を作成」「フロー図を描いて」「処理の流れを図示」などのリクエストで利用。
---

# Sequence Diagram

## 概要
...割愛

## クイックスタート

### 基本的な作成手順

1. **要件の確認**: ユーザーがどのような処理フローの図を必要としているか確認
2. **パターンの選択**: `references/patterns.md` から適切なパターンを選択、または参考にする

...割愛

## Mermaid記法リファレンス

Mermaidのシーケンス図記法の詳細については、`references/mermaid-syntax.md` を参照すること。

SKILL.mdの概要、本文、リファレンス（SKILL.mdにバンドルされたファイル）をそれぞれ読み込むときにどれくらいトークンを消費するのかについてまとめた図がわかりやすい。(参考: Claude Docs - Level 3: Resources and code)

スキルにプログラムを含めることができる

スキルにはプログラムのソースコードを含めることができる。

「決定論的（特定の入力に対し、毎回同じ出力と状態遷移を実現）な信頼性という強いメリット」がプログラムにはある。そのため、スキルを構成する部分でこういった特性が求められる部分はコードを利用するという考え方に基づいている。

例えば、トークン生成によるリストのソートは、単純にソートアルゴリズムを実行するよりもはるかにコストがかかる。

重要な点として、「スクリプトのコードはコンテキストウィンドウに読み込まれない」 。トークンを消費するのは、スクリプトの出力（「検証に成功しました」や特定のエラーメッセージなど)のみである。これにより、Claudeが同等のコードをリアルタイムで生成するよりも、スクリプトの実行効率が大幅に向上する。

(参考ドキュメント)

VM環境の活用

スキルはClaudeのVM環境を活用し、プロンプトだけでは実現できない機能を提供する
Claudeはファイルシステムにアクセスできる仮想マシン上で動作するため、スキルは指示、実行コード、参考資料を含むディレクトリとして存在する
claude.aiでは、npmとPyPIからパッケージをインストールし、GitHubリポジトリからプルできる。(パッケージ依存関係について)

Agent Skillsの始め方

注意事項: カスタムスキルはサーフェス間（Claude.ai、Claude Code、API）で同期されない。スキルを使用するサーフェスごとに、スキルを個別に管理およびアップロードする必要がある。

Claude.aiでの利用

(公式ドキュメント)

1.設定→機能から「Code execution and file creation」を有効化

2.skill-creatorを有効化（skill-creatorでスキルを作成することで、後述するベストプラクティスに従ったスキルを生成できる

3.「チャットで試す」を選択するとそのままチャットに貼り付けられるので、「API定義書を作成するカスタムスキルを作成して」と依頼

4.スキルの作成が完了したら、スキルのパッケージをzipダウンロード

5.設定→機能からスキルをアップロード

なお、次の手順で説明するClaude Codeでスキルを作成し、それをzip化してアップロードすることも可能である。

Claude Codeでの利用

(公式ドキュメント)

Claude Codeのバージョンアップ

2.0.20以上が必要である:

claude update

カスタムスキル作成の依頼

> API定義書を作成するカスタムスキルを作成して

.claude/skills/以下にスキルのパッケージが生成される。個人スキルは~/.claude/skills/に、プロジェクトスキルは.claude/skills/に作成される。プラグインスキルも可能である。

生成されるスキルの例（長いのでところどころ割愛している

.claude/skills/api-spec-creator/SKILL.md

---
name: api-spec-creator
description: WebアプリケーションのAPI定義書をOpenAPI 3.0形式で作成するスキル。RESTful API、認証、CRUD操作、ファイルアップロード、ページネーション、エラーレスポンスなどの一般的なAPIエンドポイント定義を作成する際に使用。「API定義書を作成」「OpenAPI仕様を書いて」「APIドキュメントを生成」などのリクエストで利用。
---

# API Spec Creator

## 概要

このスキルは、WebアプリケーションのAPI定義書をOpenAPI 3.0 (Swagger) 形式で作成する。RESTful APIの設計、認証スキーム、エンドポイント定義、リクエスト/レスポンススキーマ、エラーハンドリングなど、実践的なAPI定義書作成をサポートする。

## 使用するタイミング

以下のようなリクエストがあった場合、このスキルを使用してAPI定義書を作成する:

- 「ユーザー管理APIの定義書を作成して」
- 「商品カタログAPIのOpenAPI仕様を書いて」
- 「認証APIのドキュメントが欲しい」
- 「ファイルアップロードAPIの仕様を定義して」
- 「既存のAPIをOpenAPI形式で文書化して」

## クイックスタート

### 基本的な作成手順

1. **要件の確認**: どのようなAPIが必要か、エンドポイント、認証方式、データ構造などを確認
2. **パターンの選択**: `references/api-patterns.md` から適切なパターンを選択、または参考にする
3. **カスタマイズ**: ユーザーの具体的な要件に合わせてAPI定義をカスタマイズ
4. **YAML形式で出力**: OpenAPI 3.0形式のYAMLファイルとして出力

### 簡単な例

ユーザーから「ユーザー一覧取得APIの定義書が欲しい」とリクエストされた場合:

1. `references/api-patterns.md`の「2.2 データ取得API (Read)」を参照
2. ユーザーの環境に合わせてパス、パラメータ、レスポンススキーマをカスタマイズ
3. OpenAPI YAMLファイルとして出力

## 主な機能

### 1. 認証・認可パターン

JWT認証、OAuth 2.0、APIキー認証など、各種認証スキームの定義を作成できる。

**使用例:**
- JWT Bearer認証
- OAuth 2.0フロー
- APIキー認証
- Basic認証

**詳細:** `references/api-patterns.md` の「1. 認証・認可パターン」を参照

## リファレンスファイル

このスキルには以下のリファレンスファイルが含まれている。必要に応じて読み込んで参照すること:

### references/api-patterns.md

WebアプリケーションのAPI設計でよく使用される6つのカテゴリのパターン集:
- 認証・認可パターン
- CRUD操作パターン
- ページネーション・フィルタリング
- ファイル処理パターン
- バッチ操作パターン
- エラーレスポンスパターン

**使用タイミング:** ユーザーのリクエストに該当するAPIパターンがありそうな場合、このファイルを読み込んで適切なパターンを参照する。

### references/openapi-syntax.md

OpenAPI 3.0仕様の完全なリファレンス:
- 基本構造
- パラメータ定義
- リクエスト・レスポンス定義
- スキーマとバリデーション
- 認証設定
- ベストプラクティス

**使用タイミング:** OpenAPI仕様の詳細な構文が必要な場合、または高度な機能（oneOf、allOf、discriminatorなど）を使用する場合に参照する。

## 補足

### Swagger UIでの確認

作成したOpenAPI定義は、Swagger UIで視覚的に確認できる:

```bash
# Swagger UIをDockerで起動
docker run -p 8080:8080 -e SWAGGER_JSON=/api/openapi.yaml -v $(pwd):/api swaggerapi/swagger-ui

リファレンスファイル

.claude/skills/api-spec-creator/referencesには、2つのリファレンスが生成される:

api-patterns.md: WebアプリケーションのAPI設計でよく使用されるOpenAPI 3.0パターンのコレクション
openapi-syntax.md: OpenAPI 3.0仕様の完全なリファレンス。実践的なAPI定義書を作成するための構文、ベストプラクティス、よくあるパターン

allowed-toolsの指定

フロントマター箇所に、allowed-toolsを指定することも可能である。以下の例では、Read、Grep、Globを、許可を求めることなく使用できるようになる:

---
name: api-spec-creator
description: WebアプリケーションのAPI定義書をOpenAPI 3.0形式で作成するスキル。RESTful API、認証、CRUD操作、ファイルアップロード、ページネーション、エラーレスポンスなどの一般的なAPIエンドポイント定義を作成する際に使用。「API定義書を作成」「OpenAPI仕様を書いて」「APIドキュメントを生成」などのリクエストで利用。
allowed-tools: Read, Grep, Glob
---

スキル一覧の確認

作成したスキルを確認したい場合は、「利用可能なスキルの一覧を教えて」などと依頼すると応答してくれる:

このリポジトリで利用可能なスキルは以下の2つです:
1. api-spec-creator
2. sequence-diagram-creator

実際の生成結果

最終的に以下のようなAPI定義書が生成される:

プロンプト:

ログイン、ログアウト、会員登録など基本的な認証周りのAPI定義書を作成して

生成されたファイル: authentication-api-spec.yaml

openapi: 3.0.3
info:
  title: 認証API
  description: |
    ユーザー認証に関するAPI定義書です。
    会員登録、ログイン、ログアウト、トークンリフレッシュなどの基本的な認証機能を提供します。

    ## 認証方式
    JWT Bearer認証を採用しています。ログイン後に発行されるアクセストークンをAuthorizationヘッダーに含めてリクエストしてください。

    ```
    Authorization: Bearer {access_token}
    ```
...

かなりしっかりとしたものを作成してくれる。

Agent Skillsを利用できるプラン

スキルはPro、Max、Team、Enterpriseの各プランで利用可能である。

ベストプラクティス

すべてのモデルでテスト

スキルはモデルへの追加機能として機能し、その効果は基盤となるモデルによって異なる。スキルを使用する予定のすべてのモデルでテストすること。

(参考)

Opusでは完璧に動作するものが、Haikuではより詳細な説明が必要になる場合がある。スキルを複数のモデルで使用する予定の場合は、すべてのモデルで問題なく動作する説明を目指すことが重要である。

命名規則

スキル名には、そのスキルが提供するアクティビティや機能を明確に表す動名詞（動詞 + -ing）を使用することが推奨される。ちなみに、xxx-creatorやxxx-builderなどの形式でも良さそう（Claudeが標準で提供しているスキルを見る限り）

(参考)

SKILL.mdのサイズ制限

最適なパフォーマンスを得るには、SKILL.md本体を500行以下にすること。

(実践的なガイダンス)

この制限に近づいたら、コンテンツを別々のファイルに分割する。以下のパターンを使用して、指示、コード、リソースを効果的に整理すること。

SkillsからMCPツールを呼び出す際の注意事項

「ツールが見つかりません」というエラーを回避するために、常に完全修飾ツール名（ServerName:tool_name）を使用すること

(参考)

Agent Skillsの今後の展望

Agent Skillsはまだその片鱗しか見せていない。

今後数週間にわたり、スキルの作成、編集、発見、共有、そして利用というライフサイクル全体をサポートする機能が追加される予定である。

Anthropicは、スキル作成ワークフローの簡素化と企業全体の展開機能の実現に取り組んでおり、組織がチーム間でスキルをより簡単に配布できるようにしている。

外部ツールやソフトウェアを必要とするより複雑なワークフローをエージェントに教えることで、モデルコンテキストプロトコル(MCP)サーバーを補完するスキルの活用方法についても検討していく予定である。

(参考: Equipping agents for the real world with Agent Skills - The future of Skills)

まとめ

Agent Skillsは、Claudeの汎用性を保ちながら特定のタスクに特化したエージェントを構築できる革新的な機能である。段階的開示によるトークン最適化、自然言語での実行、MCPとの補完関係、そしてシンプルな構成により、開発者は効率的にカスタムスキルを作成できる。SKILL.mdとリファレンスファイルの組み合わせにより、複雑なワークフローも整理された形で実装可能である。今後のライフサイクル全体のサポート強化により、さらに実用的なツールとなることが期待される。

Agent Skillsで実現する特化型エージェント構築 - Claudeの新機能を徹底解説

目次

環境

この記事を読むことで得られるメリット

この記事を読むのにかかる時間

要約

Agent Skillsとは何か

MCPとの違いと棲み分け

Agent Skillsのデモ - 実際にできること

実践例: シーケンス図作成スキル

Agent Skillsの構成

基本構造

徹底されたコンテキスト最適化 - 段階的開示

Progressive disclosure(段階的開示)とは

Level 1: Metadata (always loaded)

Level 2: Instructions (loaded when triggered)

Level 3: Resources and code (loaded as needed)

実行フロー

SKILL.mdの構造

シーケンス図作成用スキルの例

フロントマターの制限

リファレンスディレクトリの活用

SKILL.mdでのリファレンス呼び出し

スキルにプログラムを含めることができる

VM環境の活用

Agent Skillsの始め方

Claude.aiでの利用

Claude Codeでの利用

Claude Codeのバージョンアップ

カスタムスキル作成の依頼

生成されるスキルの例（長いのでところどころ割愛している

リファレンスファイル

allowed-toolsの指定

スキル一覧の確認

実際の生成結果

Agent Skillsを利用できるプラン

ベストプラクティス

すべてのモデルでテスト

命名規則

SKILL.mdのサイズ制限

SkillsからMCPツールを呼び出す際の注意事項

Agent Skillsの今後の展望

まとめ

参考