Agent Skillを書く時の心得

Agent Skillを作成・編集する間、以下の基準に従う。

心得1. 読み手は賢いmodelである

skillを実行するのは、文脈を読んで自分で判断できるmodelである。skillに書くのは、modelが推論では到達できない事だけにする。プロジェクトや作者に固有の方針、隠れた制約、外からは見えない前提、やってみないと分からないgotchaがこれに当たる。

• 考えれば分かる判断を、防御的に明文化しない。edge caseの除外規定や、誤読を防ぐための但し書きを足さない
• 読解力の低いmodelに合わせて設計しない。文脈を読み取れないmodelは、skillが求める他の作業も実行できない

心得2. 方針を書き、手段は任せる

何を確かめるか、何を達成するかを書く。どう行うかは、実行するmodelに任せる。

• どのツールのどのコマンドで行うかを、手順として指定しない。同じ操作でも、CLIで行う環境とMCPで行う環境がある。特定のコマンドを書くと、別の手段しか無い環境では成り立たなくなる
• 進め方が状況で分かれる作業に、特定のシナリオの具体例を入れない。modelが状況から判断するのをやめ、例に倣う

心得3. 無いとmodelが行き詰まる記述は残す

心得1と2は、具体的な記述を消す理由にならない。消す前に、その記述が無い時にmodelがどう実行するかを想像し、行き詰まるなら残す。

• 数万行あるlock fileから依存関係を調べる時の絞り込みコマンドのように、判断の助けになるヒントは残す。手順としての強制や、進め方を1つに寄せる具体例とは別の物である
• 特定のエコシステムに依存した記述を、抽象化のために先回りして消さない。他のエコシステムに対応する時に書き換えれば足りる

心得4. 嘘になりうる事を書かない

• 外部ツールの出力の実例を貼らない。ツールの体裁が変わると実態と食い違う。何を抜き出すかは、報告や成果物の形式例で示す
• 外部の実装に由来する列挙値を書かない。相手の実装が変わると実態と食い違う。挙動の原理と大分類までを書く。例えばファイルの埋め込みを扱うskillなら、対応する拡張子の一覧ではなく、拡張子で判定される事と、画像・動画・音声という対象の大分類を書く
• 実行時に確定できない値を、記録項目にしない。推定値が混ざると、記録全体が信用できなくなる

心得5. 実行するmodelに向けた事だけを書く

• その方法を選んだ経緯や、試して却下した案は、commit messageやPR概要欄に書く
• skillのREADMEは人間が導入を判断するための物で、実行するmodelは読まない。modelが実行する手順はSKILL.mdだけに書き、READMEに写さない

心得6. 編集する時は、全体としての最善を目指す

既存のskillに手を入れる時、変更差分を小さく保とうとしない。足す内容を既存の節の末尾に継ぎ足すのではなく、その内容が最初からあったらどう書いたかを考える。構成を大きく変えて構わない。判断基準を並べたガイドライン型のskillでは、特にそうする。

心得7. レビュー指摘の採否

外部Agentやsubagentの指摘は、事実として正しくても、skillに書く価値があるとは限らない。指摘が正しいかの検証とは別に、採否を以下の問いで決める。

• 問1. 賢いmodelなら、その場で判断できる事ではないか
• 問2. 特定の手段を手順として強制したり、特定のシナリオの具体例で進め方を寄せたりしていないか
• 問3. 外部ツールの出力の実例、外部の実装に由来する列挙値、実行時に確定できない値に頼っていないか
• 問4. 実行するmodelではなく、将来の編集者に向けた事ではないか
• 問5. それが無いと、modelが実行に行き詰まる事ではないか

問1から問4に当たる指摘は採用しない。問5に当たる指摘は採用する。

採用しなかった指摘は、理由を添えてユーザーに報告する。