agent-skills

Agent Skills 標準リファレンス

このスキルでは、AI エージェントに新しい機能と専門知識を付与する標準化されたオープン形式である Agent Skills について説明します。このリポジトリでスキルを作成または編集する際は、このワークフローに従ってください。

公式の情報源：agentskills.io/specification。同梱の仕様は作業用スナップショットです。最新性が重要な場合は、公式の情報源を確認してください。

---

ディレクトリ構造

スキルは、少なくとも SKILL.md ファイルを含むディレクトリです。

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── evals/            # Required for new skills in this repository
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

必須のワークフロー

スキルを作成または編集する

1. SKILL.md のメタデータやディレクトリ構造を変更する前に、仕様を読みます。
2. 指示は、実際のドメイン知識、プロジェクトの成果物、確認された失敗パターンに基づいて作成します。指示の設計や大幅な改訂を行う場合は、ベストプラクティスを読みます。
3. スキルは一貫性があり、トリガー可能な単位に保ちます。SKILL.md には必須の指示だけを記載し、条件付きの詳細は用途を絞ったリファレンスファイルに記載して、それぞれをいつ読むべきか明記します。
4. スキルの役割、適用される状況、適用されない状況を示す、正確な description を使用します。重要な重複があるスキルでは、## When not to use セクションで最も近い代替手段または前提条件を挙げます。トリガーの境界は、少なくとも3つの起動すべきプロンプトと、2つの起動すべきでない類似プロンプトでテストします。こうしたハーネス固有のトリガーチェックは、移植可能な出力品質評価とは分けてください。トリガー設計については、description の最適化を読みます。
5. 新しいスキルごとに、代表的な出力品質のケースを少なくとも5件含む evals/evals.json を作成します。各ケースには、現実的なプロンプト、期待される結果、観察可能なアサーションが必要です。リスクの高い動作や曖昧な動作を検証するエッジケースも含めます。評価形式と反復ワークフローについては、スキルの評価を読みます。
6. 実行可能なコードを同梱する場合は、スクリプトの使用を読みます。前提条件と、非対話形式での実行方法をスキル内に記載します。
7. 引き渡す前に、このスキルの検証チェックを実行し、すべての指摘事項を修正します。

スキルをレビューする

1. 仕様に照らして、必須のフロントマター、フィールドの制約、親ディレクトリと名前の一致、YAML 構文を検証します。
2. description に肯定的および否定的なトリガーの境界が示されていること、ワークフローが実行可能であること、リソースへの参照が条件付きで到達可能であることを確認します。
3. スクリプトがある場合は、依存関係、安全な非対話型入力、明確なエラー、有用な場合は構造化された出力が文書化されていることを確認します。
4. このリポジトリでは、ユーザー向けの必須の README.md も確認します。タイトル、Why Install This Skill、What You Get、（本当にリファレンス専用でない限り）Quick Start、Triggers、Requirements が必要です。ユーザー向けの内容を簡潔に保ち、エージェント専用の指示は含めないでください。
5. 新しいスキルすべてに、出力品質のケースを少なくとも5件含む evals/evals.json があることを確認し、期待される結果とアサーションが意味のある動作を検証しているか確認します。評価ファイルのない既存のスキルについては、不備として指摘しますが、そのレガシーな不足だけを理由にレビューを妨げないでください。作業の完了を宣言する前に、スキルの評価を読みます。

クライアントの実装作業

エージェント製品でスキルの検出、有効化、またはコンテキスト管理を実装する場合は、クライアント実装ガイダンスを読みます。検索パスなどのクライアント規約を、形式全般に適用される要件として扱わないでください。

SKILL.md 形式

SKILL.md ファイルには、YAML フロントマターと、それに続く Markdown 本文が必要です。

フロントマターのフィールド

フィールド	必須	制約
name	はい	最大64文字。小文字、数字、ハイフンのみ使用できます。ハイフンで始めたり終わったりしてはいけません。親ディレクトリ名と一致する必要があります。
description	はい	最大1024文字。空欄不可。スキルの機能と使用するタイミングを説明します。
license	いいえ	ライセンス名、または同梱のライセンスファイルへの参照。
compatibility	いいえ	最大500文字。環境要件を示します。
metadata	いいえ	任意のキーと値のマッピング。
allowed-tools	いいえ	事前承認済みツールをスペース区切りで指定した文字列。（実験的）

name フィールドのルール

• 1～64文字
• 小文字の Unicode 英数字（a-z、0-9）とハイフン（-）のみ使用できます
• ハイフンで始まったり終わったりしてはいけません
• 連続するハイフン（--）を含めてはいけません
• 親ディレクトリ名と一致する必要があります

description フィールドのルール

• 1～1024文字
• スキルの機能と使用するタイミングの両方を説明する必要があります
• エージェントが関連するタスクを特定しやすくなる具体的なキーワードを含めてください

compatibility フィールドのルール

• 指定する場合は、1～500文字である必要があります
• 必須の製品、システムパッケージ、ネットワークアクセス、ランタイムなど、具体的な環境要件がある場合にのみ記載してください

metadata フィールドのルール

• 文字列のキーと文字列の値のマップである必要があります
• 他のクライアントやツールとの衝突を避けるため、十分に固有なキーを使用してください

本文の内容

Markdown の本文には、エージェントに役立つ内容であれば、形式上の制約はありません。推奨されるセクションは次のとおりです。

• 手順ごとの指示 — エージェントが従うべき手順
• 入力と出力の例 — 入力時と出力時のデータの形式
• 一般的なエッジケース — ガイダンスがないとエージェントが正しく処理できない可能性のある状況
• 注意点 — 妥当な想定に反する、環境固有の事実

SKILL.md は500行、5000トークン未満にしてください。詳細なリファレンス資料は references/ 内の別ファイルに移してください。

段階的な開示

エージェントはスキルを3段階で読み込みます。

1. メタデータ（約100トークン）：すべてのスキルについて、name と description を起動時に読み込みます
2. 指示（5000トークン未満を推奨）：スキルが有効化されたときに、SKILL.md 全体を読み込みます
3. リソース（必要に応じて）：scripts/、references/、assets/ 内のファイルを必要に応じて読み込みます

補助ディレクトリ

scripts/

エージェントが実行できるコードです。スクリプトは次の要件を満たす必要があります。

• 自己完結型にするか、依存関係を明確に記載する
• 役立つエラーメッセージを含める
• エッジケースを適切に処理する
• スキルのルートからの相対パス（例：scripts/extract.py）を使用する
• 意図を明確にする。「このスクリプトを実行する」または「これをリファレンスとして読む」と明記し、同梱ファイルが実行可能なのか例示用なのかをエージェントに推測させない

references/

必要に応じて読み込む追加ドキュメントです。個々のファイルの内容は絞り込んでください。エージェントは指示に従ってこれらを読み込むため、ファイルが小さいほどコンテキストを節約できます。

• references/ 内のすべてのファイルは、60,000文字以下にしてください。リファレンスが上限を超えた場合は、内容を絞ったファイル（例：references/<topic>-a.md、references/<topic>-b.md）に分割し、SKILL.md を更新して、新しい各ファイルを参照できるようにするとともに、必要に応じた読み込みの指示で適切なファイル名を指定してください。

assets/

テンプレート、画像、データファイル、スキーマなどの静的リソースです。

evals/

スキルの出力品質を評価するための、移植可能なケースです。このリポジトリの新しいスキルには、少なくとも5つのケースを含む evals/evals.json が必要です。トリガーのみのチェックはこのファイルではなく、ハーネス固有のテストセットに含めてください。

ファイル参照

他のファイルを参照する場合は、スキルのルートからの相対パスを使用してください。

See [the specification](references/specification.md) for details.

Run a bundled script:
scripts/<script-name>

ファイル参照は SKILL.md から1階層以内にしてください。深くネストした参照チェーンは避けてください。

効果的な説明を書く

description フィールドは、スキルを自動選択するための主要な仕組みです。クライアントが明示的な有効化に対応している場合もあります。次の原則に従ってください。

• 命令形で書きます。「このスキルは〜します」ではなく、「〜する場合はこのスキルを使います」とします。
• 実装ではなく、ユーザーの意図に焦点を当てます。 ユーザーが何を達成しようとしているかを説明します。
• 適用範囲は積極的に示します。 スキルが適用される状況を明示的に列挙します。
• 簡潔にまとめます。 数文から短い段落程度が適切です。

ベストプラクティス

実際の専門知識から始める

スキルの作成には、ドメイン固有のコンテキストを取り入れます。実際のプロジェクト成果物（運用手順書、API 仕様、コードレビューのコメント、実際の障害事例など）に基づくスキルは、一般的な知識から合成したスキルよりも優れています。

コンテキストを有効に使う

エージェントがスキルなしでは把握できない情報に焦点を当てます。プロジェクト固有の規約、ドメイン固有の手順、見落としやすいエッジケースなどです。エージェントがすでに知っている一般的な概念は説明しないでください。

制御の度合いを調整する

• 複数の方法が有効な場合は、自由度を持たせます。何をするかだけでなく、なぜそうするのかを説明します。
• 操作に脆弱性がある場合や、特定の手順を順守する必要がある場合は、具体的に指示します。
• 脆弱性に応じて指示の具体性を調整します。毎回正確に実行しなければならない手順には、エージェントがその都度工夫する指示よりも、scripts/ にある決定論的なスクリプトを優先します。テストで検出できるのは、事前に確認対象として考えたものだけです。スクリプトを使えば、判断の余地を完全になくせます。
• 選択肢の一覧ではなく、デフォルトの方法を提示します。代替手段は簡潔に触れるにとどめます。
• 宣言よりも手順を重視します。特定の一例で何を作るかではなく、ある種の問題にどう取り組むかを教えます。

一貫性のある単位を設計する

スキルの範囲は関数のように設定し、ほかのスキルと組み合わせやすい、一貫性のある作業単位にします。範囲が狭すぎると、1 つのタスクに複数のスキルが必要になります。広すぎると、適切なタイミングで有効化するのが難しくなります。

注意点のセクションを設ける

最も価値の高い内容は、多くの場合、環境固有の修正事項です。つまり、伝えなければエージェントが間違えることです。エージェントが間違いを犯したら、その修正内容を注意点のセクションに追加します。

出力テンプレートを用意する

出力に特定の形式が必要な場合は、テンプレートを本文中または assets/ に用意します。エージェントは具体的な構造を手本にするのが得意です。

サードパーティ製スキルの導入

スキルは実行可能な機能です。スキルが有効になると、エージェントの権限で指示やスクリプトが実行されます。これにはシェルアクセス、ファイルシステム、認証情報へのアクセスが含まれます。自分で作成していないスキル（レジストリ、同僚、LLM による生成など）を実行する前に、サードパーティ製スキルの審査を読み、ほかの依存関係と同じように扱ってください。提供元を調べ、本文とすべてのスクリプトを読み、スキルが外部にアクセスする対象を確認します。

検証

skills-ref リファレンスライブラリを使ってスキルを検証します。

skills-ref validate ./my-skill

これにより、SKILL.md のフロントマターが有効で、すべての命名規則に従っているかを確認できます。

このリポジトリでは、同梱されているリポジトリ全体のチェッカーも実行します。

ruby scripts/validate-skills.rb

このチェッカーは、正規のトップレベルスキルとバンドルスキルについて、フロントマター、サポート対象フィールド、行数制限、ローカルリンク、必須の README セクションを確認します。agent-council/profiles/skills/ 以下のベンダー提供プロファイルスキルは、元のリポジトリの規約に従っているため、意図的に対象から除外されています。

skills-ref が利用できない場合、バリデーターの実行に成功したと主張しないでください。同等の構造チェックを手動で行って結果を報告するか、タスクで許可されている場合はリファレンスバリデーターをインストールして実行してください。