skill-md-review

SKILL.md を、cccskills（https://cccskills.com/evaluation）が公開スキルに付けている客観評価と同じ基準で点検する。採点の根拠は SKILL.md と、そこから参照されているファイルの中身だけにする。スター数・作者・文章の上手さは採点に入れない。

使う場面

• 自作スキルを GitHub や cccskills に公開する前の点検
• 「入れても安全か」を判断するための、他人のスキルの点検
• 採点が B や C の項目を A に上げたいとき

手順

1. 対象を集める

1. 対象のフォルダか SKILL.md のパスを確かめる。指定がなければ、カレントディレクトリ以下の SKILL.md を探して一覧を示し、どれを見るか聞く。
2. SKILL.md を読む。本文から参照されているファイル（scripts/・references/・assets/ など）があれば、それも読む。スクリプトは読むだけで実行しない。
3. 参照先のファイルが存在しないときは、その事実を記録する（採点の材料にする）。

2. 形式を検査する（合否のみ）

検査	合格の条件
frontmatter	先頭が --- で始まり、YAML として読める
name	小文字英数字とハイフンだけ、64 文字以内、フォルダ名と一致
description	空でない、1024 文字以内、「何をするか」と「いつ使うか」の両方が書かれている
参照先	本文で名前を挙げたファイルがすべて存在する
長さ	本文がおおむね 500 行以内（超えるなら references/ への分割を勧める）

不合格の項目があれば、採点の前にまとめて示す。

3. 4 項目を A/B/C で採点する

項目	A	B	C
clarity（指示の明確さ）	使う場面と動作が明確	おおむね分かるが曖昧な所がある	何をするのか読み取りにくい
specificity（手順の具体性）	手順と出力の形が具体的	一部だけ具体的	方針の羅列で手順がない
safety（安全面）	注意が要る操作がない、または範囲と確認手順が明示されている	注意が要る操作があり、説明が足りない所がある	削除・外部送信・認証情報の読み取りを確認なしで行う、または説明と実際の処理が食い違う
setup（導入のしやすさ）	前提がほぼない、または導入手順まで書かれている	前提はあるが一部しか書かれていない	前提が多いのに書かれていない

safety を判定するときは、本文とスクリプトの中から次を探し、見つかった箇所をすべて挙げる。

• 外部への送信（curl・fetch・requests・WebFetch・API 呼び出し・メール送信）
• ファイルの削除・上書き（rm・git reset --hard・git push --force・> での上書き）
• 認証情報の読み取り（.env・~/.ssh・~/.aws・トークンや API キーの環境変数）
• パッケージの導入やシステム設定の変更（npm install -g・pip install・sudo）

見つかった操作それぞれについて、SKILL.md に「何を・どこへ・ユーザーの確認を取るか」が書かれているかを確かめる。書かれていなければ B、確認なしで影響の大きい操作をするなら C にする。

setup では、必要なツール（CLI・言語ランタイム）、API キーの名前、有料サービス、OS の前提を洗い出し、SKILL.md に書かれているかを確かめる。

4. 結果を返す

次の形で返す。根拠は SKILL.md の具体的な箇所（見出し・行・コマンド名）に触れる。褒め言葉・推測は書かない。

## skill-md-review: <name>

### 形式
- [x] frontmatter / [x] name / [ ] description（「いつ使うか」がない） / [x] 参照先 / [x] 長さ

### 採点
| 項目 | 判定 | 根拠 |
| --- | --- | --- |
| clarity | A | description と「使う場面」で対象が明確 |
| specificity | B | 手順 3 の出力形式が書かれていない |
| safety | B | scripts/sync.sh が curl で外部 API に POST するが、送る内容が書かれていない |
| setup | C | GITHUB_TOKEN と jq が必要だが記載がない |

### 直し方（効果の大きい順）
1. **setup C→A**: 「## 前提」節を足す（下に差分）
2. ...

「直し方」には、B・C の項目ごとに SKILL.md へそのまま貼れる差分か文案を付ける。A の項目には何も書かない。

5. 直すかどうかを聞く

• 直し方を示したあと、SKILL.md に反映するかを聞く。ユーザーが了承するまでファイルを書き換えない。
• 反映したら、手順 2〜3 をやり直して採点の変化を示す。

採点の注意

• 書かれていないことは推測で補わない。「書かれていない」こと自体を判定の材料にする。
• description と本文・スクリプトの動作が食い違うときは、safety を C にして食い違いを具体的に示す。
• この採点は SKILL.md の書き方の点検で、安全を保証するものではない。結果の末尾でそう伝える。

もう一歩：実行して確かめる

cccskills では、書き方の採点とは別に「スキルあり・なしで同じ依頼を Claude Code に実行させて比べる」実行検証をしている。自分で試すなら、スキルが効くはずの依頼を 2〜3 個作り、スキルを入れた状態と外した状態で結果を比べるよう勧める。依頼文の案もあわせて出す。

このスキルについて

• 作者: cccskills（https://github.com/cccskills/skills）
• 外部への送信・コマンドの実行はしない。ファイルの書き換えは手順 5 でユーザーが了承したときだけ行う。