skill-authoring

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

用途

次もすべて読むこと。

• create。skill を作る
• revise。指摘を受けて skill を直す