7 つの手順

1. すでに繰り返した作業から始める
思いつきから始めないでください。手作業で少なくとも 3 回やった作業から始めます。そうして初めて、どの手順が実在し、どれが想像だったのかが分かります。「場合による」と言わずに作業を説明できないなら、仕組み化には早すぎます。
2. フォルダーを作り、名前を厳密に決める
フォルダー名と name フィールドは一致している必要があり、名前には制約があります。小文字、数字、ハイフンのみ、先頭と末尾のハイフン不可、連続ハイフン不可、最大 64 文字です。後から変えると両方を変えることになるので、長く使える名前にしてください。
```
my-skill/
├── SKILL.md          # required
├── references/
│   └── REFERENCE.md  # loaded only when needed
└── scripts/
    └── check.py
```
必須は SKILL.md だけです。ほかは必要になったときに読み込まれます。
3. 本体より先に説明文を書く
説明文はスキルが読み込まれるかどうかを決めるので、作業を人の言葉で覚えているうちに、最初に書いてください。何をするのか、いつ使うのかを述べ、自分の言い回しだけでなく同僚が使いそうな言い方も入れます。

4. 本体は論説ではなく手順として書く

本体が読まれるのは、エージェントが起動を決めた後です。ですから手順、判断点、出力の形を書きます。モデルがすでに知っている一般知識は外してください。文脈を消費するだけで何も足しません。

---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
---

# Release notes

## Steps
1. List merged pull requests since the previous tag.
2. Group them by user facing change, not by author or by file.
3. Drop internal refactors unless they change behaviour.
4. Write one line per change, in the present tense.

## Output
A Markdown list under a version heading. No emoji. No marketing language.

これで完全に有効なスキルです。出力の節が、形式のぶれを止めます。

5. 任意フィールドは必要なときだけ足す
ほとんどのスキルは name と description 以外を必要としません。公開するときに license、環境が本当に問題になるときだけ compatibility、仕様が定義しない情報には metadata を使います。allowed-tools は実験的なので、対応状況は不確実だと考えてください。
```
---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
license: MIT
compatibility: Requires git and network access to the repository host
metadata:
  author: example-org
  version: "1.2"
---
```
6. 長いものは references に分ける
本体はスキルが起動するたびに全文が読み込まれるので、目安として 500 行未満に保ち、詳細は references/ に移します。参照は 1 階層に留めてください。ファイルが互いを指し合う連鎖は遅く、迷いやすくなります。
```
See [the full grouping rules](references/GROUPING.md).

Run the collector first:
scripts/collect.py --since v1.4.0
```
7. 検証し、他人の言葉で発動を試す
まず検証ツールを実行します。名前とフロントマターの誤りは、一度も読み込まれないスキルという形で現れるからです。次に、どの検証ツールも見られない部分を試します。同僚が言いそうな表現で作業を頼み、スキルが発動するか確かめてください。しなければ、悪いのは本体ではなく説明文です。
```
skills-ref validate ./my-skill
```

代償の大きい 5 つの誤り

いずれもレビューでは問題なく見え、使う段階で失敗します。だからこそ長く生き残ります。

自分の語彙で書かれた説明文: 自分の言い方にしか一致しません。良いスキルが一度も使われない理由として最も多いものです。
手順ではなく論説: 背景と理由づけは、エージェントの動きを変えないまま、起動のたびにトークンを消費します。
モデルがすでに知っていることを書く: プルリクエストとは何かの説明は、トークンを増やすだけで挙動を変えません。書くのは自分たちの規約です。
同じ判断を指示するスキルが 2 つ: エージェントは矛盾した指示を受け取り、見えないところで折り合いをつけます。仕事ごとに拠り所は 1 つに。
発動を一度も試さない: 本体は手動で起動して確認されます。自動で発動するかを確かめる人はほとんどいません。

配布する

スキルはフォルダーなので、配布とはそのフォルダーを導入できる場所に置くことです。最も簡単なのは、skills CLI で追加できる公開リポジトリです。公開の前に互換性マップを確認してください。すでに広く使われている別のスキルが担っている判断に自分のスキルも指示を出すなら、利用者に衝突を発見させるのではなく、自分の説明文でそのことを述べてください。

npx skills add owner/repo

SKILL.md リファレンス説明文チェッカー衝突と組み合わせ

7 つの手順

1. すでに繰り返した作業から始める

2. フォルダーを作り、名前を厳密に決める

3. 本体より先に説明文を書く

4. 本体は論説ではなく手順として書く

5. 任意フィールドは必要なときだけ足す

6. 長いものは references に分ける

7. 検証し、他人の言葉で発動を試す

代償の大きい 5 つの誤り

配布する