# SKILL.md の書き方

## frontmatter

`name` と `description` の2つだけを必須にします。

- `name`: 英小文字とハイフン。フォルダ名と一致させます
- `description`: 1文から2文。何をするか、いつ使うか

`allowed-tools` を書くと、その Skill が使えるツールを制限できます。読み取りだけの Skill なら `Read, Glob, Grep` に絞ります。書き換えさせない保証がここで作れます。

## 本文

### 具体的に書く

| 避ける書き方 | 書き直した例 |
|---|---|
| 適切にファイルを確認する | `Glob` で `src/**/*.java` を列挙し、`service` パッケージのファイルだけを読む |
| 必要に応じて修正する | 深刻度「高」のものだけ修正する。「中」以下は報告に載せる |
| 良い形式で出力する | `.work/result.md` に、ID・場所・内容・根拠の4列の表で出す |

### 長さ

- 200行を超えたら分割します。詳しい判断材料は `references/` に置き、SKILL.md からは「迷ったときだけ読む」と書いて参照します
- 全部読ませると、毎回のトークン消費が増えます

### やらないことを書く

範囲外のことを明記します。これが無いと、Skill が呼ばれたついでに関係ない作業まで進めてしまいます。

## フォルダ構成

```
.claude/skills/<名前>/
├── SKILL.md          必須
├── references/       任意。詳しい判断材料
└── scripts/          任意。補助スクリプト
```

`references/` の中身は、SKILL.md から参照されたときだけ読まれます。最初から全部読まれるわけではありません。
