agentic-skills

agentic-skills — AI エージェント向け本番エンジニアリングフレームワーク

キーワード：agentic-skills · /spec · /plan · /build · /test · /review · /code-simplify · /ship

「正しそう」だけでは不十分です。すべての出力を測定可能な検証に基づかせましょう。

agentic-skills は、シニアエンジニアがソフトウェア開発で使用するワークフロー、品質ゲート、ベストプラクティスを組み込んだ、本番グレードのエンジニアリングフレームワークです。Google のエンジニアリング文化（Software Engineering at Google）から、トランクベース開発、シフトレフトテスト、ハイラムの法則、チェスタトンの柵、コードを負債と捉える考え方を取り入れています。

プラグインのインストール（Claude Code）：

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

このスキルを使用する場面

• 手戻りを防ぐため、コードを書く前に仕様を定める、規律ある契約が必要な場合
• 小さな垂直スライスと頻繁な検証による段階的な実装が必要な場合
• リリース前にテスト駆動開発（Red → Green → Refactor）が必要な場合
• セキュリティ強化や OWASP Top 10 の対策が対象に含まれる場合
• 公式ドキュメントに基づく、ソース主導の開発をユーザーが求めている場合
• Core Web Vitals の目標を満たすパフォーマンス最適化が必要な場合
• 本番環境向けの git ワークフロー（トランクベース、アトミックコミット、CI/CD 品質ゲート）が必要な場合
• マージ前に 5 つの品質軸に沿ったコードレビューを行う場合
• 本番リリース前に、出荷チェックリストと段階的なロールアウトが必要な場合

このスキルを使用しない場面

• 複数エージェントのオーケストレーションとルーティングが必要な場合 → jeo、oh-my-claudecode、または harness にルーティングします
• 主なタスクが実装前の広範な調査である場合 → survey にルーティングします
• 品質ゲートなしの一度限りの簡単な修正が必要な場合 → 直接実行します
• エージェントチームの設計をユーザーが求めている場合 → harness にルーティングします

インストール

Claude Code（推奨）

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

Gemini CLI

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

Cursor / Windsurf

各 skills/*.md ファイルの内容を .cursor/rules/ またはエディターのルール設定にコピーします。

OpenCode

リポジトリのルートにある AGENTS.md を介して、エージェント主導の実行を行います。

ローカルクローン

git clone https://github.com/addyosmani/agent-skills.git
# Reference skill files from the local path

開発ライフサイクルのフェーズ

現在の作業に合ったフェーズを選択してください。各フェーズは、1 つ以上のスラッシュコマンドに対応しています。

フェーズ 1 — 定義 /spec

スキル：idea-refine、spec-driven-development

依頼が曖昧、または詳細が不十分な場合は、ここから始めます。

• idea-refine：大まかなアイデアを具体的で実行可能な提案に変換します
• spec-driven-development：コードを書く前に、完全な PRD（要件、制約、受け入れ基準）を作成します

/spec "build a user authentication flow"

合理化を防ぎます。「アイデアは明白だから」という理由で仕様策定を決して省略しないでください。意図の不一致は、最も大きな手戻りの原因になります。

フェーズ 2 — 計画 /plan

スキル：planning-and-task-breakdown

仕様を、個別に検証できる小さな作業単位に分解します。

• ストーリーを、個別に完了・テストできるタスクに分割します
• 着手前に影響範囲を見積もります
• 依存関係を特定し、順序を明示します

/plan  # after /spec is frozen

フェーズ 3 — 構築 /build

スキル：incremental-implementation、test-driven-development、context-engineering、source-driven-development、frontend-ui-engineering、api-and-interface-design

場当たり的なチャットの文脈ではなく、仕様に沿って実装します。

• incremental-implementation：小さな垂直スライスで進め、各スライスのテストに合格してから次に進みます
• test-driven-development：Red → Green → Refactor。失敗するテストを書く前に実装を始めてはいけません
• context-engineering：適切な情報を適切なタイミングで LLM に提供します
• source-driven-development：SDK／API／フレームワークに関するすべての判断を公式ドキュメントに基づかせます
• frontend-ui-engineering：コンポーネントアーキテクチャ、デザイントークン、アクセシビリティ、パフォーマンス予算を扱います
• api-and-interface-design：実装前に検証を行う、契約優先の API 設計です

/build  # slice-by-slice against the frozen spec

Phase 4 — /test で検証

スキル: browser-testing-with-devtools、debugging-and-error-recovery

成功を主張する前に検証してください。

• browser-testing-with-devtools: ランタイムの検査、ネットワークのトレース、パフォーマンスのプロファイリング、アクセシビリティ監査
• debugging-and-error-recovery: 5 段階のトリアージ（観察 → 再現 → 仮説立案 → テスト → 修正）

/test  # mechanical + semantic + browser verification

ドリフトのしきい値：

• 0.00–0.15 — 優秀。続行してください
• 0.15–0.30 — 注意深く監視してください
• 0.30+ — 続行する前に中断して修正してください

Phase 5 — /review と /code-simplify でレビュー

スキル: code-review-and-quality、code-simplification、security-and-hardening、performance-optimization

マージ前に、5 つの観点からレビューしてください。

• code-review-and-quality: 正確性、読みやすさ、保守性、パフォーマンス、セキュリティ
• code-simplification: 認知負荷を減らしながら動作を維持
• security-and-hardening: OWASP Top 10 の予防、シークレットのスキャン、入力の検証
• performance-optimization: まず測定し、最適化の前に Core Web Vitals の目標を設定

/review        # five-axis quality gates
/code-simplify # behavior-preserving clarity pass

変更規模の基準：

• 小規模：200 行未満、単一の関心事
• 中規模：200～500 行、関連する関心事
• 大規模：500 行超 → 分割するか、PR の説明で正当化

Phase 6 — /ship でリリース

スキル: git-workflow-and-versioning、ci-cd-and-automation、deprecation-and-migration、documentation-and-adrs、shipping-and-launch

規律を守ってリリースしてください。

• git-workflow-and-versioning: トランクベース開発、アトミックなコミット、セマンティックバージョニング
• ci-cd-and-automation: 品質ゲートのパイプライン、テストの自動化、安全なデプロイ
• deprecation-and-migration: 移行ガイドを用いた体系的なレガシーコードの削除
• documentation-and-adrs: 自明でない選択についてのアーキテクチャ決定記録
• shipping-and-launch: リリース前チェックリスト、段階的なロールアウト（1% → 10% → 50% → 100%）、ロールバック計画

/ship  # pre-launch checklist + staged rollout

専門家のペルソナ

レビュー作業向けの 3 つの専門家ペルソナ：

ペルソナ	対象
code-reviewer	正確性、アーキテクチャ、読みやすさ、テストカバレッジ
test-engineer	テスト戦略、エッジケース、カバレッジの不足
security-auditor	OWASP Top 10、シークレット、認証フロー、入力の検証

参照用チェックリスト

チェックリスト	目的
testing-patterns	テストの種類、分離、カバレッジの目標
security-checklist	OWASP への準拠、認証、シークレット、ヘッダー
performance-checklist	CWV の目標、バンドルの予算、レンダリングパス
accessibility-checklist	WCAG 2.1 AA、キーボード、ARIA、フォーカス

哲学的な基盤

原則	適用
コードは負債	すべての行が保守の負担です。その存在理由を明確にしてください
ハイラムの法則	観測可能な振る舞いはすべて依存されるようになります。契約を明示してください
チェスタトンの柵	何かを取り除く前に、それが存在する理由を理解してください
ビヨンセ・ルール	「気に入ったなら、それをテストするべきだった」
シフトレフト	問題は後（本番環境）ではなく、早い段階（仕様）で検出してください
トランクベース開発	短命なブランチ、頻繁な統合、リスクのある作業にはフィーチャーフラグを使用

クイックコマンドリファレンス

コマンド	フェーズ	目的
/spec	定義	コーディング前に仕様書／PRDを作成
/plan	計画	仕様を検証可能なタスクに分割
/build	構築	仕様に沿って段階的に実装
/test	検証	ブラウザー、ランタイム、受け入れの検証
/review	レビュー	5 つの観点による品質ゲート
/code-simplify	レビュー	動作を維持しながら明瞭さを向上
/ship	リリース	リリース前チェックリストと段階的なロールアウト

運用ルール

1. コードより仕様を優先する — 仕様が確定する前に、実装を開始してはいけません
2. 実装よりテストを優先する — TDD を実践し、機能コードを書く前に失敗するテストが存在していなければなりません
3. 推測より情報源を優先する — SDK/API を使用する前に、公式ドキュメントを確認してください
4. 最適化より測定を優先する — パフォーマンス改善には、ベースラインの測定結果を示す成果物が必要です
5. 完了前に検証する — 「問題なさそう」では不十分です。すべての出力に、測定可能な根拠が必要です
6. 段階的にリリースする — 段階的なロールアウトとロールバック計画を用意し、リスクの高い変更を全環境に一括デプロイしてはいけません

出典：addyosmani/agent-skills — MIT License

手順

1. タスクのトリガーと期待される出力を特定します。
2. このスキルのワークフロー手順を上から順に実行します。
3. 次のステップに進む前に、出力を検証します。
4. いずれかのステップが失敗した場合は、ブロッカーと代替手段を記録します。

例

• 例：まず小さな範囲にこのスキルを適用し、検証に合格した後で対象範囲を広げます。

ベストプラクティス

• 出力の再現性と監査可能性を保ちます。
• 広範囲でリスクの高い編集より、小規模で元に戻せる変更を優先します。
• 前提条件を明確に記録します。

参考資料

• プロジェクト標準：.agent-skills/skill-standardization/SKILL.md
• バリデータースクリプト：.agent-skills/skill-standardization/scripts/validate_skill.sh