write-skills

スキルの作成

スキルはドキュメントではありません。コードを書き、推論する方法をすでに知っているエージェントのための、圧縮された実行メモリです。その役割は予測可能性です。同じ出力を生成することではなく、実行のたびに同じプロセスを踏むことです。エージェントの行動を変えるコンテキストだけを記述してください。

基本原則

1. 説明から起動します。 スキルが読み込まれる前に読まれるのは、フロントマターの description だけです。スキルが何をするのか、どのような具体的な状況で起動すべきかを記述してください。起動条件を本文に隠さないでください。

2. トークンは貴重なものとして使います。 エージェントは一般的な推論がすでに得意だと想定してください。方向性を示し、実装の詳細は賢いモデルに考えさせます。ラッパースキルなら、2文で十分です。使う機能と従うべきスキルを示してください。実際に確認された失敗がある場合にのみ、仕組みを追加してください。

3. エッセイではなく手順を書きます。 命令形のルール、判断ポイント、小さな例を優先してください。良いスキルは次のターンでの行動を変えます。単にトピックを説明するだけではありません。また、成果物の形に合わせて手順を組み立ててください。「合うものを選ぶ」方式のテクニック集では、フローではなくツール選びが行われます。面接や段階を踏む散策のように、タスクが特定の形をしたやり取りなら、ワークフロー自体もその形にし、テクニックはその中の手順として扱ってください。

4. 段階的に情報を開示します。 メインのスキルファイルは短く保ってください。長いスキーマ、例、プロバイダーのドキュメント、特定のバリエーションに関するガイダンスは、必要な場合にだけ参照するポインターを介して、リンク先の references/ ファイルに移してください。繰り返し使う、壊れやすい操作は scripts/ に置きます。再利用できる出力素材は assets/ に置きます。

5. 実際に使って検証します。 新しいエージェントが現実的なタスクに正しく適用できるスキルが良いスキルです。何も知らない状態で実行し、実行対象となる中で最も弱いモデルでも試してください。作成した最先端モデルでしか正しい行動を促せないスキルは、リリースするには脆弱すぎます。編集後は、会話履歴が何もない状態で読むようにして、行動に影響しない要素を取り除いてください。

6. 例では解決策ではなく、問題を示します。 エージェントが繰り返し起きる問題を認識する方法――兆候、症状、何を根拠に誤りと判断したか――を教える例には、トークンを使う価値があります。それは長く役立つ知識です。たまたま適用した修正はそうではありません。コードは変わり、埋め込まれた解決策は古くなり、さらに悪いことに、次回には合わない手法を指示するおそれがあります。失敗のパターンとその兆候を書き、エージェントには現在のコードに合わせて修正方法を新たに導き出させてください。「重心までの距離で判定される方向質問が、どの方角から見ても誤って読めた」は参考になります。「だから FRONT_ARC をキーにした」は古びていきます。迷ったら、何が壊れていて、どう気づいたかを書き、そこで止めてください。

導きの言葉

導きの言葉とは、モデルの事前学習にすでに含まれ、スキルの実行中にエージェントが思考のよりどころにする、簡潔な概念です（例：fog of war、tracer bullets、red、tight）。一つの言葉で、モデルがすでに持つ事前知識を呼び起こし、最小限のトークンで行動のまとまり全体を方向づけられます。

• 本文では実行を方向づけます（同じ言葉 → 毎回同じ行動）。説明では呼び出しを方向づけます（その言葉がユーザーのプロンプト、ドキュメント、コードにもあれば、スキルがより確実に起動します）。
• 導きの言葉で不要になる言い換えを探してください。「高速、決定論的、低オーバーヘッド」→ tight なループ。「信頼できるループ」→ ループが red になる。二つの利点があります。トークンが減り、引き金がより明確になります。
• 弱い導きの言葉は何も変えません（エージェントがすでにそうしているときの be thorough など）。必要なのは文を増やすことではなく、より強い言葉（relentless など）に変えることです。

呼び出し方法

スキルへの呼び出し方法を選びます。選択肢ごとに、発生するコストが異なります。

• モデルによる呼び出し（デフォルト）：エージェントが自律的にスキルを起動でき、ほかのスキルからも呼び出せるように、description を残します。コンテキストの読み込みが必要です。説明は毎ターン、コンテキストウィンドウに表示されます。トリガーとなる表現を豊富に記述してください。
• ユーザーによる呼び出し：disable-model-invocation: true を設定します。ユーザーがスキル名を入力した場合にのみ呼び出されます。コンテキストの読み込みは不要ですが、ユーザーがスキルの存在を覚えている必要があります。description はユーザー向けの一行説明になります。

エージェントまたは別のスキルが、明示的な指示なしにスキルを呼び出す必要がある場合にのみ、モデルによる呼び出しを選んでください。ユーザーによる呼び出しのスキルが増えすぎてメモリを圧迫する場合は、ほかのスキルの名前と、それぞれを呼び出すタイミングを示すルータースキルを追加してください。

説明

説明には2つの役割があります。スキルの内容を示すことと、そのスキルを呼び出す具体的な状況（分岐）を列挙することです。

• 先頭に主要な単語を置きます。呼び出し処理はここで行われます。
• 1つの分岐につきトリガーは1つにします。同じ分岐を言い換えた同義語は重複です。まとめて、本当に異なる分岐だけを残してください。
• 本文ですでに説明されている内容は省きます。トリガーと、「別のスキルから呼び出す必要がある場合」のような呼び出し条件だけを残してください。

情報の階層

スキルは手順とリファレンスで構成され、どちらも自由に組み合わせられます。それぞれの項目を、エージェントが必要とするタイミングに応じて優先順位付けします。

1. スキル内の手順 — SKILL.md に記載する、順序立てた操作です。各手順の末尾には完了条件を設けてください。確認可能な条件にし（エージェントが完了か未完了かを判断できるか）、必要に応じて網羅的な内容にします（「変更リストを作成する」ではなく、「変更したモデルをすべて確認する」）。曖昧な完了条件は、早まった完了判断を招きます。
2. スキル内のリファレンス — 必要に応じて参照する定義やルールです。互いに独立したルールが平坦に並んでいても問題ありません。
3. 外部リファレンス — SKILL.md からリンク先のファイルに移し、参照先を開く必要が生じた場合にのみ読み込みます。

概念の定義、ルール、注意事項は、同じ見出しの下にまとめてください（近接配置）。一か所を読むだけで関連情報も確認できます。外部に移す内容が少なすぎると冒頭が肥大化し、多すぎるとエージェントに必要な情報が見つけにくくなります。

分割するタイミング

分割するたびにコストが発生するため、分割する価値がある場合にのみ行ってください。

• 呼び出し方法による分割 — 独自の主要な単語で単独に呼び出すべき場合、または別のスキルから呼び出す必要がある場合は、モデルによる呼び出しのスキルを切り分けます。新しい説明が常に読み込まれる分のコンテキストコストが発生します。
• 手順の流れによる分割 — 後続の手順に気を取られ、目の前の手順を急いでしまうおそれがある場合は、手順の流れを分割します。後続の手順を隠すことで、現在の手順により多くの作業を集中させられます。その兆候は段階の圧縮です。複数の手順の作業が1つのメッセージにまとめられたり、エージェントが後続の手順を開いてもいないのに、完了したと説明したりします。メインのスキルに「手順に入ったら、そのファイルを読む」という参照先を記載すると、能力の低いモデルでも確実に参照できます。

失敗パターン

問題のあるスキルを、以下の観点で診断します。

• 早すぎる完了 — まだ終わっていないステップを終わりにしてしまうことです。まず完了条件を修正します（手間がかかりません）。その条件がどうしても曖昧で、かつ急いで終わらせている様子が見られる場合に限り、後続のステップを隠すために分割します。スキルの仕事が成果物の引き渡しで終わる場合は、それだけをスキルレベルの完了条件として明記します。そうしないと、完了したように感じられる中間成果物の段階で実行が終わってしまいます。
• 情報の保留 — 順序のあるワークフローを過剰に遵守することです。エージェントが後のステップの手順を守るために、早い段階で得た知見を伏せてしまい、ユーザーが判断に関わる情報をエージェントが抱えたまま意思決定することになります。ステップに順序を設けるスキルには、次の例外ルールを明記します。順序が規定するのは提示の仕方であり、情報開示ではありません。
• まぐれの成功 — ユーザーや外部の状況が、重要な入力を促されずに提供したおかげで、検証が成功することです。結果は正しくても、プロセスによって得られたわけではありません。同じ幸運が繰り返されることに頼らず、情報を引き出す質問を明示的なステップとして記述します。
• 重複 — 同じ意味が複数の箇所にあることです。信頼できる唯一の情報源を保ちます。
• 堆積 — 追加するほうが安全に感じられるため、古い記述が積み重なることです。意識して削除します。
• 昔話 — 変更から得た教訓を、その変更の逐一の記録として書くことです。関数名、調整した値、あるバグの経緯などの具体例はすぐに古くなり、応用可能なルールを埋もれさせます。原則と注意すべき兆候を述べ、仕組みの詳細はコードベースに委ねます。具体例を1つ示せば理解の助けになりますが、いくつも並べると要点がぼやけます。
• 実装索引 — 本来は判断の仕方を教えるべきスキルが、現在のソースファイル、行番号、現行のリテラル値、正確な内部関数を示していることです。こうした位置情報は古くなり、エージェントが古い仕組みを追う原因になります。スキルには長く使える原則、症状、受け入れ基準、参照資料を残し、タスク固有の実装メモは作業中の仕様書に記載します。コードの場所が重要な場合は、コードベースで現在の担当箇所を探すようエージェントに指示します。
• 肥大化 — すべての行が有効でも長すぎることです。次の段階的な方法で解消します。参照情報はポインターの先に置き、分岐や手順ごとに分割します。
• 不要な指示 — モデルがすでに既定で従う行です。各文を個別にテストし、効果がない場合は文を部分的に短くせず、全文を削除します。

形式

特別な理由がない限り、次の構成を使用します。

---
name: short-verb-phrase
description: What this does. Use when ...
---

# Skill Title

One short paragraph defining the job.

## Workflow

1. Do the first load-bearing thing.
2. Make the key decision.
3. Produce or verify the artifact.

## Rules

- Keep the constraints that prevent common mistakes.
- Link only the references that should be loaded conditionally.

編集手順

スキルを作成または改訂する場合：

• 小文字のハイフン区切りで、動詞 + 複数形の名詞を優先します。例：audit-tests、write-skills、compare-screenshots。フォルダー名とフロントマターの名前は同じにします。複数形にすると意味が損なわれる場合は、自然な例外を認めます。これは新しい名前の既定方針であり、既存のスキル名を変更する義務ではありません。
• 本文を読まなくても適切に呼び出されるよう、説明を具体的にします。
• 本文から「使用するタイミング」のセクションを削除します。
• 古い履歴、帰属情報、プレースホルダー、セットアップメモを削除します。
• スキルがコードナビゲーション用の手順書である場合を除き、ファイルパス、行番号、現在の定数、実装上の調整箇所を削除します。長く使える原則を示し、現在のコードを調べるよう指示することを優先します。
• 重複する箇条書きを複数並べるより、強いルールを1つ示すことを優先します。
• 先頭に置ける言葉がある場合は、それを使って同じ内容の言い換えを整理します。
• 例は短く、現実的なものにします。
• スキルが参照するよう指示している実際の資料でない限り、README、変更履歴、補足ドキュメントを追加しません。
• 利用可能な場合は、スキルバリデーターを実行します。

完了条件

メタデータが適切に機能し、本文を一度で読み通せる長さであり、初めて使うエージェントがスキルの存在理由を尋ねずに従える状態になれば、スキルは完成です。