Agent Skills 記述ガイド
概要
Agent Skills（SKILL.md）を効果的に記述するためのプラクティスをまとめました。
Agent Skills は、Claude Code、Codex など複数のエージェントツールで採用されている形式です。標準化は途上であり、ツールごとに実装差があります。
「なぜそう書くのか」という背景から説明し、Progressive Disclosure（段階的開示）の考え方を理解した上で、効果的なスキルを書けるようになることを目的としています。
本記事を読むとできるようになること
- エージェントに「選ばれる」description が書ける
- SKILL.md と references/ をどう分けるか判断できる
- Skills と AGENTS.md/CLAUDE.md の使い分けができる
まず押さえる3点（忙しい人向け）
- description は「動詞 + Use when」で書く
- SKILL.md に全部書かない（長くなったら references/ へ分割）
- 単一目的の作業での原則は Skills、全作業共通なら AGENTS.md/CLAUDE.md
なぜ Skills の書き方が重要か
エージェントはどうやってスキルを選ぶのか
多くの実装では、エージェントは起動時に利用可能な全スキルの メタデータ(SKILL.md の Frontmatter) を読み込みます。
---
name: スキル名
description: 説明文
---
重要なのは、スキルの本文（SKILL.md の Markdown 部分）はこの段階では読まれない ことが多いという点です。description は「選ばれるかどうか」を決める入口であり、実際の振る舞いを制御するのは SKILL.md 本文です。
description は、LLM がスキルを使うかどうか判断する際の 主要な材料 です。
| description の質 | 結果 |
|---|---|
| 曖昧・抽象的 | スキルが選ばれない（または間違った場面で選ばれる） |
| 具体的・明確 | 適切な場面でスキルが選ばれ易くなる |
description はスキルの「表紙」です。ここを間違えると、どれだけ良い内容を書いても使われにくくなります。
※ 実装によって挙動は異なり、description だけでは自動選択されず明示的な指定が必要な場合もあります。
Progressive Disclosure（段階的開示）
Agent Skills の基本的な設計思想として、コンテキストは段階的にロードされます。
Tier 1: メタデータ（name, description）
→ 常時ロード
Tier 2: SKILL.md 本文
→ スキル選択時にロード
Tier 3: references/, scripts/
→ 必要時にオンデマンドロード
この仕組みにより、多数のスキルを定義してもトークン効率が維持できることを目指しています。
※ 実際の挙動はツールによって異なります。この3段階構造は設計思想として理解してください。
「必要な情報を、必要なときに、必要な量だけ」渡す設計なので、SKILL.md に全てを詰め込む必要はありません。
Description の書き方
原則: 動詞 + "Use when:" パターン
description には以下を含めることが推奨されています。
- 何をするか（動詞から始める）
- いつ使うか（"Use when:" で明示）
# ❌ 悪い例: 名詞の羅列
description: "Testing principles, TDD process, coverage standards, mock guidelines."
# ⭕ 良い例: 動詞 + Use when
description: "Applies TDD process, test quality criteria, and mock guidelines. Use when: writing unit tests, using mocks, or reviewing test quality."
なぜ動詞から始めるのか
エージェントは「このスキルは何をするのか」を理解しようとします。名詞の羅列では何をするスキルなのか不明確で、複数の解釈が可能になってしまいます。
動詞から始めることで、スキルのアクションが明確になります。
| 開始パターン | エージェントの解釈 |
|---|---|
| "Testing principles..." | 「テストについて何か書いてある」（曖昧） |
| "Applies TDD process..." | 「TDDプロセスを適用するスキル」（明確） |
トリガーワードの選び方
"Use when:" 以降には、ユーザー（あなた）が実際に使う言葉を含めます。
# ❌ 抽象的すぎる
description: "... Use when: testing is needed."
# ⭕ 具体的なアクション
description: "... Use when: writing unit tests, using mocks, or reviewing test quality."
ユーザーが入力しそうな言葉（「ユニットテストを書く」「リファクタする」など）を動詞形で書きます。そして、トリガーワードは 3-5個程度に絞ります。多すぎる場合は責任範囲が広すぎる可能性があるので、後述する「単一責任の原則」を参考に、スキルを整理してください。
※ 多くの実装では、厳密なキーワードマッチではなく、「意味的に近い入力かどうか」で判断されます。そのため、人間が使う自然な表現を書くことが重要です。
単一責任の原則
description が長くなりすぎたら、スキルの分割を検討してください。
スキルの責任範囲が広い
→ カバーすべきトリガーワードが増える
→ description が肥大化
スキルの責任が単一
→ トリガーワードは自然と絞られる
→ description は簡潔になる
参考値として、description が200文字を超えたり、"Use when:" のケースが5個を超えたりしたら分割を検討します。description の長さは、スキル設計の健全性を測る指標になります。
本文の書き方
SKILL.md 本文や references の中身を書く際の原則は以下の通りです。書き方によって LLM の実行精度は大きく変わります。
最小記述で最大精度
コンテキストは貴重なリソースです。同じ意味なら短い表現を使います。ただし、曖昧になるほど短くしないでください。
❌ 冗長
エラーが発生した場合は必ずログに記録してください
⭕ 簡潔
エラーは全てログ記録必須
❌ 省略しすぎ
エラーは全て記録
重複を排除する
同じ内容を複数箇所に書くのはトークンの無駄遣いです。更新漏れによる矛盾も生じます。スキル間、SKILL.md と references で同じ内容を書かないように気をつけましょう。
測定可能な基準を設定する
曖昧な指示は解釈のブレを生みます。数値や具体的な条件で明確化します。
⭕ 測定可能
- 関数：30行以下
- 循環的複雑度：10以下
- カバレッジ：80%以上
❌ 曖昧
- 読みやすいコード
- 十分なテスト
※ 循環的複雑度: 分岐の多さを示す指標
NGパターンは「推奨 + 背景」で示す
NGは「ピンクの象問題（否定の文脈に反応した出力をしてしまう）」を誘発するため、極力肯定系の記述を行うことを心がけてください。セキュリティなど禁止事項を書くべき時には、以下のような「推奨 + 背景」形式でのNGの記載が効果的です。
⭕ 推奨形式
【状態管理】
推奨：Zustand または Context API
理由：グローバル変数はテスト困難、状態追跡が複雑
NG例：window.globalState = { ... }
❌ 禁止の羅列
- グローバル変数を使うな
- windowに値を保存するな
重要度順に配置する
LLM は冒頭の情報により注意を払います。最重要ルールを先頭に配置しましょう。
## 最重要原則（必ず守る）
1. 全APIはJWT認証必須
2. レート制限：100req/分
## 標準仕様
- メソッド：REST原則に従う
- ボディ：JSON形式
## 例外ケース（特殊な場合のみ）
- ファイルアップロード時のみ multipart 許可
スコープ境界を明確にする
何を扱い、何を扱わないかを明示します。
## このスキルの適用範囲
### 対象
- REST API全般
- GraphQLエンドポイント
### 対象外
- 静的ファイル配信
- ヘルスチェック（/health）
references/ と scripts/ の使い方
いつ分割すべきか
SKILL.md 本文が長くなりすぎると、トークン消費が増え、エージェントの注意が分散し、実行精度が低下し易くなります。
目安として、SKILL.md 本文が300行を超えてきたら分割を検討してください。適切な長さはツールやモデルにより異なります。行数はあくまでも目安です。
- 常に必要ではない詳細情報は references/ へ
- 実行可能なコードは scripts/ へ
ディレクトリ構造
my-skill/
├── SKILL.md # メインの指示（汎用的な原則）
├── references/ # 参照ドキュメント（オンデマンドロード）
│ ├── typescript.md # 例: 言語固有のルール
│ └── python.md
└── scripts/ # 実行可能スクリプト
└── validate.sh
references/ の効果的な使い方
例: 言語毎の実装パターンを記述する場合
SKILL.md: 言語非依存の汎用原則を書く
## Error Handling
**Absolute Rule**: Error suppression prohibited. All errors must have log output.
**Layer-Specific Error Handling**
- Presentation Layer: Convert to user-friendly messages
- Business Layer: Propagate domain-specific errors
- Data Layer: Convert technical errors to domain errors
references/typescript.md: TypeScript固有の実装パターンを書く
## Error Handling (TypeScript)
**Result Type Pattern**
\`\`\`typescript
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
function parseUser(data: unknown): Result<User, ValidationError> {
if (!isValid(data)) return { ok: false, error: new ValidationError() }
return { ok: true, value: data as User }
}
\`\`\`
SKILL.md から references を参照する
## Language-Specific References
For language-specific rules, also read:
- **TypeScript**: [references/typescript.md](references/typescript.md)
scripts/ の使い方
scripts/ には、実行が前提のスクリプトを配置します。バリデーション、lint、コード生成、セットアップ自動化などが典型的な用途です。
一方、読むだけで十分なもの（サンプルコード、パターン例）は references/ に置きます。
スクリプトは自己完結させ、外部依存がある場合は明記してください。
Skills に何を書くべきか
判断の軸
スキルに書くべきかどうかは「原則の成熟度」と「適用範囲」で判断します。
| 段階 | 説明 | 書く場所 |
|---|---|---|
| 単一作業のプラクティス | 特定の作業で「こうした」という経験 | まだ原則化できない ※1 |
| 単一目的の作業での原則 | 同じ目的の作業で繰り返し使える原則 ※2 | Skills |
| 全作業共通の原則 | プロジェクトの全ての作業に適用すべき原則 | AGENTS.md/CLAUDE.md |
※1: 書きすぎの罠
Skills や AGENTS.md/CLAUDE.md にプラクティスを書けば精度が上がると考えがちです。ですが、LLM は既に多くの一般的なプラクティスを知っています。「当たり前のこと」を書くことでコンテキストを圧迫し、結果本当に伝えたい情報への注意が薄まります。
書くべきは「あなたのプロジェクト固有の判断基準」やプラクティスを「いつ」「どのように使うか」です。この見極めにこそ、技術者としての経験が活きます。
※2: 再利用可能であること
単一の作業における事象ではなく「何度も同じ指摘をした」「他の作業でも使えそうと確信できた」状態になってから原則化をしましょう。その際、多くのケースを網羅できる汎用的な記載になっていることが望ましいです。ただし、抽象的すぎると判断基準として機能しません。「状況に応じて適切に判断する」のような記載は避けてください。
書くべきもの
Skills には「単一の目的を持つ作業」で繰り返し使える原則を書きます。
| カテゴリ | 例 |
|---|---|
| 技術プラクティス | TDDプロセス、エラーハンドリング方針 |
| 判断基準 | いつテストを書くか、いつリファクタするか |
| パターン | コードの構造パターン、命名規則 |
| チェックリスト | コード品質チェック、レビュー観点 |
書くべきでないもの
- まだ原則化できないもの: 特定の作業で一度使っただけのプラクティス
- 全作業に適用すべきもの: プロジェクト全体のルール（→ AGENTS.md/CLAUDE.md）
- プロジェクト固有の設定: 環境設定、チーム構成に依存するもの
ドメイン固有の知識（金融、医療、法律など）は Skills に書くべきです。LLM が一般知識として持っていない可能性が高く、その知識を補う素材として価値があります。
AGENTS.md/CLAUDE.md との境界
AGENTS.md/CLAUDE.md は「プロジェクトの全ての作業に適用すべき原則」を書く場所です。
| 項目 | Skills | AGENTS.md/CLAUDE.md |
|---|---|---|
| 適用範囲 | 特定の目的を持つ作業 | 全ての作業 |
| 内容 | 技術プラクティス・ドメイン知識 | プロジェクト固有のルール |
| 粒度 | 「テストを書くとき」「APIを設計するとき」 | 「このプロジェクトでは常に」 |
迷いやすい例
- 「このリポジトリでは Python 3.12 を使う」→ AGENTS.md/CLAUDE.md（全作業に適用）
- 「Python では例外を握りつぶさず Result 型で扱う」→ Skills（エラーハンドリング時の原則）
- 「コードレビューではセキュリティ観点を必ず確認する」→ Skills（レビュー時の原則）
アンチパターン
1. Description の名詞羅列
# ❌ エージェントが何をすべきか不明
description: "Code quality, refactoring, clean code principles, SOLID."
# ⭕ アクションが明確
description: "Applies clean code principles and refactoring techniques. Use when: refactoring code, reviewing code quality, or improving maintainability."
2. SKILL.md への詰め込みすぎ
# ❌ 1ファイルに全て詰め込む（3000行）
## TypeScript Rules
## Python Rules
## Go Rules
## Testing Rules
## Documentation Rules
...
# ⭕ 責任ごとに分割
# coding-rules/SKILL.md （汎用原則のみ）
# coding-rules/references/typescript.md
# testing/SKILL.md （別スキルとして分離）
3. 曖昧なトリガーワード
# ❌ 曖昧すぎて、いつ使うか不明
description: "Helps with code. Use when: coding."
# ⭕ 具体的なシチュエーション
description: "Detects code smells and anti-patterns. Use when: fixing bugs, reviewing code quality, or refactoring."
4. ハードコードされたパス
# ❌ 環境依存
Read the config at /home/user/project/config.json
# ⭕ 相対パスを使用
Read the config at ./config.json
実践チェックリスト
スキル作成時
- description は動詞から始まっているか
- "Use when:" でトリガー条件を明示しているか
- description は適切な長さか（長すぎたら分割検討）
- 単一責任になっているか
スキル本文
- 本文は適切な長さか（長すぎたら分割検討）
- 言語固有の詳細は references/ に分離しているか
- SKILL.md から references への参照を明記しているか
- 単一目的の作業で繰り返し使える原則か
レビュー観点
- 特定の目的を持つ作業での原則になっているか
- トリガーワードはユーザーが実際に使う言葉か
- 類似スキルとの責任境界は明確か
まとめ
| 原則 | 内容 |
|---|---|
| Progressive Disclosure | 必要な情報を、必要なときに、必要な量だけ |
| 動詞 + Use when | description は「何をするか」+「いつ使うか」 |
| 単一責任 | description が長くなったら分割を検討 |
| 分離 | 言語固有は references/、実行可能は scripts/ |
| 境界 | 単一目的の作業での原則は Skills、全作業共通の原則は AGENTS.md/CLAUDE.md |
参考文献
- Agent Skills Specification - 仕様ドキュメント（コミュニティ主導）
- Equipping agents for the real world with Agent Skills - Anthropic Engineering Blog
- Claude Agent Skills: A First Principles Deep Dive - 技術的な深堀り分析
- GitHub: anthropics/skills - Anthropic スキルリポジトリ
Discussion