Agent Skills Best Practices

agentskills.io 仕様準拠 — プロ品質スキルの設計・検証・改善ガイド

1 — 概要
このガイドについて

Agent Skills Best Practices は、Anthropic 公式ドキュメントを凝縮した実践ガイドと、プロ品質スキルを生成するための skill-creator スキル本体を含むリポジトリ。スキルの設計から LLM を使ったバリデーションまでを体系化している。

<500
SKILL.md 行数上限
1,024
description 文字数上限
4
バリデーションフェーズ
1深
サブディレクトリ上限
スキルはエージェント向け、人間向けではない。 README.md や CHANGELOG.md は作らない。エージェントがすでに問題なくこなすタスクのための命令は省く。
2 — ディレクトリ構成
必須レイアウト

すべてのスキルは以下のディレクトリ構造に従う。サブフォルダのネストは 1 段のみ。

skill-name/
├── SKILL.md              # Required: メタデータ + コア手順（<500 行）
├── scripts/              # Python / Bash の小さな CLI
├── references/           # API ドキュメント・スキーマ・チートシート
└── assets/               # 出力テンプレート・JSON スキーマ・静的ファイル
各フォルダの役割
フォルダ用途禁止事項
SKILL.md高レベル手順・ナビゲーション。スキルの「脳」500 行超、大きなスキーマのインライン記述
scripts/決定論的タスク用の小さな CLI スクリプトライブラリコード・長期間使うロジック
references/API ドキュメント・ドメイン固有ロジック・チートシートネストしたサブフォルダ（1 段のみ許可）
assets/出力テンプレート・JSON スキーマ・画像人間向けドキュメント（README など）
3 — フロントマター最適化
発見可能性

エージェントがスキルをトリガーするかどうかは、name と description だけに基づいて判断する。この 2 フィールドの最適化が最重要。

---
name: angular-vite-migrator
description: >
  Migrates Angular CLI projects from Webpack to Vite and esbuild.
  Use when updating builder configs or replacing webpack plugins.
  Don't use for React/Vue projects or general Angular upgrades.
---
ルール一覧
フィールド制約ポイント
name1–64 文字、小文字・数字・単一ハイフンのみ親ディレクトリ名と完全一致が必須
description最大 1,024 文字第三者的命令形（I/you 禁止）
トリガー"Use when…" を明記曖昧な記述は誤トリガーの原因に
ネガティブトリガー"Don't use for…" を明記類似スキルとの誤区別を防ぐ
Bad — 曖昧すぎる
description: "React skills."
Good — 明確なトリガー付き
description: "Creates React components with Tailwind. Use for UI logic. Don't use for Vue/Svelte."
4 — コンテキスト管理（Progressive Disclosure）
コンテキストウィンドウを守る

SKILL.md はナビゲーションと高レベル手順のみを持つ「脳」として機能する。詳細はサブディレクトリに移し、必要なときだけ読むよう指示（Just-in-Time Loading）する。

JiT ローディングの例: "See references/auth-flow.md for specific error codes" のように、エージェントがファイルを読むタイミングを SKILL.md から明示的に指示する。指示がなければエージェントは読まない。
削除すべきもの
  • 人間向けドキュメント — README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
  • 冗長な命令 — エージェントが既に問題なくこなすタスクへの指示
  • ライブラリコード — 長期運用するコードは標準 CLI ディレクトリへ
  • ネストされたサブフォルダ — references/db/v1/schema.md のような 2 段以上のパス
5 — 手順の書き方
第三者的命令形で書く

LLM 向けの命令は 第三者的命令形（Third-Person Imperative）で記述する。

Bad

"I will extract the text…"
"You should extract…"

Good

"Extract the text…"
"Run the build script…"

ステップ番号・テンプレート・用語の統一
  • ステップ番号付きで時系列に並べる — 分岐がある場合は「If … run X. Otherwise skip to Step 3.」のように明示
  • 具体的なテンプレートを用意 — エージェントはパターンマッチングが得意。JSON 出力の説明より assets/ にテンプレートファイルを置く
  • 用語を統一 — Angular なら「html」でなく「template」など、ドメイン固有の正確な語を一貫して使う
6 — スクリプトの活用
決定論的タスクはスクリプトへ

複雑なパース・反復するボイラープレートを毎回 LLM に書かせない。scripts/ にテスト済みスクリプトを配置し、エージェントに実行させる。

## Step 1: メタデータのバリデーション
python3 scripts/validate-metadata.py \
  --name "skill-name" \
  --description "Action-oriented description..."
# 成功: SUCCESS: Metadata is valid and optimized for discovery.
# 失敗: stderr に NAME ERROR / DESCRIPTION ERROR / STYLE WARNING
スクリプト設計の原則
  • CLI として設計 — 引数を受け取り、stdout/stderr で結果を返す
  • 詳細なエラーメッセージ — エージェントが自己修正できるよう「NAME ERROR: 'foo' is 65 chars」のように具体的に
  • 単一目的 — 1 スクリプト 1 タスク。複雑なロジックは標準 CLI へ
  • 標準出力 — stdout = 成功、stderr = 失敗。exit code を正しく使う
7 — バリデーションガイド

スキルの品質は LLM との協働でテストするのが最も効果的。以下の 4 フェーズで回帰を防ぐ。

flowchart TD
  A([スキル草稿完成]) --> B

  subgraph B["Phase 1: Discovery Validation"]
    B1["フロントマターを LLM に渡す"]
    B2["正トリガー 3 例・誤トリガー 3 例の生成"]
    B3["description の改善提案を受け取る"]
    B1 --> B2 --> B3
  end

  subgraph C["Phase 2: Logic Validation"]
    C1["SKILL.md 全文と DIR ツリーを LLM に渡す"]
    C2["エージェントとして実行をシミュレート"]
    C3["Execution Blocker（曖昧な指示）を特定"]
    C1 --> C2 --> C3
  end

  subgraph D["Phase 3: Edge Case Testing"]
    D1["QA テスター役に切り替え"]
    D2["失敗状態・未サポート設定を攻撃的に洗い出す"]
    D3["3〜5 問の質問リストを受け取り回答する"]
    D1 --> D2 --> D3
  end

  subgraph E["Phase 4: Architecture Refinement"]
    E1["回答を元に SKILL.md を書き直す"]
    E2["Progressive Disclosure を強制適用"]
    E3["Error Handling セクション追加"]
    E1 --> E2 --> E3
  end

  B --> C --> D --> E --> F([デプロイ可能])

  classDef phase fill:#f7f7f7,stroke:#e8e8e8,color:#1a1a1a
  classDef terminal fill:#d97b2f,stroke:#d97b2f,color:#fff
  class B,C,D,E phase
  class A,F terminal

Phase 1: Discovery Validation

YAML フロントマターだけを新規 LLM チャットに貼り、以下を確認:

  • このスキルを確実にトリガーすべきプロンプト 3 例
  • 似ているが トリガーすべきでないプロンプト 3 例
  • description が広すぎないか・最適化の提案

Phase 2: Logic Validation

SKILL.md 全文 + ディレクトリツリーを渡し、「自律エージェントとして実行をシミュレートせよ」と指示。各ステップで Execution Blocker（推測・幻覚が必要な箇所）を特定させる。

Act as an autonomous agent that has just triggered this skill.
Simulate step-by-step. For each step:
1. What exactly are you doing?
2. Which file/script are you reading or running?
3. Flag any Execution Blockers (lines where you must guess).

Phase 3: Edge Case Testing

「QA テスター」として役割を切り替え、スキルを「壊す」ことを目標にした 3〜5 問の質問を生成させる。修正はまだ行わず、質問に回答するだけ。

Switch roles. Act as a ruthless QA tester.
Ask 3-5 specific questions about edge cases or missing fallbacks.
Do NOT fix these issues yet. Just ask and wait for answers.

Phase 4: Architecture Refinement

回答を元に SKILL.md を書き直し、Progressive Disclosure を強制適用。大きなテンプレートや設定ファイルは references/ / assets/ に分離し、Error Handling セクションを追加。

8 — デプロイ前チェックリスト
カテゴリチェック項目
メタデータ name が 1–64 文字・小文字英数・単一ハイフンのみ
name と親ディレクトリ名が完全一致
description が 1,024 文字以内
"Use when…" と "Don't use for…" が明記されている
第三者的語調（I, me, my, you, your が未使用）
構成 scripts/, references/, assets/ 以外のフォルダが存在しない
フォルダが 1 段のみ（ネストなし）
README.md 等の人間向けドキュメントがない
すべてのパスが相対パス + 前向きスラッシュ
SKILL.md 500 行未満
命令形（Extract, Run, Validate 等）
番号付きで時系列に並んでいる
大きなスキーマ・テンプレートが references/ / assets/ に分離されている
ドメイン固有の用語が一貫して使われている
スクリプト 引数付きの CLI として設計されている
stdout / stderr で明確なフィードバックを返す
単一目的（複雑なロジックは標準 CLI へ）
エラー処理 Error Handling セクションが存在する
バリデーションスクリプトの実行ステップが含まれている
公式・関連