AIコーディングエージェントに「うまく動いてほしい」と思ったとき、多くのエンジニアがまず試みるのは .cursorrules や CLAUDE.md に指示を書き足すことです。
でも正直なところ、そのファイルがどんどん膨らんで、何が効いているのか分からなくなった経験はないでしょうか。
Addy Osmani（Google Chrome DevRel）が公開した addyosmani/agent-skills は、その「何となく書いてきた指示書」を 再利用可能な判断ロジック として設計し直すための、具体的なリファレンスになっています。
リポジトリのファイル構造と記述パターンを実際に読み解きながら、「production-grade なスキル定義」が何を意味するのかを整理します。
MCP（何を接続するか）やメモリ管理の話は今回の射程の外です。あくまで「エージェントに何をどう判断させるか」というプロンプト設計の話として展開します。
スキル定義とは何か――「指示書」との決定的な違い
エージェントへの指示には、大きく分けて2つのレイヤーがあります。
一つは「今回のタスクをこうやってほしい」という単発のプロンプト。
もう一つは「このプロジェクトではこういう判断基準で動いてほしい」という、繰り返し適用される文脈の定義です。
.cursorrules に書き足してきた内容は、多くの場合この2つが混在しています。
「コメントは英語で書いて」という規約と、「テストを書く前に仕様を確認して」という判断フローが、同じフラットなファイルに並んでいる状態です。
これでも動くことは動くのですが、チームで共有したり、プロジェクトをまたいで再利用したりしようとすると、とたんに扱いにくくなります。
スキル定義が目指しているのは、 判断ロジックのカプセル化 です。
「コードレビューをするとき、エージェントはどういう順序で何を見て、何を理由に指摘を保留するか」という、ベテランエンジニアの頭の中にある暗黙の判断基準を、再現可能な形で書き出すことです。
単なる手順書との違いは、「やること」だけでなく「やらない理由を先回りして潰す」記述が含まれている点にあります。
この設計思想が、後述する SKILL.md の構造に直接反映されています。
リポジトリ構造と SKILL.md の記述パターン
リポジトリのルートにある CLAUDE.md には、プロジェクト全体の構造が簡潔にまとめられています。
各ディレクトリの役割はこうなっています。
- skills/ ― コアスキル。skills/
/SKILL.md という粒度で1スキル1ファイルに切られている - agents/ ― 再利用可能なエージェントペルソナ（code-reviewer、test-engineer、security-auditor、web-performance-auditor など）
- hooks/ ― セッションのライフサイクルフック（セッション開始・終了時の処理）
- .claude/commands/ ― /spec、/plan、/build、/test、/review、/code-simplify、/ship などのスラッシュコマンド定義
- references/ ― テスト・パフォーマンス・セキュリティ・アクセシビリティ・オブザーバビリティの補足チェックリスト
収録スキルの例を挙げると、spec-driven-development、context-engineering、code-review-and-quality、test-driven-development、incremental-implementation、code-simplification、planning-and-task-breakdown といったものがあります。
「コードを書く」という行為の中にある、個別の 判断フェーズ がそれぞれ1スキルとして切り出されているのが分かります。
スラッシュコマンドとスキルの関係も押さえておくと理解が深まります。
/spec は spec-driven-development スキルを、/review は code-review-and-quality スキルを呼び出す対応になっています。
コマンドはあくまでスキルの 呼び出し口 に過ぎず、判断ロジックの実体はスキルファイルの側にあります。
/build auto が planning-and-task-breakdown → incremental-implementation + test-driven-development という順でスキルを連鎖させる設計になっているのが、その好例です。
個別のスキルファイルの構造は、getting-started.md にある解剖図がそのまま設計書になっています。
YAML frontmatter (name, description)
├── Overview — このスキルが何をするか
├── When to Use — 発動条件とトリガー
├── Core Process — ステップバイステップのワークフロー
├── Examples — コードサンプルとパターン
├── Common Rationalizations — 言い訳とその反論
├── Red Flags — スキルが守られていないサイン
└── Verification — 終了条件チェックリスト
Overview・When to Use・Core Process は、一般的な手順書にも存在するセクションです。
決定的に違うのは後半の3つ―― Common Rationalizations、 Red Flags、 Verification です。
Common Rationalizations は「このスキルを適用しなくていい理由として、エージェントが持ち出しがちな言い訳」とその反論を列挙するセクションです。
「今回は小さな変更だからテストは省略していい」「この部分は後でリファクタリングするから今は雑でいい」といった、エージェントが（そして人間も）陥りがちな合理化を先回りして潰します。
Red Flags は「スキルが正しく適用されていないときのシグナル」を、Verification は「このスキルの適用が完了したと言えるための終了条件」を定義します。
context-engineering スキルを例に取ると、コンテキストを永続性の高い順に積む、という設計思想が具体的に記述されています。
---
name: context-engineering
description: Manages context window usage to maximize relevant information
density. Use when working on complex, multi-file tasks or long sessions.
---
## When to Use
- Starting a complex feature that spans multiple files
- Session has been running long and context feels "stale"
- Agent is making decisions that seem to ignore earlier constraints
- Preparing handoff documentation for a new session
## Red Flags
- Reloading the same files repeatedly across iterations
- Losing track of constraints established earlier in the session
- Context window approaching limits with low-value content
- Making assumptions instead of checking the actual source
## Verification
- [ ] High-persistence context (rules, architecture) loaded once at session start
- [ ] Per-task context scoped to only relevant files
- [ ] No redundant file loads across iterations
- [ ] Handoff notes written before session ends if work continues
Red Flags を見ると、「同じファイルを繰り返し読み込んでいる」「前の制約を無視した判断をしている」という、エージェントが実際にやりがちな失敗パターンが書かれています。
Verification のチェックリストは、「完了した」とエージェントが自己申告するための 終了条件 を明示しています。
この構造が意味するのは、スキルファイルが「何をするか」だけでなく「何をしていないときに止まれ」という ガードレール を内包しているということです。