effective-agent-skills

効果的なエージェントスキル

---

1. エージェントスキルとは

エージェントスキルは、SKILL.md ファイル（YAML フロントマター＋Markdown の指示）と、エージェントが必要に応じて読み込むスクリプト、リファレンス、アセット用の任意のサブフォルダーを含むフォルダーです。

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

Agent Skills（agentskills.io）はオープンスタンダードです。フォルダーと SKILL.md の形式は移植可能ですが、呼び出し制御などの任意の動作はクライアント固有の場合があります。

---

2. スキルを使う理由

スキルは、再利用できるよう手順に関する知識とコンテキストをまとめます。

• コンテキスト効率 — 関連する場合にのみ指示を読み込みます
• 再現性 — 複数ステップの手順が監査可能なワークフローになります
• 組み合わせやすさ — タスクに応じて、複数のスキルを実行時に組み合わせられます
• 移植性 — 同じファイルをさまざまなベンダーや環境で使用できます

---

3. 仕組み — 段階的な開示

読み込みには3つのレベルがあります。

レベル1 — 検出（スキルあたり約100トークン、常にコンテキスト内）： エージェントはまず name と description を確認し、そのスキルが該当するかどうかを判断します。

レベル2 — 有効化（一致時に読み込み、5,000トークン未満）： リクエストが一致すると、エージェントは SKILL.md の本文全体を読み込みます。

レベル3 — 実行（上限なし、必要に応じて）： エージェントは必要に応じてリファレンス（references/foo.md）を読み込むか、スクリプト（scripts/validate.py）を実行します。スクリプトを実行しても、そのソースをコンテキストに読み込む必要はありません。

同梱ファイルは、その内容が読み込まれた場合にのみコンテキストを消費します。

---

4. SKILL.md の構成

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

# Skill Name

## Quick start
[Minimal working example]

## Workflow
[Step-by-step procedure with checklists]

## Output format
[What the user/agent should expect back]

## Advanced
[Link to references/ for rarely-needed detail]

フロントマターの制約：

• name は小文字とハイフンのみで構成し、1〜64文字にします。親フォルダー名と完全に一致させる必要があります
• フロントマターでは < と > を避けてください（システムプロンプトへのインジェクションにつながる可能性があります）
• 無効な YAML はエラーなしで読み込みを妨げます
• 引用符で囲まれていない description の中に : （コロン＋スペース）を絶対に入れないでください — 厳格な YAML パーサー（Pi など）は、寛容なパーサー（Claude Code など）では受け入れられる場合でも、これをネストしたマッピングとして拒否します（「Nested mappings are not allowed in compact mappings」）。文中にコロンが必要な場合は、値全体をシングルクォートで囲み、内部のアポストロフィを2つ重ねてください：description: 'Differentiator: finds gaps in the user''s knowledge.'

手動呼び出し専用の設定はクライアント固有です

disable-model-invocation: true は、Agent Skills の中核仕様には含まれていません。Claude Code と VS Code/Copilot がサポートするクライアント拡張です。これらのクライアントでは、明示的な呼び出しを可能にしたまま自動呼び出しを防ぐため、SKILL.md のフロントマターに記述します。

OpenAI Codex では、スキル内の agents/openai.yaml という別ファイルを使用します。

policy:
  allow_implicit_invocation: false

Claude Code、VS Code/Copilot、Codex で共有する手動呼び出し専用スキルには、両方の設定を含めてください。クライアント固有のフロントマターフィールドが、あらゆる Agent Skills 実装で機能すると想定しないでください。対象となる各クライアントのドキュメントを確認し、それぞれの実行環境で暗黙の呼び出しをテストしてください。

---

5. 2つの設計思想

パターンA — 機能のプリミティブ（ツールラッパー）

スキルは、決定論的な CLI またはスクリプトを薄くラップします。ロジックはコードにあり、SKILL.md ではエージェントに呼び出し方を教えます。

• 追加するもの：新しい機能（検索、メール、ブラウザー、API アクセス）
• 信頼性の源：プロンプトではなく、シェルツール
• 一般的な長さ：30〜80行。大部分はコマンドの例
• 使用する状況：「エージェントがXを実行できない」ことがボトルネックの場合

パターンB — プロセスのプリミティブ（認知の規律）

スキルは、エージェントが従うべき手法を定めます。純粋なプロンプトエンジニアリングであり、スクリプトは不要です。

• 追加するもの：構造化されたワークフロー（TDD、コードレビュー、設計の整合、デバッグの反復）
• 信頼性の源：明確な手順、チェックリスト、検証の反復
• 使用する状況：「エージェントの出力品質やプロセスに問題がある」ことがボトルネックの場合

---

6. 効果的なスキルの書き方 — こうしましょう

スキル選択用の説明を書く

エージェントは本文を読み込む前に、名前と説明を確認します。スキルの機能と、そのスキルを使うべき具体的なタスクを説明してください。

• 1、2文の短い文を目指してください。1,024文字は上限であり、目標ではありません。
• 主なユースケースと重要な用語を最初に置いてください。ホストによって説明が短縮される場合があります。
• ユーザーが実際に使うタスク名、入力、ファイル形式を挙げてください。キーワードだけでなく、意図に合致させてください。
• 関連するスキルとの混同を防げる場合に限り、適用範囲の境界を示してください。
• ワークフローの手順は本文に記載してください。曖昧な主張、何にでも当てはまる表現、同義語の羅列は避けてください。

パターン："[機能]。［具体的なタスクや状況］で使用します。"

情報源：Agent Skills · OpenAI.

SKILL.md は簡潔に保つ

• 一定の長さを超えると、通常はスクリプトや参照ファイルに記載すべきロジックを埋め込んでいることになります

文章より Bash を優先する

長い文章よりも、インラインコメント付きの具体的なコマンド例を優先してください。

決定性をコードに持たせる

壊れやすい、繰り返しが多い、または変化がバグにつながるものはスクリプトにしてください。判断が必要なタスクにのみ Markdown を使用してください。

タスクの壊れやすさに合わせて厳密さを調整する（自由度）

誤った操作のコストに応じて、指示の厳密さを調整してください。

• 有効な方法が多数ある場合（例：コードレビュー）は、柔軟な自然言語のヒューリスティックを使います。
• 推奨パターンはあるものの、多少の変化が許容される場合（例：レポート形式）は、擬似コードやテンプレートを使います。
• ワークフローが壊れやすい、エラーが起きやすい、または一貫性が重要な場合（例：マイグレーション、ドキュメントのパッチ適用）は、正確なスクリプトと厳密な手順リストを使います。

検証ループを構築する

検証 → 修正 → 再検証のループを明示してください。

• ドキュメント作成スキル：納品前に目視で品質を確認
• コードスキル：完了前にテストが成功し、型エラーがゼロであることを確認
• データスキル：出力前にスキーマを検証

操作前に状態を確認する

セットアップが済んでいると決めつけないでください。エージェントに状態を確認させてから、状況に応じて処理を分岐させます。

First check if X is configured: [command]
If not, walk the user through setup: [steps]

必要なときに読み込めるよう、参照先を明示する

参照ファイルをいつ読むべきか、エージェントに具体的に指示してください。

For standard cases, follow the steps below.
For [specific edge case], read references/edge-cases.md first.

参照は1階層に留める

参照先は SKILL.md から直接リンクしてください。参照先がさらに別の参照先を指す構造では、一部しか読まれず指示が見落とされるおそれがあります。100行を超える参照ファイルには目次を追加してください。

出力形式を記載する

他のツールが確実に解析できるよう、構造化された出力例を示してください。

詳細は --help を参照する

SKILL.md には一般的な操作を示し、それ以外は tool --help を使うよう案内してください。

ワークフローを一括化せず、プリミティブを組み合わせる

各スキルは1つの機能または専門分野に絞り、大きなワークフローには目的を絞ったスキルを組み合わせてください。

該当する場合は、確立された原則を引用する

TDD、DDD、red-green-refactor などの確立された手法を使う場合は、その出典を明記してください。エージェントとユーザーが意図した手法を確認できます。

セッションをまたいで記憶を保つための永続的な成果物

スキルでは、後続のセッションで使える永続的なコンテキストをリポジトリ内のファイル（CONTEXT.md、ADR、意思決定ログ）に保存できます。

---

7. 避けるべきこと — アンチパターン

モデルがすでに知っていることを教え直さない

モデルが持っていないコンテキストを提供してください。Python や Git の基本的なチュートリアルは省き、すべての段落に価値を持たせてください。

人間向けのドキュメントを含めない

スキルフォルダーには README.md、CHANGELOG.md、INSTALLATION_GUIDE.md を含めないでください。スキルはエージェント向けです。

曖昧な説明を書かない

• 悪い例：「ドキュメントに役立つスキル」
• 良い例：「PDF のフォームフィールドへの入力、フォームデータの抽出、入力済み PDF のフラット化を行います。ユーザーが PDF フォーム、入力可能なフォーム、またはプログラムによるフィールドへの入力に言及した場合に使用します。」

ライブラリのコードを含めない

解析ライブラリが必要な場合は、npm または pip でインストールしてください。ソースコードをスキルに貼り付けないでください。

巨大で一枚岩のスキルを書かない

設計、計画、実装、テスト、デプロイをまとめているスキルは分割してください。

エージェントが推論すると想定しないでください

重要なすべてのステップについて明示してください。

• 悪い例:「その後、デプロイして。」
• 良い例:「npm run deploy:staging を実行し、成功を報告する前に /healthz から HTTP 200 が返るのを待ってください。」

スタイルだけを変えるバリアントを書かないでください

トーンやフォーマットを変えるだけのスキルは、スキルではなくユーザー設定やシステムプロンプトに属します。

失敗モードを無視しないでください

失敗する可能性のある各ステップについて、失敗をどのように認識し、何をすべきかを記述してください。

時間に敏感な情報を含めないでください

「2024年第4四半期時点では…」はすぐに陳腐化します。スクリプトでライブデータを取得するか、省略してください。

絶対パスを使わないでください

常に相対パスにします。OS に関係なくフォワードスラッシュを使用します。スキルディレクトリを参照するには実行時のプレースホルダーを使用します。

不慣れなスキルを信用しないでください

スキルはコードを実行し、動作を誘導し、データを漏洩させる可能性があります。使用前にスクリプト、参照、名前、アクセススコープを監査してください。以下のセキュリティチェックリストに従ってください。

---

8. 作成ワークフロー

1. ギャップを特定します。 実際のタスクでエージェントを実行します。どこで一貫して失敗するか、または再プロンプトが必要になるでしょうか？それがスキルの候補です。
2. パターンを決定します。 能力プリミティブ（新しいツールが必要）か、プロセスプリミティブ（より良い方法論が必要）のどちらでしょうか？
3. 最初に説明を起草します。 何を + いつ。混乱を招きそうな場合にのみ境界を追加します。
4. 機能する最小の本文を書きます。 テストでギャップが明らかになった場合にのみ追加します。
5. SKILL.md が長くなりすぎたら、詳細を references/ に移動します。
6. トリガーをテストします。 スキル名を出さずに、現実的なリクエストとニアミスを使用します。その本文が実際にロードされることを確認します。
7. 実行をテストします。 明示的に呼び出します。出力が間違っている場合は、本文を修正します。
8. 敵対的テスト。 別の LLM に「このスキルを壊すエッジケースは何ですか？」と尋ねます。ギャップにパッチを当てます。
9. バージョン管理。 スキルをコードとして扱います。タグ、ブランチ、レビュー。

---

9. テストとデバッグ

• 実際のアクティベーションを確認します。 ランタイムが SKILL.md をロードしたかどうかを検査します。有効な YAML やエージェントの自己報告は証拠にはなりません。
• 誤ったアクティベーションまたは見逃されたアクティベーション。 検出と呼び出しの設定を確認し、その後、説明のスコープとトリガーの文言を調整します。
• 実行が失敗 → 本文の問題。 明示的なステップ、例、または検証を追加します。
• トリガーテストには新しいセッションを使用します。 一部のクライアントは起動時にスキルをスナップショットします。
• デプロイする最も弱いモデルに対してテストします。 強いモデルは曖昧なスキルを許容しますが、弱いモデルはそれを露呈させます。
• 両方向をテストします。 現実的なリクエストと、キーワードを共有するがスキルをアクティベートすべきでないニアミスを含めます。曖昧なケースを繰り返し、新しいプロンプトをテストして過剰適合を避けます。

---

10. コンポジション

エージェントは1つのタスクのためにスキルを組み合わせることができます:

• 1つのスキル = 1つの関心事。 バンドルすることに抵抗します。
• スキル間のインターフェースを定義します。 スキル A がスキル B の消費するアーティファクトを生成する場合、その形状を文書化します。
• リポジトリレベルのコンテキストを共有します。 AGENTS.md、CONTEXT.md、settings.json などのファイルは、明示的なハンドオフなしで複数のスキルを調整できます。
• スキルを有用なワークフローに接続します。例えば、align → spec → build → verify → refactor などです。

---

11. セキュリティチェックリスト

サードパーティのスキルをインストールする前に:

• フォルダ内のすべてのファイルを読みます
• scripts/ を監査します: 外向きのネットワーク呼び出し、予想されるスコープ外のファイルアクセス、コマンド実行
• プロンプトインジェクション（「以前の指示を無視して…」）がないか参照を確認します
• スキル名が人気のあるもののタイポスクワッティングでないことを確認します
• 最初にサンドボックス環境で実行します
• latest ではなく特定のバージョン/コミットにピン留めします

---

12. 公開チェックリスト

スキルを公開する前に、次の項目を確認してください。

• フロントマターの name がフォルダー名と一致している
• 説明は簡潔で、機能と具体的なトリガーを最初に示している
• 必要に応じて、関連するスキルとの境界が明確になっている
• スキルフォルダー内に人間向けのドキュメントがない
• 時間の経過とともに古くなる情報がない
• 相対パスのみを使用している
• 該当する場合は、アクションの前に状態を確認する
• 検証ループが記載されている
• 該当する場合は、出力形式が記載されている
• 性能の低いモデルと高いモデルの両方でテストしている
• 正しいトリガーと正しい実行の両方をテストしている
• スキルが単一のことを実行する
• 関連するスキルとスムーズに連携する
• バージョン管理されている