building-skills

スキルの構築

エージェントスキルとは、エージェントに必要に応じてタスクを教えるSKILL.mdファイルを含むフォルダーです。この形式は多くのエージェントでサポートされているオープン標準（仕様）です。特定の製品に依存せず、持ち運び可能なスキルを作成してください。

毎回の目標は、スキルを以前より小さく、明確で、役立つものにすることです。スキルは何千回も読まれますが、書かれるのは一度だけです。すべてのトークンに価値を持たせてください。

スキルの読み込み方法（段階的な開示）

┌──────────────┐ always loaded ┌───────────────────────────────────────┐
│ 1. metadata  │──────────────▶│ name + description (~100 tokens)      │
└──────────────┘               │ the only input used for triggering    │
                               └───────────────────────────────────────┘
┌──────────────┐   on trigger  ┌───────────────────────────────────────┐
│ 2. SKILL.md  │──────────────▶│ body instructions (aim < 500 lines)   │
└──────────────┘               └───────────────────────────────────────┘
┌──────────────┐   as needed   ┌───────────────────────────────────────┐
│ 3. resources │──────────────▶│ scripts/, references/, assets/        │
└──────────────┘               └───────────────────────────────────────┘

それぞれの情報は、機能する最も低コストなレベルに配置してください。起動の手がかりは説明に、主要なワークフローは本文に、必要なときだけエージェントが読む詳細な情報はリソースに記載します。

フロントマター

YAML フロントマターの後に Markdown を記述します。必須なのはnameとdescriptionだけです。

フィールド	必須	制約
name	はい	64 文字以下。小文字のa-z、数字の0-9、ハイフンを使用します。先頭や末尾のハイフン、連続するハイフンは使用できません。フォルダー名と一致させる必要があります
description	はい	1024 文字以下（できるだけ短くしてください）。何をするスキルか**、および**いつ使うかを記述します
license	いいえ	ライセンス名またはファイル参照（このリポジトリではMITを使用します）
compatibility	いいえ	500 文字以下。スキルに特定のツール、ランタイム、ネットワークが必要な場合にのみ指定します
metadata	いいえ	任意の文字列キーと値のマップ
allowed-tools	いいえ	事前承認済みツールをスペース区切りで列挙します（実験的）

ほとんどのスキルでは、name、description、license以外は必要ありません。憶測でフィールドを追加しないでください。

名前

スキルの内容に合わせて形式を選んでください。

• 特定のツール → ツール名を付けます：gh-cli、sourcegraph-cli、miro-mcp。起動条件が明確になる場合は、ツール名で名前空間を付けます（gh-address-comments）。
• 繰り返し行うタスク、ワークフロー、広範な操作 → 動名詞形（動詞 + -ing）を使います：building-skills、writing-issues-and-prs、managing-deployments。

どちらの場合も、短くハイフンでつなぎ、helper、utils、toolsのような曖昧な名前は避けてください。

説明 — 起動条件

エージェントがスキルを使うかどうかを判断する際に見るテキストはこれだけです。そのため、「いつ使うか」に関する情報はすべてここに記載し、本文には記載しないでください。スキルが何をするか、および起動すべき具体的な状況や表現を明記し、検索に適した具体的なキーワードを使います。機能の概要を動詞で始める場合は三人称単数形を使います。スキルを読み込む場合も含め、エージェントへの指示には命令形を使います。コロンなどの YAML 特殊文字を含む場合は、値を引用符で囲んでください。

• 良い例：GitHub CLI (gh) を使って、GitHub リポジトリ、イシュー、プルリクエスト、アクション、リリース、Gist、API 呼び出しを操作します。コマンドラインから GitHub の操作が必要なタスクで使用してください。
• 悪い例：コードを支援します。（曖昧で、起動条件がありません）

スキルが起動されにくい場合は、本文にルールを追加するのではなく、起動する状況を説明でより明確に示してください。

基本原則

• 簡潔さが重要です。 エージェントはすでに十分に賢いものと考えてください。エージェントが知らない情報、つまり自明ではない手順、分野固有の事実、プロジェクトの慣例だけを追加します。すべての行について、そのトークンを使う価値があるかを検討してください。導入、要約、一般常識の説明は削除します。
• 何をするかだけでなく、なぜそうするかを説明してください。 短い理由を添えると、能力の高いエージェントが想定外の事例にも対応できます。強引なALWAYS／NEVERルールは、その理由を説明する形に置き換えてください。厳格な制約は、手順が非常に壊れやすく、間違いが起こりやすい場合に限って設けます。
• 手順の壊れやすさに応じて自由度を調整してください。 妥当な進め方が多い自由度の高いタスクでは、概要レベルの説明を使います。推奨するパターンには、擬似コードやパラメーター化した例を使います。ミスのコストが高い、壊れやすい手順には、選択肢を絞った正確なスクリプトを使います。
• 過剰に特化せず、一般化してください。 スキルは目の前の例だけでなく、今後のさまざまなプロンプトで使えるものでなければなりません。特定のケースに合わせ込むのではなく、長く使えるパターンを優先してください。
• 命令形で書いてください。 説明的な語り口ではなく、エージェントに直接指示します（「X を実行する」「まず Y を読む」）。

構成

skill-name/
├── SKILL.md      # Required: frontmatter + instructions
├── scripts/      # Executable code for deterministic or repeated work
├── references/   # Docs the agent reads on demand (schemas, APIs, deep guides)
└── assets/       # Files used in output (templates, icons, fonts)

• scripts/ — エージェントが実行のたびに同じコードを書き直す場合や、手順に確定的な信頼性が必要な場合に使用します。意図が伝わるように参照します。「scripts/validate.py を実行して、フロントマターを確認してください。」スクリプトは実際に実行してテストします。
• references/ — SKILL.md を簡潔に保つため、詳細な資料をここに移します。SKILL.md から各ファイルを参照し、いつ読むべきかを記載します。参照の階層は一段までにします。
• assets/ — 出力にコピーする、または出力で使用するリソースを格納します。コンテキストには読み込みません。

README.md、CHANGELOG.md、インストールガイド、スキルの作成方法に関するメモは追加しないでください。スキルには、エージェントが作業を行うために必要なものだけを含めます。

ワークフロー

1. タスクを理解する。 具体例を集めます。何を実現すべきか、どのような表現がトリガーになるか、期待される出力は何かを確認します。完了した会話をスキルにする場合は、すでに行われた手順、ツール、修正を洗い出します。
2. リソースを計画する。 各例について、エージェントが繰り返し作業するのに役立つスクリプト、リファレンス、アセットは何かを検討します。執筆前に一覧を作成します。
3. SKILL.md のドラフトを作成する。 フロントマター（特に description）を適切に記述し、その後に本文を作成します。本文には、一行の要約、ワークフロー、具体例を含めます。リソースがある場合は、先に作成します。
4. 情報を分割する。 本文が約 500 行を超える場合、または複数のバリエーションや分野を扱う場合は、コアとなるワークフローと選択ロジックを SKILL.md に残し、それ以外を references/ に移します（バリエーションごとに 1 ファイル）。
5. 検証する。 フロントマターと命名規則を確認します。次にスキル全体を読み直し、用語、見出しのスタイル、書式に一貫性があること、セクション間や SKILL.md とリファレンス間で内容が重複していないことを確認します。各情報は必ず一か所だけに記載します。
6. 実際の使用を通じて改善する。 スキルを使い、エージェントが苦労したり、手順を無駄にしたりする箇所を確認して改善します。実行のたびに同じヘルパーを作り直している場合は、スクリプトとしてまとめます。新鮮な視点でドラフトを読み直し、不要な部分を削ります。

既存のスキルを編集する場合

まず全体を読み、name とフォルダーはそのまま保持します。内容を短く、わかりやすくします。不要な部分を削除し、硬直的なルールを根拠に基づく判断に置き換え、トリガーとなる内容を description に盛り込み、詳細をリファレンスに移します。周囲のハウススタイルに合わせます。改善に必要な最小限の変更を優先し、それ以外は変更しないでください。