Imported from masseater/skills (
skills/skill-authoring/SKILL.md) via skills.sh. Install upstream withnpx skills add masseater/skills --skill skill-authoring. Copyright stays with the author.
skill-authoring
skill を作る、直す、添削するときの規則である。
- 構成と frontmatter は https://agentskills.io/specification に従う
- 文章は writing に従う
- ユーザーの読み方と考え方は humanity-and-humanness に従う
- 読み手の model 向けの書き方は https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices と、そこから辿れるガイドに従う
この skill が必要な理由と達成したい状態
この skill が必要な理由は、skill を書く AI がユーザーの判断を持っていないことにある。ユーザーが skill を書かせるのは、自分の判断を一度書いておけば、自分がいない場でもその判断で AI が動くからである。ところが書く AI は判断を持たない。足りない部分を自分の知識や一般的な文書の型で埋める。埋めた記述もユーザーの判断と同じ顔で skill に残り、読んだ AI はそれをユーザーの判断として実行する。これを防ぐにはユーザーが全行を自分の判断と照らして弾くしかなく、それでは自分で書くのと変わらない。
この skill で達成したい状態は、skill がユーザーの判断だけでできていることである。
必要な理由と達成したい状態のセクション
規則が当てはまらない場面で、モデルはこのセクションから判断する。だから本文に 1 つ置き、手順や規則と分ける。
- 「この skill が必要な理由は」で書き出す段落を 1 つ置く
- 「この skill で達成したい状態は」で書き出す段落を 1 つ置く
- この skill が何をするかは書かない。それは本文の規則そのものである
必要な理由には、何が困るかだけでなく、それがなぜ起きるかの仕組みを書く。仕組みが書けていれば、想定していない場面でも、同じ仕組みが働くかで判断できる。
達成したい状態には、skill に従い続けた先の状態を、手段に縛られない形で書く。手順や具体的な基準は規則に任せる。
2 つが同じことの裏返しになったら、困りごとの解像度が足りない。症状だけを書くと、達成したい状態はその否定にしかならない。仕組みまで書けない skill は、まだ作る段階にない。
何を書くか
本文に書くのは、ユーザーが依頼と指摘で示した判断と、必要な理由と達成したい状態から導けることだけである。判断はユーザーのものであり、それをどう文章にするかはあなたが責任を持つ。
置き場所
1 つの文書には 1 つの種類だけを入れる。種類の違う節を同じ段に並べると、読み手は見出しを一覧しても分け方を掴めない。
SKILL.mdには、説明である必要な理由と達成したい状態と、参照である規則を置く- 手順は
usecases/に置く。見出しは「〜するとき」ではなく「〜する」の動詞句にする - 特定のリポジトリや環境に固有の参照は
references/に置く
判断の引き出し方
ユーザーは自分の判断をすべて言語化できていない。尋ねるだけでは出てこない。
- たたき台を書いて見せ、反応から判断を読み取る
- 全部を自分で決めない。全部を尋ねもしない
- 必要な理由や達成したい状態を左右する判断は、たたき台に埋め込まない。選択肢と自分の推奨を示し、ユーザーに決めさせる
埋めない
ユーザーが決めていないところを、自分の知識や文書の一般的な型で埋めない。埋めがちなのは次のものである。
- 頼まれていない前提、注意、補足の節
- 念押し
- 書き手にしか通じない言い回し
判断を変えない文、ほかの場所の言い直し、言われなくてもモデルがやることは消す。迷ったら消す。
委ねる
- 他の skill に委ねるときは skill 名だけを書く。中身は言い直さない
- 型、README、設定のような構造的な情報源は指し示す。写さない
- 繰り返す指示は文を足さず、lint、メタデータ、実行時の検査、スクリプトにする。poteto-principles の encode-lessons-in-structure に従う
- 繰り返し踏むのに skill になっていない手順があれば、新しい skill を提案する
references に送る
読まれなければ、どれだけ整備しても意味がない。
- 関係するセクションの先頭に「
nameも読むこと」と書く - 「〜は name にある」「〜のときだけ読む」のように、読まなくてもよいと思わせる文脈は残さない
- コンテキストが膨れてもよい。読んだ後に、これは不要だったと判断できればよい
書きぶり
モデルは理由から、書いていない場面にも規則を広げる。だから規則には理由を添える。
- 規則には理由を一文添える。理由がなくても読み違えようのない規則には付けない
- 「〜しない」で終えず、代わりに何をするかを書く
- 避けてほしい形は一般論にせず、具体的に名指しする
- 出力の形を決めたいときは、文で説明するより良い例を示す
- 思考や検証の量を増やす指示は書かない。確かめ方を決めたいときは、量ではなく方法を書く
- 推論を書き出させる指示は拒否されうる。要るなら結果の短い説明を求める
- 強い言い回しや強調を足さない。いまのモデルは指示に過敏に反応する
確かめる方法の例は、poteto-principles の prove-it-works にある「代わりのものでなく実物を見る」である。
frontmatter
nameはディレクトリ名と同じにする。本文の最初の見出しも同じ名前にするdescriptionには何をするかと、いつ使うかを書く。使う場面の語を入れるdescriptionに本文の目次を書かない。references/やusecases/が増えるたびに直すことになるlicenseは書かない。LICENSE ファイルも作らない
metadata.derived-from
metadata.derived-from には、この skill の原典の URL だけを書く。原典とは、その内容を取り込み、読み替えてこの skill にしたものである。skill でも記事でもよく、取り込んだ後に書き直していても原典である。
- 書くときに読んだだけの資料は原典ではない。本文にリンクを書く
- 本文で根拠として引く資料は原典ではない。引く箇所にリンクを書く
- 本文から名前で委ねる skill は原典ではない
- GitHub の URL はコミットを指定した permalink にする
- 原典の URL、作者、バージョンは本文と
references/に書かない
metadata の値は文字列だけなので、複数の URL は空白区切りの 1 つの文字列にする。
metadata:
derived-from: >-
https://github.com/<owner>/<repo>/blob/<commit>/path/SKILL.md
https://github.com/<owner>/<repo>/tree/<commit>/path/another-skill用途
次もすべて読むこと。
