skill-authoring

Savant verdict: Pending analysis

Imported from the source hub; Savant's analysis is still running.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

Scan pending.

Structure

• 1 referenced file isn't in the packagereferences/name.md. They may be binary, too large to catalog, or missing upstream.
• No license declaredConfirm you may reuse this skill before importing it into your repository.

SKILL.md

---
name: skill-authoring
description: Agent Skills の skill、つまり `SKILL.md` とそのディレクトリを作る・直す・添削するときに読む。本文を skill が必要な理由と達成したい状態から導いて書き、直すときも全体を導き直す。
metadata:
  derived-from: https://github.com/cursor/plugins/blob/bebaffe14f8f442b98e9c409e960aedad59b5fc8/pstack/skills/poteto-mode/playbooks/authoring-a-skill.md
---

# 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`](references/name.md) も読むこと」と書く
- 「〜は 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 つの文字列にする。

```yaml
metadata:
  derived-from: >-
    https://github.com/<owner>/<repo>/blob/<commit>/path/SKILL.md
    https://github.com/<owner>/<repo>/tree/<commit>/path/another-skill
```

## 用途

次もすべて読むこと。

- [`create`](usecases/create.md)。skill を作る
- [`revise`](usecases/revise.md)。指摘を受けて skill を直す