Agent Skills
Production-grade engineering skills for AI coding agents. — addyosmani/agent-skills
何か
Agent Skills は、AI コーディングエージェントがシニアエンジニアと同じ品質規律でソフトウェアを開発できるように設計されたワークフロー集。各スキルは「手順（Process）・アンチ合理化表（Rationalizations）・検証要件（Verification）」の 3 要素で構成され、エージェントが最短ルートを選んで仕様・テスト・セキュリティレビューをスキップする問題を防ぐ。
24skills/ 配下
6開発フェーズ
8スラッシュコマンド
4エージェントペルソナ
設計哲学: スキルは「参照ドキュメント」ではなく「エージェントが従うワークフロー」。手順・チェックポイント・終了条件を持ち、
SKILL.md がエントリポイント。サポート参照はトークン節約のために必要時だけロードする Progressive Disclosure を採用。
スキルの解剖学
すべてのスキルは一貫した構造を持つ。
┌─────────────────────────────────────────────┐
│ SKILL.md │
│ │
│ ┌─ Frontmatter ─────────────────────────┐ │
│ │ name: lowercase-hyphen-name │ │
│ │ description: Use when [trigger] │ │
│ └───────────────────────────────────────┘ │
│ │
│ Overview → 何をするスキルか │
│ When to Use → 発動条件 │
│ Process → ステップバイステップの手順 │
│ Rationalizations → スキップ言い訳 + 反論 │
│ Red Flags → 問題のサイン │
│ Verification → 証拠要件（証明が必要） │
└─────────────────────────────────────────────┘
6 フェーズ
DEFINE
→
PLAN
→
BUILD
→
VERIFY
→
REVIEW
→
SHIP
フルフィーチャーの標準的なスキル実行順:
1. idea-refine → アイデアを精錬
2. spec-driven-development → 何を作るか定義
3. planning-and-task-breakdown → 検証可能な粒度に分解
4. context-engineering → 正しいコンテキストをロード
5. incremental-implementation → スライスごとに実装
6. test-driven-development → 各スライスを証明
7. code-review-and-quality → マージ前レビュー
8. git-workflow-and-versioning → クリーンなコミット履歴
9. documentation-and-adrs → 意思決定を記録
10. shipping-and-launch → 安全にデプロイ
柔軟な適用: すべてのタスクがすべてのスキルを必要とするわけではない。バグ修正なら
debugging-and-error-recovery → test-driven-development → code-review-and-quality の 3 スキルで十分なことが多い。公式仕様に縛りたい作業では source-driven-development、本番直前の判断では doubt-driven-development を足す。
スキル選択ツリー
タスクが届いたとき、どのスキルを使うかを判定するデシジョンツリー。
flowchart TD
T["タスク到着"] --> A{"フェーズ判定"}
A --> D0["要件が曖昧
→ interview-me"] A --> D1["曖昧なアイデア
→ idea-refine"] A --> D2["新機能・新プロジェクト
→ spec-driven-development"] A --> D3["仕様あり・タスク分解
→ planning-and-task-breakdown"] A --> D4{"実装フェーズ"} D4 --> B1["コード実装
incremental-implementation"] D4 --> B2["UI 作業
frontend-ui-engineering"] D4 --> B3["API 設計
api-and-interface-design"] D4 --> B4["コンテキスト不足
context-engineering"] D4 --> B5["公式根拠
source-driven-development"] D4 --> B6["高リスク検証
doubt-driven-development"] A --> D5{"検証フェーズ"} D5 --> V1["テスト
test-driven-development"] D5 --> V2["ブラウザ検証
browser-testing-with-devtools"] D5 --> V3["障害対応
debugging-and-error-recovery"] A --> D6{"レビューフェーズ"} D6 --> R1["コードレビュー
code-review-and-quality"] D6 --> R2["セキュリティ
security-and-hardening"] D6 --> R3["パフォーマンス
performance-optimization"] A --> D7{"出荷フェーズ"} D7 --> S1["Git / コミット
git-workflow-and-versioning"] D7 --> S2["CI/CD
ci-cd-and-automation"] D7 --> S3["ドキュメント
documentation-and-adrs"] D7 --> S4["デプロイ
shipping-and-launch"]
→ interview-me"] A --> D1["曖昧なアイデア
→ idea-refine"] A --> D2["新機能・新プロジェクト
→ spec-driven-development"] A --> D3["仕様あり・タスク分解
→ planning-and-task-breakdown"] A --> D4{"実装フェーズ"} D4 --> B1["コード実装
incremental-implementation"] D4 --> B2["UI 作業
frontend-ui-engineering"] D4 --> B3["API 設計
api-and-interface-design"] D4 --> B4["コンテキスト不足
context-engineering"] D4 --> B5["公式根拠
source-driven-development"] D4 --> B6["高リスク検証
doubt-driven-development"] A --> D5{"検証フェーズ"} D5 --> V1["テスト
test-driven-development"] D5 --> V2["ブラウザ検証
browser-testing-with-devtools"] D5 --> V3["障害対応
debugging-and-error-recovery"] A --> D6{"レビューフェーズ"} D6 --> R1["コードレビュー
code-review-and-quality"] D6 --> R2["セキュリティ
security-and-hardening"] D6 --> R3["パフォーマンス
performance-optimization"] A --> D7{"出荷フェーズ"} D7 --> S1["Git / コミット
git-workflow-and-versioning"] D7 --> S2["CI/CD
ci-cd-and-automation"] D7 --> S3["ドキュメント
documentation-and-adrs"] D7 --> S4["デプロイ
shipping-and-launch"]
Meta
どのスキルを当てるか
| スキル | 何をするか | いつ使うか |
|---|---|---|
using-agent-skills |
着手中の作業を適切なスキルワークフローへマッピングし、共通の運用ルールを定義 | セッション開始時や、どのスキルを適用すべきか決めたいとき |
Define
何を作るかを明確にする
| スキル | 何をするか | いつ使うか |
|---|---|---|
interview-me |
1 問ずつインタビューし、ユーザーが本当に望む要件を ~95% の確信まで抽出 | 依頼が曖昧なとき、「interview me」「grill me」と言われたとき |
idea-refine |
発散・収束の構造思考で曖昧なアイデアを具体的な提案に変換 | 荒削りなコンセプトをブラッシュアップしたいとき |
spec-driven-development |
コードの前に目的・コマンド・構造・テスト・境界を網羅した PRD を書く | 新プロジェクト・機能・重大な変更を始めるとき |
Plan
実装可能な粒度に分解
| スキル | 何をするか | いつ使うか |
|---|---|---|
planning-and-task-breakdown |
仕様を小さく検証可能なタスクに分解し、受け入れ基準と依存関係を整理 | 仕様があり、実装単位に落としたいとき |
Build
コードを書く
| スキル | 何をするか | いつ使うか |
|---|---|---|
incremental-implementation |
薄い垂直スライスで実装・テスト・検証・コミット。フィーチャーフラグ・安全なデフォルト | 複数ファイルにまたがる変更 |
test-driven-development |
Red-Green-Refactor・テストピラミッド (80/15/5)・DAMP over DRY・Beyonce Rule | ロジック実装・バグ修正・動作変更 |
context-engineering |
適切な情報を適切なタイミングでエージェントに渡す — rules ファイル・コンテキストパッキング・MCP 統合 | セッション開始時・タスク切り替え時・出力品質が低下したとき |
source-driven-development |
公式ドキュメントに根拠を置く — 出典の検証・引用・未検証箇所の明示 | フレームワークやライブラリの判断を権威ある情報で裏付けたいとき |
doubt-driven-development |
非自明な判断を対話的に疑う — CLAIM → EXTRACT → DOUBT → RECONCILE → STOP（必要なら別モデル検証） | 本番・セキュリティ・不可逆変更などリスクが高いとき、自信過剰な出力を早めに検証したいとき |
frontend-ui-engineering |
コンポーネントアーキテクチャ・デザインシステム・状態管理・WCAG 2.1 AA アクセシビリティ | ユーザー向けインターフェースの構築・変更 |
api-and-interface-design |
コントラクトファースト設計・Hyrum's Law・One-Version Rule・エラーセマンティクス・境界バリデーション | API・モジュール境界・公開インターフェースの設計 |
Verify
動作を証明する
| スキル | 何をするか | いつ使うか |
|---|---|---|
browser-testing-with-devtools |
Chrome DevTools MCP でライブランタイムデータを取得 — DOM・コンソール・ネットワーク・プロファイル | ブラウザで動くものの構築・デバッグ |
debugging-and-error-recovery |
5 ステップトリアージ: 再現 → 局所化 → 縮小 → 修正 → ガード。Stop-the-line ルール | テスト失敗・ビルド破損・予期しない動作 |
Review
マージ前の品質ゲート
| スキル | 何をするか | いつ使うか |
|---|---|---|
code-review-and-quality |
5 軸レビュー・変更サイズ (~100 行)・重大度ラベル (Nit/Optional/FYI)・分割戦略 | 変更をマージする前 |
code-simplification |
Chesterton's Fence・Rule of 500・動作を保ちながら複雑性を削減 | コードは動くが読みにくい・保守しにくい |
security-and-hardening |
OWASP Top 10 防止・認証パターン・シークレット管理・依存関係監査・3 層境界システム | ユーザー入力・認証・データストレージ・外部統合 |
performance-optimization |
計測ファースト — Core Web Vitals 目標・プロファイリング・バンドル分析・アンチパターン検出 | パフォーマンス要件がある・リグレッションが疑われる |
Ship
自信を持ってデプロイ
| スキル | 何をするか | いつ使うか |
|---|---|---|
git-workflow-and-versioning |
トランクベース開発・アトミックコミット・変更サイズ管理・コミット=セーブポイントパターン | コード変更のたびに（常に） |
ci-cd-and-automation |
Shift Left・Faster is Safer・フィーチャーフラグ・品質ゲートパイプライン・フィードバックループ | ビルド・デプロイパイプラインの設定・変更 |
deprecation-and-migration |
コード=負債の考え方・強制 vs 勧告の廃止・マイグレーションパターン・ゾンビコード除去 | 旧システム除去・ユーザー移行・機能サンセット |
documentation-and-adrs |
Architecture Decision Records・API ドキュメント・インラインドキュメント標準 — why を記録 | アーキテクチャ決定時・API 変更時・機能出荷時 |
observability-and-instrumentation |
構造化ログ・RED メトリクス・OpenTelemetry トレース・症状ベースのアラート — 構築と同時に計装 | テレメトリ追加時、本番で動くものを出荷するとき |
shipping-and-launch |
出荷前チェックリスト・フィーチャーフラグライフサイクル・段階的ロールアウト・ロールバック手順・監視設定 | プロダクションへのデプロイ準備 |
開発ライフサイクルにマップされたコマンド
7 つのライフサイクルコマンドがエントリポイント。内部で適切なスキルを自動的にアクティベートする。加えて /webperf で Web パフォーマンス監査ペルソナを起動できる。
/spec
Spec before code
何を作るかを定義する。spec-driven-development スキルを起動。
/plan
Small, atomic tasks
実装方法を計画する。planning-and-task-breakdown スキルを起動。
/build
One slice at a time
インクリメンタルにコードを書く。実装系スキルを自動選択。
/test
Tests are proof
動作を証明する。test-driven-development スキルを起動。
/review
Improve code health
マージ前にレビュー。code-review-and-quality スキルを起動。
/code-simplify
Clarity over cleverness
コードを簡潔にする。code-simplification スキルを起動。
/ship
Faster is safer
プロダクションへデプロイ。shipping-and-launch スキルを起動。
/webperf
Measure, don't guess
Core Web Vitals 監査。web-performance-auditor ペルソナを Quick / Deep モードで起動。
/build auto
仕様が固まったあと手順を減らしたい場合は /build auto。プラン生成から全タスク実装までを 1 回の承認で走らせる。タスク間の人間ステップは省くが、各タスクは TDD と個別コミットのまま。失敗やリスクの高いステップでは一時停止する。
自動スキル選択
コマンドを使わなくても、何をしているかに基づいてスキルが自動的にアクティベートされる。API 設計をしていれば api-and-interface-design が、UI を構築していれば frontend-ui-engineering が動く。
スペシャリストペルソナ
特定の観点で集中的なレビューを行うために事前設定された専門家エージェント。
Senior Staff Engineer
code-reviewer
5 軸コードレビュー。「スタッフエンジニアがこれを承認するか？」が判断基準。
QA Specialist
test-engineer
テスト戦略・カバレッジ分析・Prove-It パターン。
Security Engineer
security-auditor
脆弱性検出・脅威モデリング・OWASP アセスメント。
Web Performance Engineer
web-performance-auditor
Core Web Vitals 監査（Quick / Deep）。メトリクスの正直さルール付き。
/webperf から起動。
リファレンスチェックリスト
スキルが必要に応じて参照するクイックリファレンス素材。4 種類を収録。
| リファレンス | カバー範囲 |
|---|---|
testing-patterns.md | テスト構造・命名・モッキング・React/API/E2E の例・アンチパターン |
security-checklist.md | コミット前チェック・認証・入力検証・ヘッダー・CORS・OWASP Top 10 |
performance-checklist.md | Core Web Vitals 目標・フロントエンド/バックエンドのチェックリスト・計測コマンド |
accessibility-checklist.md | キーボードナビ・スクリーンリーダー・ビジュアルデザイン・ARIA・テストツール |
コアオペレーティング行動
すべてのスキルにまたがって常に適用される非交渉的な行動規範（using-agent-skills より）。
- 仮定の表面化: 非自明な実装の前に仮定を明示し、承認を求めてから進む。
- 混乱の積極的管理: 不整合や矛盾に直面したら STOP し、具体的な問いを立てて解消する。
- 適切なプッシュバック: 問題のあるアプローチには直接指摘し、代替案を提案する。同意マシンにならない。
- シンプルさの強制: 実装前に「これはより少ない行数でできるか？」を確認する。
- スコープ規律: 指示されたものだけに触れる。近隣コードの無許可リファクタは行わない。
- 検証の非省略: すべてのスキルには検証ステップがある。「それっぽい」は証拠にならない。
対応ツール
Agent Skills は Markdown のスキルファイルで構成されており、システムプロンプトや指示ファイルを受け付けるあらゆるエージェントで動作する。
Claude Code
Cursor
Antigravity CLI
Gemini CLI
Windsurf
OpenCode
GitHub Copilot
Kiro
Codex / その他
Claude Code（推奨）
Marketplace インストール
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
SSH で失敗する場合: マーケットプレースの clone が SSH 前提のことがある。GitHub に SSH 鍵を登録するか、HTTPS でカタログを追加してからインストールする（例:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git → 同じ @addy-agent-skills 名で install）。
ローカル / 開発
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
Cursor
任意の SKILL.md を .cursor/rules/ にコピーするか、リポジトリの skills/ を参照する。詳細は上流の docs/cursor-setup.md。
# 特定スキルだけ使う場合
cp skills/spec-driven-development/SKILL.md .cursor/rules/spec.md
# ディレクトリ参照（推奨）
# .cursor/rules/ に skills/ を追加して全スキルを有効化
Antigravity CLI
スキル・サブエージェント・スラッシュコマンドをネイティブプラグインとして登録する。Antigravity 内部の /plan と衝突するため、プラグイン側は /planning を使う。
agy plugin install https://github.com/addyosmani/agent-skills.git
# ローカル clone から
agy plugin install ./agent-skills
Gemini / Windsurf / Copilot / OpenCode / Kiro
| ツール | インストール方法 |
|---|---|
| Gemini CLI | gemini skills install https://github.com/addyosmani/agent-skills.git --path skills（リモート）またはローカル clone から gemini skills install ./agent-skills/skills/。docs/gemini-cli-setup.md |
| Windsurf | ルール設定へスキル内容を取り込む。docs/windsurf-setup.md |
| GitHub Copilot | agents/ をペルソナに、スキル本文を .github/copilot-instructions.md へ。docs/copilot-setup.md |
| OpenCode | AGENTS.md と skill ツールによるエージェント駆動のスキル実行。docs/opencode-setup.md |
| Kiro IDE / CLI | .kiro/skills/（プロジェクトまたはグローバル）と Agents.md。公式: kiro.dev/docs/skills/ |
| Codex / その他 | プレーン Markdown のため、システムプロンプトや指示ファイルとして読み込ませる。docs/getting-started.md |
Hooks
セッション開始用の hooks/session-start.sh に加え、sdd-cache-pre.sh / sdd-cache-post.sh（SDD キャッシュ）、simplify-ignore.sh（簡素化時の無視リスト）などが hooks/ にある。設定は hooks/hooks.json。
session-start.sh は開始時にスキル一覧とコンテキストを渡し、どの SKILL.md を当てるかエージェントが選びやすくする。
Contributing: スキルは 具体的（実行可能な手順・曖昧なアドバイスではない）・検証可能（明確な終了基準）・実戦検証済み・最小限であることが求められる。docs/skill-anatomy.md と CONTRIBUTING.md を参照。
リポジトリ構成（要約）
agent-skills/
├── skills/ # 24 スキル（23 ライフサイクル + メタ）
├── agents/ # 4 ペルソナ（code-reviewer 等）
├── references/ # チェックリスト 4 種
├── hooks/ # セッション・SDD・simplify 等
├── .claude/commands/ # 8 スラッシュコマンド（Claude Code）
├── .gemini/commands/ # Gemini CLI 用コマンド
├── commands/ # 8 スラッシュコマンド（Antigravity CLI）
├── plugin.json # Antigravity プラグインマニフェスト
└── docs/ # ツール別セットアップガイド上流: github.com/addyosmani/agent-skills（MIT）