create-agent-skill

エージェントスキルの作成

範囲

• 会話内で、計画のみを求める依頼に回答します。対象は計画、設計、批評、アウトライン、要件、スキル構成に関する議論です。複数の内容が混在する依頼では、まず計画を整理し、実装方針が明確になってからファイルを作成します。
• 名前が挙がったツール、スキル、フレームワーク、ワークフローは、計画の文脈として扱います。ファイルの作成に移るのは、ユーザーから明示的に依頼された場合のみです。ファイルへの書き込みの意図が曖昧で、編集すると意外に思われる可能性がある場合は、編集前に確認します。
• 既存のスキルファイルをレビューする場合は、このスキルのルールに照らして確認し、会話内で指摘事項を報告します。
• 既存のスキルの評価、整理、反復改善を依頼された場合は、references/evaluating-skills.md を読み込みます。

ワークフロー

1. 範囲を確認します。

   • 作成または更新する具体的な成果物を特定します。スキルディレクトリ、SKILL.md、参考資料、スクリプト、アセット、インベントリ文書などが対象です。
   • スキルが扱うタスク、ワークフロー、プロジェクトの規約、またはドメインを特定します。
   • ユーザーが繰り返し入力する指示をまとめたショートカットの場合は、手順 2〜5 と 7 を省略します。手順 3 に従って名前を付け、ユーザーが呼び出すための、1 行の説明を含むフロントマターを設定します。本文に指示を記載してから、手順 6 を適用します。
   • スキルを起動するきっかけとなるプロンプト、コンテキスト、ファイル、ワークフローと、対象に含めない関連依頼や紛らわしい依頼を記録します。

2. 資料を収集し、割り当てます。

   • 完了済みのタスク、ユーザーからの修正、プロジェクト文書、ランブック、スキーマ、レビューコメント、課題、パッチを根拠としてスキルを作成します。スキルに保持すべき参考資料を集めます。
   • 教訓を指示として記述する前に、リンタールール、型、ランタイムチェック、スクリプトで適用できないか確認します。バンドルしたスクリプトやフックなど、スキル自身の成果物で適用できる場合は、その仕組みを組み込み、説明文のルールは省略します。対象リポジトリでの対応が適切な場合は、スキルの範囲を超えて編集せず、推奨事項として提示します。
   • 判断や承認と機械的な手順を分けます。Scripts セクションに従って機械的な各手順をスクリプトまたは直接呼び出しに割り当て、補助となる参考資料、アセット、テンプレート、サンプルファイルを選びます。

3. スキル名と配置場所を決めます。

   • ディレクトリ名は name フィールドに合わせます。長さは 1〜64 文字で、小文字、数字、単一のハイフンのみを使用し、先頭と末尾は英字または数字にします。

4. SKILL.md を作成します。

   • name と description を少なくとも含む YAML フロントマターから始めます。
   • license、compatibility、metadata、allowed-tools などの任意のフィールドは、情報を伝える場合にのみ追加します。
   • エージェントが自ら呼び出す必要がある場合、または別のスキルが読み込む必要がある場合に限り、そのスキルをモデル呼び出し可能にします。説明は毎ターンのコンテキストに残るため、「Description pattern」セクションに従って記述します。それ以外の場合は、disable-model-invocation: true を設定し、トリガーの一覧を含まない、人向けの1行の説明を使います。また、Codex はフロントマターのフィールドを無視するため、agents/openai.yaml を追加して、policy.allow_implicit_invocation を引用符なしの false に設定します。スキル名を入力すれば、引き続き呼び出せます。
   • ユーザーが呼び出すスキルを覚えにくくなった場合は、ほかのスキルの名前と、それぞれを使うタイミングを示す、ユーザー呼び出しのルータースキルを1つ提案します。ルート対象のスキルを追加、改名、削除するたびに、ルーターを更新します。
   • 説明を本文に含めません。説明では示せない有効化や適用範囲のルールが必要な場合は、## Boundaries セクションに記載します。説明だけで明確な場合はこのセクションを省き、実行時のデフォルトはワークフローの手順に記載します。
   • 本文は手順、デフォルト、例、注意点、スクリプト、検証手順を中心にします。
   • 実行完了時に何が成果物として得られるかを定義します。作業が複数の結果に分かれ得る場合は、最終的な結果を列挙します。監査、レビュー、保守のスキルでは、報告を水増しせず、「変更に値するものはなかった」ことも完了結果として含めます。
   • 繰り返し登場する概念には、先頭に置くキーワードを使います。ユーザーのプロンプトや対象分野ですでに使われている簡潔な用語を選び、説明と本文で同じ語句を繰り返し使います。列挙の書き下しや言い換えは、その語句に集約します。
   • ワークフローの各手順には、自然に設定できる場合、確認可能な完了条件を設けます。「変更をレビューする」のような曖昧な表現より、「変更したすべてのファイルをレビューする」のように網羅的な表現を優先します。客観的な基準を設けられない判断手順については、無理に基準を設けず、最終検証で具体的な確認事項を示します。
   • 本文のすべての行は、スキルを実行するエージェント向けに記述します。作成の意図、依頼の経緯、スキルの構成に関する説明は省きます。
   • スキルの指示によって最新情報を更新できる場合を除き、時期に左右される事実は避けます。
   • ほかのスキルをインストールせずに動作するスキルを優先します。ワークフローで別のスキルが本当に必要な場合は、そのスキル名を記載し、該当する手順で読み込むよう指示します。内容を複製したり要約したりしません。

5. 段階的な情報開示を適用します。

   • 毎回の実行に必要な内容は SKILL.md に残します。一部の分岐でのみ必要な内容は補助ファイルに移し、その分岐で読み込むファイルを示すポインターを記載します。
   • ポインターは references/evaluating-skills.md のように通常のパスで記述します。セクション名は「the Scripts section」のように文章で示します。Markdown のリンク構文では、ラベルと URL の両方に同じ参照先が重複します。
   • 本文の空でない行がおよそ100行を超える場合は、インラインの内容をポインターの先に移すべきか検討します。これは上限でも目標でもありません。サイズより完全性と正確性を優先します。
   • 対象が狭く、指示だけで完結するスキルには補助ファイルは不要です。エージェントが誤りやすい判断を網羅する最短のワークフローに、間違いを防ぐ場合に限って注意点、例、検証を加えた、単一の SKILL.md を使います。
   • 詳細なドキュメントは references/ に、再利用可能なテンプレート、画像、サンプルファイル、静的データは assets/ に移します。scripts/ は Scripts セクションの規則に従います。補助リソースはスキルディレクトリからの相対パスで1階層に収めます。

6. 指示文を磨きます。

   • refine-it を読み込み、続けて shorten-it を読み込みます。作成または編集した指示ファイルすべての全文に、それぞれを適用します。
   • 推敲前のテキストと推敲後のテキストを比較し、トリガー、要件、権限、ワークフローの順序、その他の運用上の意味に関わる変更は元に戻します。どちらの工程でも改善されない箇所は、表現を変更せずそのまま残します。

7. 結果を確認します。

   • 対象範囲が不明確な場合や、スキルにドメイン固有の設定が含まれる場合は、ドラフトを提示します。想定されるユースケースをカバーしているか、不足している点や不明確な点は何か、詳細を増やすべき点や減らすべき点は何かを尋ねます。
   • SKILL.md と補足ファイル全体で用語の一貫性を保ちます。
   • 各機械的な手順を Scripts セクションと照合します。説明されている引数と出力が、同梱されたスクリプトの内容と一致していることを確認します。
   • モデル呼び出し型のスキルでは、現実的な肯定プロンプトと、わずかに条件が異なる否定プロンプトを使って、説明の妥当性を確認します。説明が広すぎたり狭すぎたりする場合は修正します。
   • トリガーテストや比較実行などの正式な評価が役立つ場合は、次のステップとしてユーザーに提案します。このワークフローの一環として、手動評価は実行しないでください。

説明のパターン

モデル呼び出し型のスキルでは、説明を1024文字未満にし、三人称で、次の構成にします。

description: [What the skill enables]. [Conditions that invoke it: specific user intents, keywords, contexts, or file types].

最初の文では、スキルの機能を述べ、ユーザーが実際に入力する語彙を先に示します。2文目では呼び出される条件を、分岐ごとに1つのトリガーで述べます。同じ分岐の同義語はまとめ、最初の文ですでに説明した詳細は省きます。モデルによる呼び出しを想定して記述します。ユーザーはスキル名を指定して任意のスキルを呼び出せます。トリガーに誤って該当してしまう、実際に紛らわしいケースがある場合に限り、除外条件を加えます。

推奨例：

description: Reviews accessibility issues in React interfaces and suggests concrete fixes. Use when the user asks for accessibility review, WCAG checks, keyboard navigation fixes, or ARIA guidance for React components.

曖昧な表現を避け、1つの分岐に同義語を詰め込みすぎないでください。

description: Helps with accessibility.

description: ... Use when the user asks to review, check, audit, inspect, examine, or assess accessibility.

スクリプト

• 複数回のツール呼び出しを1回にまとめられる場合、順序や正確なフラグの指定、エージェントが誤りやすいクリーンアップを処理できる場合、次の判断に必要な情報だけに冗長な出力を絞れる場合、またはスキルで文章として述べるだけでは徹底しにくいルールを適用できる場合は、機械的な手順をスクリプト化します。
• スクリプトを使っても利点がない場合は、手順を直接実行します。たとえば、既存のツールの呼び出しを含め、スキルの記述を使ってエージェントが1行のシェルコマンドで正しく実行できる場合や、ワークフローのバリエーションに対応するためのフラグの指定が、置き換える直接呼び出しより煩雑になる場合です。
• 判断と承認はエージェントに委ねます。スクリプトでは、次の判断に影響する失敗を明らかにする必要があります。
• スクリプトをまとめる場合は、自己完結型で、対話操作が不要かつ冪等にし、相対パスを使ってスキルのルートから実行できるようにします。
• スクリプトには簡潔な --help、役立つエラーメッセージ、意味のある終了コード、安全なデフォルト値を用意し、次の判断に必要な情報だけを構造化して標準出力に出します。完全なログはファイルに書き込み、そのパスを表示します。完全なログを標準エラー出力に出さないでください。標準エラー出力もコンテキストを消費します。
• 破壊的操作や状態を変更する操作には、ドライラン用のフラグか、明示的な確認用フラグを含めます。
• 同梱スクリプトを呼び出す各箇所では、エージェントが別途ヘルプを参照しなくても実行できるよう、必要な引数と任意の引数、デフォルト値、出力、終了時の動作を説明します。これらの説明はスクリプトと一致させ、実装の詳細はコード内に記述します。
• 納品前に、同梱スクリプトと正確なコマンドを、最初から最後まで一度実行します。破壊的操作や状態を変更する操作は、ドライラン、ヘルプ、確認の各経路を使うか、破棄可能なテスト用データに対して検証します。実際の対象には実行しないでください。

スターターの形式

---
name: skill-name
description: Does a specific reusable task. Use when the user asks for concrete intents, contexts, or file types that should trigger this skill.
---

# Skill name

## Workflow

1. Follow the domain-specific procedure.
2. Use the default tool or format; mention alternatives only as escape hatches.
3. Validate output and fix failures before finalizing.

## Gotchas

- State the correct behavior for a case the agent gets wrong by default; name the mistake itself only when the correct form alone won't prevent it.

品質基準

• スキルは、一般的な知識を詰め込んだものではなく、再利用可能な作業をまとめた一貫性のある単位です。
• エージェントがスキルなしでは誤りやすい点を、指示でカバーします。
• ワークフローでは、独立した操作を1回のツール実行にまとめます。判断やユーザーの承認が必要な段階ではまとめるのを止め、失敗は見える状態に保ちます。
• 環境から得られる事実は、それを管理する環境に置きます。環境からは得られない、明文化されていない慣習、理由、注意点を記載します。
• すべての指示は、何らかの状況で動作を変えるものにします。「ツールを確認する」「判断力を働かせる」「丁寧に作業する」のように、エージェントが異なる行動を取れない文や、環境がすでに保証していることを言い換えるだけの曖昧な表現は削除します。
• エージェントが自分で行う手順ではなく、実行するアクションを明示します。「references/x.md を適用する」とし、「references/x.md を読んで適用する」とはしません。エージェントが手順を省略したり、順序を誤ったりするおそれがある場合に限り、サブステップを明記します。
• 各ルールは、適用される箇所で一度だけ記載します。ワークフローですでに述べたルールを別の箇所で繰り返すことや、そのルールを否定するだけの注意点は削除します。
• 概念の定義、ルール、注意点は、1つの見出しの下にまとめます。
• デフォルトを明確にします。代替案は、判断を変える場合に限り記載します。
• 禁止事項には、代わりに何をすべきかを必ず示します。
• 手順を細かく規定するのは、間違えやすい操作に限ります。柔軟に対応できるタスクでは、目的を説明します。
• 例を含める場合は、具体的で現実的なものにし、よくある間違いを検出できるように検証します。