Equipping agents for the real world with Agent Skills
1. 概要
Anthropic が開発した**「Agent Skills（エージェントスキル）」**という新しい仕組みについて説明しています。
一言でいうと： AIエージェントに「専門知識」を教え込むための、ファイルとフォルダを使った仕組みです。
2. なぜ Agent Skills が必要なのか？
背景にある課題
Claude は非常に賢い AI ですが、以下のような場面では困ることがあります。
| 状況 | Claudeの限界 |
|---|---|
| 専門的な操作手順 | PDF のフォームを埋めるなど、具体的な操作方法は苦手 |
| 組織固有の文脈 | プロジェクト固有の命名規則や、チーム内の暗黙のルールは知らない |
Agent Skills の解決策
たとえ話で説明すると：
新入社員が入社したとき、「オンボーディングガイド（新人向けマニュアル）」を渡しますよね？Agent Skills は、まさに AI エージェント版のオンボーディングガイドです。
従来のやり方:
用途ごとに専用の AI を作る → 大変、管理が複雑
Agent Skillsのやり方:
汎用AIに「スキルブック」を渡す → 簡単、組み合わせ自由
3. Skill の構造（Anatomy of a Skill）
基本構成
Skillは**フォルダ（ディレクトリ）**として構成されます。最低限必要なのはSKILL.mdという1つのファイルだけです。
pdf-skill/ ← スキルのフォルダ
├── SKILL.md ← 必須ファイル（スキルの本体）
├── reference.md ← オプション（参考情報）
├── forms.md ← オプション（追加の手順書）
└── extract_form.py ← オプション（実行可能なスクリプト）
SKILL.mdファイルの書き方
SKILL.mdファイルには決まった形式があります。
---
name: PDF Processing
description: PDFファイルの読み取り、編集、フォーム入力を行うスキル
---
# PDF 処理スキル
このスキルはPDFファイルを操作するための手順を提供します。
## 基本的な使い方
...（ここに具体的な指示を書く）...
## 追加の参照
- フォーム入力については `forms.md` を参照
- 技術的な詳細は `reference.md` を参照
重要なポイント：
| 要素 | 説明 |
|---|---|
--- で囲まれた部分 |
YAMLフロントマターと呼ばれ、必須のメタデータ |
name |
スキルの名前（必須） |
description |
スキルの説明（必須）。Claudeはこれを見て「このスキルを使うべきか」を判断 |
| 本文部分 | 実際の指示や手順 |
4. Progressive Disclosure（段階的開示）
これが Agent Skills の最も重要な設計原則です。
概念の説明
たとえ話：本の読み方
本を読むとき、最初から最後まで全部読みますか？普通は：
- まず目次を見る（何が書いてあるか把握）
- 関係ある章だけ読む
- 必要なら詳細な付録を見る
Agent Skillsも同じ仕組みです。
レベル1: name + description（目次）
↓ 必要と判断したら
レベル2: SKILL.md 本文（該当する章）
↓ さらに詳細が必要なら
レベル3: 追加ファイル（付録・参考資料）
なぜこれが重要か？
AIにはコンテキストウィンドウという「一度に読める量の限界」があります。すべての情報を最初から読み込むと：
- 無駄にトークンを消費する
- 本当に必要な情報が埋もれる
- コストが上がる
段階的開示により、必要な情報だけを必要なときに読み込めます。
実際の流れ（図解）
┌─────────────────────────────────────────────────────┐
│ システムプロンプト（基本設定） │
├─────────────────────────────────────────────────────┤
│ インストール済みスキル一覧（nameとdescriptionのみ） │
│ ・PDF Processing: PDFの操作 │
│ ・Code Review: コードレビュー支援 │
│ ・Data Analysis: データ分析 │
├─────────────────────────────────────────────────────┤
│ ユーザーの質問:「このPDFのフォームを埋めて」 │
└─────────────────────────────────────────────────────┘
↓
Claude:「PDF関連だから PDF Processingスキルを使おう」
↓
┌─────────────────────────────────────────────────────┐
│ SKILL.md を読み込む │
│ 「フォーム入力は forms.md を参照」と書いてある │
└─────────────────────────────────────────────────────┘
↓
Claude:「フォーム入力だから forms.md も読もう」
↓
┌─────────────────────────────────────────────────────┐
│ forms.md を読み込む │
│ 具体的なフォーム入力の手順を取得 │
└─────────────────────────────────────────────────────┘
↓
Claude: フォームを正確に入力
5. スキルとコード実行
なぜコードを含めるのか？
LLM は多くのタスクが得意ですが、従来のプログラムの方が適している処理もあります。
| 処理 | LLMで実行 | コードで実行 |
|---|---|---|
| リストのソート | トークン生成で高コスト | ソートアルゴリズムで一瞬 |
| 数値計算 | 間違える可能性あり | 確実に正確 |
| ファイル操作 | テキストとして扱うしかない | 直接バイナリ操作可能 |
実例：PDFスキルでのコード実行
PDFスキルにはextract_form.pyというPythonスクリプトが含まれています。
# extract_form.py（イメージ）
import pypdf
def extract_form_fields(pdf_path):
"""PDFからすべてのフォームフィールドを抽出"""
reader = pypdf.PdfReader(pdf_path)
fields = reader.get_form_fields()
return fields
Claudeはこのスクリプトを：
- コンテキストに読み込まなくても実行できる
- 決定論的（毎回同じ結果）に処理できる
- 効率的に PDF を操作できる
6. スキルの開発・評価のベストプラクティス
記事では4つのガイドラインが示されています。
① 評価から始める（Start with evaluation）
❌ いきなりスキルを作り始める
✅ まず Claude に実際のタスクをやらせて、どこで躓くか観察する
具体例：
- Claudeにコードレビューを依頼
- 「うちの会社のスタイルガイドを知らないから、命名規則の指摘ができない」ことを発見
- → スタイルガイドをスキルとして作成
② スケールを考慮した構造化（Structure for scale）
SKILL.md が長くなりすぎたら...
悪い例:
SKILL.md に全部書く（1000行）
良い例:
SKILL.md（基本情報 + 目次）
├── setup.md（環境構築）
├── coding-standards.md（コーディング規約）
└── review-checklist.md（レビューチェックリスト）
③ Claudeの視点で考える（Think from Claude's perspective）
nameとdescriptionは特に重要です。なぜなら、Claude はこれを見て「このスキルを使うべきか」を判断するからです。
# 悪い例
name: skill1
description: 便利なスキル
# 良い例
name: ABEMA Video Clipping
description: ABEMAのニュース動画から特定シーンを切り出すための手順。
タイムコードの指定方法、出力形式、命名規則を含む。
④ Claudeと一緒にイテレーション（Iterate with Claude）
スキルを最初から完璧に作ろうとせず、Claudeと協力しながら改善していきます。
1. タスクをClaudeに依頼
2. うまくいった → 「今のアプローチをスキルに記録して」
3. うまくいかない → 「何が問題だったか振り返って」
4. 得られた知見をスキルに反映
5. 繰り返し