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 は、まだ作る段階にない。
何を書くか
本文に書くのは、ユーザーが依頼と指摘で示した判断と、必要な理由と達成したい状態から導けることだけである。判断はユーザーのものであり、それをどう文章にするかはあなたが責任を持つ。
置き場所
各事実は、モデルが必要とする前に届く段のうち、いちばん読まれる回数の少ない段に置く。上の段ほど多くの場面で読まれ、そのたびにコンテキストを使う。
descriptionは全セッションで読まれる。使う場面を見分けるきっかけだけを置くSKILL.mdは skill を使うたびに読まれる。必要な理由と達成したい状態と、どの場面でも要る規則を置くusecases/には、一部の場面でしか要らない手順を置く。見出しは「〜するとき」ではなく「〜する」の動詞句にするreferences/には、一部の場面でしか要らない参照を置く。特定のリポジトリや環境に固有の参照と、規則の詳細がこれにあたる- ほとんどの場面で読む
usecases/やreferences/はSKILL.mdに上げる - スクリプト、雛形、素材は読ませず、実行させるか写させる
usecases/ と references/ へのリンクは writing の ai-context に従って書く。どの場面で読むかは、リンクを置く節で決まる。
判断の引き出し方
ユーザーは自分の判断をすべて言語化できていない。尋ねるだけでは出てこない。
- たたき台を書いて見せ、反応から判断を読み取る
- 全部を自分で決めない。全部を尋ねもしない
- 必要な理由や達成したい状態を左右する判断は、たたき台に埋め込まない。選択肢と自分の推奨を示し、ユーザーに決めさせる
埋めない
ユーザーが決めていないところを、自分の知識や文書の一般的な型で埋めない。埋めがちなのは次のものである。
- 頼まれていない前提、注意、補足の節
- 念押し
- 書き手にしか通じない言い回し
消すのは次のものである。迷ったら消す。
- 判断を変えない文と、削っても動きが変わらない語
- 言われなくてもモデルがやること。定義、一般的な慣行、自明な考えの例がこれにあたる
- 人間だけが要るもの。経緯、きっかけになった出来事、計測値はコミットメッセージに書く
- 同じ意味の 2 つめ。
SKILL.md、references/、usecases/、ツールの文書を通して、1 つの意味は 1 か所に置く
ただし、書き込み、マシンの外へのデータ送信、有料の枠のように取り返しのつかない操作には、モデルが知っていることでも安全の規則を 2、3 行残す。
すべての行がモデルの動きを変え、同じ意味が 2 度出てこなければ、書き終わりである。
委ねる
- 他の skill に委ねるときは skill 名だけを書く。中身は言い直さない
- 型、README、設定のような構造的な情報源は指し示す。写さない
- ツールの使い方を教える skill では、正確な名前、引数、値をツールの help とエラーに任せる。skill には、よく使う呼び出しと、モデルが間違える呼び出しの形だけを書く
- 繰り返す指示は文を足さず、lint、メタデータ、実行時の検査、スクリプトにする。poteto-principles の encode-lessons-in-structure に従う
- 繰り返し踏むのに skill になっていない手順があれば、新しい skill を提案する
書きぶり
モデルは理由から、書いていない場面にも規則を広げる。だから規則には理由を添える。
- 規則には理由を一文添える。理由がなくても読み違えようのない規則には付けない
- 規則には、モデルが既に知っている短い名前を付ける。多くの規則を覆う既知の標準があれば、標準の名前とどこまで従うかを書く
- 場合を並べず、それらを生む考え方を書く
- 「〜しない」を並べず、代わりに何をするかを 1 つの基準で書く。禁止の形は、肯定の形にできない安全の規則にだけ使う
- 避けてほしい形は一般論にせず、具体的に名指しする
- 思考や検証の量を増やす指示は書かない。確かめ方を決めたいときは、量ではなく方法を書く
確かめる方法の例は、poteto-principles の prove-it-works にある「代わりのものでなく実物を見る」である。
frontmatter
nameはディレクトリ名と同じにする。本文の最初の見出しも同じ名前にするdescriptionには何をするかと、いつ使うかを書く。使う場面の語を入れる。全セッションで読まれるので、場面ごとにきっかけを 1 つだけ書く- ユーザーしか起動しない skill には
disable-model-invocation: trueを付け、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用途
次もすべて読むこと。
