addyosmani/agent-skills

AI にコードを書かせるとき、進め方の指示は毎回こちらが言い直すことになる。このリポジトリは、その指示をあらかじめ手順書の束にしたもの。仕様を決める、分解する、実装する、テストする、レビューする、出す、という開発の各段階に対応する25本が入っている（24本が各段階のもの、残る1本は「どれを使うか選ぶ」ためのもの）。ライセンスは MIT。

中身はふつうの Markdown のファイルで、1本ごとに書式が決まっている。何をするものか、どんなときに使うか、手順、言い訳と、それへの反論、危険な兆候、そして終わりの条件としての証拠。README はこの設計を「読み物ではなく、たどる手順」と説明し、「良さそうに見える」で終わらせず、テストの結果やビルドの出力といった証拠を求めることを共通の決まりにしていると書いている。必要になったときだけ補助の資料を読み込む構成なので、最初から全部を読ませるわけではない。

入れ方は2通り。共通のコマンドで一括して入れる方法（README は対応する道具を70種類以上としている）と、使っている道具ごとの入れ方だ。9個のスラッシュコマンドが段階の入り口になっていて、たとえば API を設計し始めれば設計用の手順書が、画面を作り始めれば画面用の手順書が自動で立ち上がる。ほかに、レビュー専門・テスト専門・セキュリティ専門・Web性能専門の4つの役柄と、7本の確認用チェックリストが付いている。

同じ注意を毎回しているとき

「先に仕様を書いて」「テストを通してから言って」といった指示を毎回打っているなら、それは手順書にできる部分だ。25本のうち必要なものだけを入れることもできる。

進め方を人に説明しづらいとき

各手順書は、段階・手順・終わりの条件の形で書かれている。AI に読ませる文書であると同時に、人が読める進め方の説明にもなっている。新しく入った人に渡すものが無いときの土台にできる。

1本だけ入れると、付属の資料が付いてこない。 README 自身が但し書きしていて、1本単位で入れた場合、リポジトリ側にある共通のチェックリストは複写されない。手順書自体は動くが、資料への参照が切れる。まとめて入れるか、必要な資料を手で置くことになる。

道具ごとに入れ方も落とし穴も違う。 一括で入れるコマンドのほかに、Claude Code、Cursor、Codex、Gemini CLI など個別の手順が並んでいる。README には、特定の道具でコマンドの呼び出しがうまく見つからない場合の回避方法や、SSH の設定に起因する失敗への対処も書かれている。入れる前に、自分の道具の節を読む前提のものだ。

Web 寄りの前提が混じっている。 テストの書き方の資料は JavaScript / TypeScript のもので、性能の目標にはブラウザ側の指標が入っている。分野が違えば、その部分は読み替えることになる。

厳しさが合わないことがある。 証拠を出すまで終わりにしない、省略の言い分に反論する、という作りなので、短く試したいだけのときは重い。手早く動くものを作りたい場面と、外に出すものを作る場面で、入れる手順書を分けるほうが現実的だ。