Addy Osmani agent-skills徹底解剖｜AIエージェントの言い訳を封じる20スキル7コマンド

GoogleでChromeのDX責任者を務めるAddy Osmani氏が2026年に公開した addyosmani/agent-skills は、AIコーディングエージェントの最大の弱点である「最短ルート信仰」を、20スキル＋7スラッシュコマンド＋反論テーブルという三層構造で物理的に封じ込める汎用フレームワークだ。GitHub Starは2026年5月時点で35,000超、forks 4,000超を達成し、Claude Code・Cursor・Copilot・Gemini CLI・Windsurf・OpenCode・Kiroの全主要ハーネスに横断対応している。

Claude Code Skillsの基本コンセプト全般は Claude Code Skills徹底解説 を併せて参照してほしい。

agent-skillsとは何か—Addy Osmani氏が「シニアの仕事」を成文化した理由

Addy Osmani氏はGoogleでChromeのDeveloper Experience（DX）責任者を務め、Web Vitals・Lighthouse・Performance Best Practiceの普及を主導してきた人物だ。著書『Software Engineering at Google』（共著）で広く知られ、Hyrum’s Lawや80/15/5テストピラミッド等の概念を実践現場に持ち込んだ第一人者でもある。

そのAddy Osmani氏が2026年に公開したのが agent-skills だ。氏自身がブログ記事で語る動機は明快である。

動機—エージェントは「シニアの見えない仕事」を全部スキップする

「シニアエンジニアの仕事の大半は、diffに表れない部分でできている」。これがagent-skillsの出発点になっているコアテーゼだ。

AIコーディングエージェントは「動くコード」を最短で出すことを学習目標として最適化されている。だが実際のシニアエンジニアの仕事は、そこに到達する前後にこそ集中する。仕様の確定・タスク分解・テスト戦略・レビュー・スコープ規律・ドキュメント・デプロイ計画——これらは全て「diffに表れない」が、書かれたコードの寿命と保守性を決める。

Addy氏はこの構造を「ジュニアエンジニアと同じ失敗モード」と表現する。ジュニアは何を聞かずにコードを書き始め、テストを書かずに「動きました」と報告し、レビュー指摘で初めて欠けていた工程に気付く。今のAIエージェントもまったく同じ振る舞いをする。

解決アプローチ—スキャフォールドを「強制可能」な形で外付けする

agent-skillsの解決策はシンプルだ。シニアエンジニアが自分自身に課している無意識のチェックリストを、SKILL.md（スキル定義Markdown）として明文化し、エージェントランタイムに強制可能な形で渡す。提案や推奨ではなく、各フェーズで実行する手順とエグジットクライテリア（完了判定基準）を含むワークフローとして。

Addy氏自身の言葉

ブログから抜粋できる氏の表現は以下に集約される。

“Process over prose. Workflows over reference.”

「プロセスは散文に勝る。ワークフローはリファレンスに勝る」。要するに、エージェントは「書かれたガイドライン」を読んで賢くなったりはしない。「実行手順」を踏ませることでだけ品質が上がる、という割り切りだ。

“Passing tests are evidence, not proof.”

「合格テストは証拠であって証明ではない」。これはVERIFYフェーズの基本姿勢で、テスト全合格をもって完了とせず、ユーザー可視の振る舞いと人間レビューを必須化する設計に直結している。

6フェーズSDLCと20スキルの全体像

agent-skillsの構造は、ソフトウェア開発のライフサイクルを6フェーズに分割し、各フェーズに必要なスキルを配置した格子状になっている。

フェーズ図

各フェーズには「キープリンシプル」（守るべき第一原則）が紐づいている。これがエージェントの優先順位判断の基準になる。

全20スキルの一覧表

7スラッシュコマンドとの対応

20スキルは膨大すぎてユーザーが直接呼び出すのは現実的でない。そこでスラッシュコマンドが「フェーズ単位の入口」として用意されており、コマンド発動時に関連スキルが自動活性化する設計になっている。

/spec     → idea-refine + spec-driven-development
/plan     → planning-and-task-breakdown
/build    → incremental-implementation + TDD + context-engineering + 関連BUILD系
/test     → test-driven-development + browser-testing + debugging
/review   → code-review-and-quality + security-and-hardening + performance + simplification
/code-simplify → code-simplification
/ship     → git-workflow + ci-cd + deprecation + documentation + shipping-and-launch

Anti-Rationalization Tables——「言い訳と反論」の発明

agent-skillsを他のSkillsリポジトリと決定的に区別している発明が、各SKILL.mdに必ず含まれる反論テーブル（Anti-Rationalization Table）だ。

反論テーブルの構造

書式は単純だ。各スキルファイルの末尾近くに「Excuse（言い訳）」と「Rebuttal（反論）」の2列テーブルが置かれる。エージェントが手順を省略しようとした時に内心で考えるであろう自己正当化を先回りして書き出し、それぞれに反論をハードコードしてある。

なぜこのパターンが効くのか

LLMの最大の強みは「説得力ある文章生成」だが、これは同時に最大の弱点でもある。エージェントは自分自身に対して説得力のある言い訳を生成して手順を省略する。「このタスクは小さいので仕様書は時間の無駄」「テストはユーザーが指示しなかったので不要」——これらは全て正しく聞こえる。

反論テーブルは、これらのもっともらしい言い訳を事前にカタログ化することで、エージェントが「自分はオリジナルな判断をしている」と錯覚するルートを物理的に塞ぐ。ハードコードされた反論文の存在は、モデルにとって「同じ論点を再度自分で発見できない」状況を作る。

これは行動経済学的に言えばコミットメント・デバイスだ。事前に逃げ道を塞ぐことで、後から「やっぱりこっちでいいか」と判断を翻すコストを上げている。

反論テーブルが守る5つの非交渉項目

メタスキルusing-agent-skillsからAddy氏が抽出した、AGENTS.mdに必ず書くべき5つの非交渉ルールは以下だ。

特に3番目の「Push back when warranted」は重要だ。エージェントが過剰に従順だとユーザーの誤指示が修正されないままコードに焼き込まれる。反論テーブルは、エージェント自身の手順省略だけでなく、ユーザーへの押し返しも奨励する。

Google発のソフトウェア工学プラクティスを丸ごと埋め込む

agent-skillsの内部に埋め込まれている工学知識は、『Software Engineering at Google』（通称SWE-Book）とGoogle Engineering Practicesから引き継がれた実践知の集大成と言える。

Hyrum’s Law（api-and-interface-designスキル）

“With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.”

「APIに十分な数のユーザーがいる時、契約書で何を約束したかは関係ない。観測可能な全ての振る舞いが誰かの依存対象になる」（Hyrum Wright氏発）。これがHyrum’s Lawだ。api-and-interface-designスキルはこの法則を出発点に、One-Version Rule（一バージョン原則）と境界バリデーションを必須化する。

Beyoncé Rule（test-driven-developmentスキル）

“If you liked it, you should have put a (test) on it.”

「気に入ったなら（テストを）書いておけば良かったのに」。Beyoncéの楽曲「Single Ladies」をもじったSWE-Bookの定番表現で、コードを残したいなら必ずテストで囲え、という規律を意味する。test-driven-developmentスキルはこの規律をRed-Green-Refactor手順と組み合わせて強制する。

80/15/5 テストピラミッド

   ╱E2E╲           5%   エンドツーエンド
  ╱─────╲
 ╱統合テスト╲    15%   統合・契約テスト
╱──────────╲
ユニットテスト    80%   関数・クラス単体

下に行くほど数が多く速く安定、上に行くほど少なく遅く脆弱。比率は80/15/5を目安とする。これはGoogle社内の経験則として広く知られているが、agent-skillsはこれをエージェントに自動適用させる点が新しい。

Chesterton’s Fence（code-simplificationスキル）

“Do not remove a fence until you know why it was put up.”

「フェンスがそこに立てられた理由を知るまで、フェンスを取り壊してはならない」（G.K.チェスタトン）。code-simplificationスキルはこの法則をAIエージェントに教え込み、「動かないように見えるコード」「冗長に見える条件分岐」を即座に削除しないよう強制する。同時にRule of 500（一画面に収まる単位を超えないモジュール設計）と組み合わせて、簡潔化の方向を限定する。

Five-Step Triage（debugging-and-error-recoveryスキル）

エラー対応の標準手順として以下を強制する。

Five-Axis Review（code-review-and-qualityスキル）

PRレビューを5軸で評価する手順。

加えて~100行PRサイジング（PR1本あたりdiffを100行程度に抑える）と severity ラベル（Nit / Optional / FYI）の運用が組み込まれている。これは「大きすぎるPRはレビューされない」というGoogle社内の経験則を、エージェントに事前分割させることで対応する。

Trunk-Based Development（git-workflow-and-versioningスキル）

長寿命ブランチを廃し、main直下に小さくマージする運用。git-workflow-and-versioningスキルは以下を強制する。

# 推奨パターン
git checkout -b feat/small-change
# ~100行のatomic commitを1〜3個
git commit -m "Add validation for email field"
git push origin feat/small-change
# CI緑化を確認 → main即マージ → ブランチ削除

「Faster is Safer」（速いほうが安全）というSHIPフェーズの原則は、長寿命ブランチに溜まったコンフリクトと統合債務こそが障害の最大要因だ、という経験則に立脚している。

全主要ハーネスへのインストール—Markdown1本で横展開

agent-skillsの実用面で重要なのは、書き換え不要で全主要ハーネスに横展開できることだ。SKILL.mdというMarkdown形式が、Claude Code・Cursor・Gemini CLI・Windsurf・OpenCode・GitHub Copilot・Kiroの全てで（やや異なる方式ながら）認識される。

Claude Code（推奨：マーケットプレース経由）

# Claude Code内で実行
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

SSHエラーが出る場合はHTTPSで強制クローンする。

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

ローカル開発で試す場合は以下。

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

導入直後から/spec /plan /build /test /review /code-simplify /shipがClaude Code内で使える状態になる。Claude Code Skills機構の自動活性化を最大限活用したい場合はこのルートが最適だ。Claude Code全般のセットアップは Claude Codeベストプラクティス2026 を参照してほしい。

Cursor

SKILL.mdを.cursor/rules/にコピーする方式。プロジェクト固有のルールとしてCursorが起動時に読み込む。

mkdir -p .cursor/rules
cp -r /path/to/agent-skills/skills/* .cursor/rules/

Gemini CLI

ネイティブインストールコマンドで自動配置できる。

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills
# またはローカルクローンから
gemini skills install ./agent-skills/skills/

GEMINI.mdへの追記方式も対応している（永続コンテキスト用途）。

Windsurf

.windsurfrules設定にスキル本文を追加する。詳細は公式docs/windsurf-setup.mdを参照。

OpenCode

AGENTS.mdとskillツールでエージェント駆動の活性化を行う。

GitHub Copilot

agents/配下の定義をCopilotペルソナとして利用、.github/copilot-instructions.mdにスキル本文を追加する二段構え。

Kiro IDE & CLI

.kiro/skills/配下にProjectまたはGlobalレベルで配置。Agents.md形式に対応している。

横展開の威力

ここが重要だ。同じMarkdownファイルを書き換えずに、上記7ハーネス全てで動く。これは単なる「対応」ではなく、企業導入時の選択リスクを劇的に下げる。

「Claude Codeに賭けて全社導入したが半年後にCursorに移行することになった」というケースで、Skills資産を捨てずに引き継げる。これがAddy氏が掲げる「Write once, runtime enforces everywhere（一度書けば全ランタイムで強制される）」の本質的な価値だ。

agent-skills vs 他Skills集の使い分け

2026年5月時点でClaude Code Skills関連のリポジトリは複数存在する。それぞれの位置づけを比較しておこう。

主要Skills集の比較表

どれを選ぶか

claude-code-templatesの詳細は claude-code-templates完全解説、Prismatic Skillsの設計パターンは Prismatic Skills徹底解剖 を参照してほしい。

実装テイクアウェイ—自社プロジェクトに落とし込む方法

agent-skillsの設計思想を自社プロジェクトに移植したい開発者のために、実装パターンを5つにまとめる。

Takeaway 1: 反論テーブルを最初から書く

新規SKILL.mdを書く時、最初に書くべきは「言い訳→反論」の2列テーブルだ。先に手順本文を書くと、後から付け足された反論テーブルは形骸化しがちになる。逆に反論テーブルから書き始めると、手順本文がそれを満たすように設計される。

## Anti-Rationalization Table

| Excuse | Rebuttal |
|---|---|
| "依存ライブラリ追加で済む" | 既存ライブラリで実現可能か30秒検討せよ。新規依存はメンテ債務。 |
| "型定義は後で書く" | 後はない。型なしで書いたコードを後から型付けする工数は2-3倍。 |

Takeaway 2: SDLC 6フェーズに整列させる

社内独自スキルを書く際も、必ずDEFINE/PLAN/BUILD/VERIFY/REVIEW/SHIPのどれかに割り当てる。「複数フェーズに跨る」スキルは大抵スコープが広すぎる兆候だ。

Takeaway 3: 終端で「証拠」を要求する

各SKILL.mdの最後に「完了条件として何を提出するか」を書く。「テスト合格スクショ」「pnpm build成功ログ」「Lighthouse Performance 90+」等、ファイル名・コマンド出力・数値の形で具体化する。

Takeaway 4: メタスキルで動的活性化を設計する

スキルが10個を超えたら、using-agent-skills相当のメタスキル（ルーター）を必ず用意する。「いまどのスキルを呼ぶべきか」をモデルに毎回判断させると、不必要な活性化でトークンを浪費する。タスクのキーワードから決定論的にスキルを選ぶロジックを書いた方が安定する。

Takeaway 5: agents/とskills/を責務分離する

agent-skillsはcode-reviewer test-engineer security-auditorの3エージェントペルソナをスキルとは別ディレクトリagents/に持つ。これは

• skills/: 手順書（誰がやってもこう進める）
• agents/: 専門役（特定の視点・基準で判断）

という責務分離だ。社内導入時もこの2ディレクトリ構造を踏襲するとメンテしやすい。

まとめ—長時間エージェント時代の必須インフラ

addyosmani/agent-skillsは、AIコーディングエージェントが「動くコードを最速で出す」目標最適化の副作用としてシニアエンジニアの実務をスキップする問題を、20スキル＋7コマンド＋反論テーブル＋3エージェントペルソナという四層構造で構造的に解決する2026年最重要のSkills集大成だ。

長時間エージェント実行が当たり前になる2026年後半以降、ショートカットで生まれる「デバッグの考古学（debugging archaeology）」を防ぐためのスキャフォールドは贅沢ではなく必須インフラになる。Addy Osmani氏の言葉を借りれば「The job is to encode discipline as something the agent cannot talk itself out of.」（仕事は、規律をエージェントが言いくるめられない形で符号化することだ）。

agent-skillsは、その符号化作業のリファレンス実装として、現時点で最も完成度が高い。

Claude Code Skills全般の概念は Claude Code Skills徹底解説、Claude Codeの運用ベストプラクティスは Claude Codeベストプラクティス2026、ベンダー製プラグインの設計パターンは Prismatic Skills徹底解剖 を併読してほしい。

参照ソース

• addyosmani/agent-skills – GitHub — リポジトリ本体（Star 35,000+、MIT、最新push 2026-05-07）
• Agent Skills Framework – Addy Osmani Blog — 設計思想の一次情報・5原則・反論テーブルの解説
• Software Engineering at Google — Hyrum’s Law・Beyoncé Rule・80/15/5の原典
• Google Engineering Practices documentation — Five-Axis Review・~100行PRの原点
• Claude Code Skills徹底解説 — Skills機構の全体像