mattpocock skillsは、TypeScript教育界隈で著名なMatt Pocock氏が公開する 「Skills For Real Engineers」 というクレドを掲げたClaude Code向けスキル集だ。2026年2月の公開後にGitHubスター241,793・Fork 20,564(2026-08-31時点)まで伸び、Claude Code Skillsエコシステムの中で実質的な参照実装になりつつある。本リポジトリの興味深さは、スキルの個別機能というより、「AIエージェントが失敗する4つの理由」を構造的に潰すという設計思想にある。

この記事ではmattpocock/skillsを、READMEで明示される4つの失敗モードとそれに対応するスキル群の対照関係から読み解く。エージェント基盤の選び方そのものは AIエージェントフレームワーク比較2026|LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 を起点にすると整理しやすい。現在の37スキルの構成・導入ルート・呼び出し方は mattpocock/skills完全ガイド|Claude Code用スキル集で開発プロセスを自動化 で扱っている。

4 FAILURE MODES失敗と担い手

AIの4つの失敗を、スキルで1つずつ潰す

AIエージェントの失敗

潰すスキル

AIエージェントの失敗: #1 指示と成果物のズレ(Misalignment)

潰すスキル: /grill-me・/grill-with-docs

AIエージェントの失敗: #2 冗長・言葉の不統一(Verbosity)

潰すスキル: CONTEXT.md+/grill-with-docs

AIエージェントの失敗: #3 コードが動かない(Doesn't Work)

潰すスキル: /tdd・/diagnosing-bugs

AIエージェントの失敗: #4 泥団子化(Ball of Mud)

潰すスキル: /to-spec・/improve-codebase-architecture

出典: mattpocock/skills README(2026-08-31時点)

30秒でわかる

  1. mattpocock skillsの中核は「Real Engineering — not vibe coding」。AIエージェントの4大失敗モードを潰すスキル群として設計されている
  2. 旗艦スキルは /grill-me・/grill-with-docs。アライメント不足という最頻出の失敗を潰す
  3. 枠組みは不変でも担い手は入れ替わる。/cavemanは廃止、/diagnoseは/diagnosing-bugsへ改称、ユビキタス言語の獲得は/grill-with-docsに統合された

なぜmattpocock skillsは24万★まで伸びたのか

mattpocock/skillsのREADMEは、自己紹介をこう要約している。

My agent skills that I use every day to do real engineering - not vibe coding.

過去半年で乱立した「プロセスごとAIに任せる」系のフレームワークへのアンチテーゼでもある。READMEはこう書く。

Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve.

設計思想は 「プロセスを奪わない」 と 「小さく・適応可能に・組み合わせ可能に」 に集約される。Total TypeScriptで型システムを教えてきた同氏の「abstraction is a tool, not a goal」という姿勢の延長にある。

リポジトリの素性

項目 値
リポジトリ mattpocock/skills
公開日 2026-02-03
GitHubスター 241,793(2026-08-31 時点)
Fork 20,564
ライセンス MIT
提供スキル数 37(engineering 18/in-progress 8/productivity 7/misc 4)。うち22本は disable-model-invocation: true を持ち、AI 側からは呼べない
配布手段 Claude Codeプラグイン(claude plugins install mattpocock-skills)/ npx skills@latest add mattpocock/skills

npx skills@latest add は、どのスキルを入れ、どのコーディングエージェントに紐付けるかを対話で選べる別系統のCLI(skills)だ。導入はこの1コマンドから始まる。

# skills.sh 経由(自分たちで編集したい場合)
npx skills@latest add mattpocock/skills

# Claude Codeプラグイン経由(更新を購読したい場合。両方入れると二重になる)
claude plugins install mattpocock-skills

どちらか一方を選ぶ。続けてエージェント側で次を実行する。

/setup-matt-pocock-skills

これで課題管理ツール(GitHub・Linear・ローカルファイル)、/triage のラベル語彙、ドキュメント生成先(docs/adr/ など)を対話で決められる。Matt Pocock skills の他スキルの前提を一か所に集めるハブの役割だ。

4大AI失敗モードと、それを潰す旗艦スキル

真価はREADME後半の 「4 AI Failure Modes」 とスキルの対応にある。FVの図が全体像だ。以下、モードごとに見る。

失敗モード1:Misalignment——/grill-meと/grill-with-docs

最頻出の失敗は「指示と成果物のズレ」。READMEは『The Pragmatic Programmer』の一節を添える。

“No-one knows exactly what they want” — David Thomas & Andrew Hunt

解は 実装前に grill(詰問)する こと。/grill-me は非コード用途(仕様議論・要件定義)、/grill-with-docs はコード用途で、CONTEXT.md と ADR の更新まで行う。後者はREADMEが最も人気のスキルと位置付けている。

たとえば「決済リトライ機構を追加したい」と頼むと、エージェントは実装に入らず、プロバイダ、リトライの起点(4xxのみか5xxも含むか)、冪等キーを発行する既存モジュール、通知の責務、失敗が連鎖したときの受け皿を順に問う。回答が固まると CONTEXT.md を更新し、ADRを起票してから初めてコードに着手する。

失敗モード2:Verbosity——CONTEXT.mdで共有語を作る

2番目は「AIが冗長になる」「同じ概念を別の言葉で呼ぶ」。エリック・エヴァンスのユビキタス言語の不在に対応する。READMEは CONTEXT.md の例を引く。

BEFORE: “There’s a problem when a lesson inside a section of a course is made ‘real’ (i.e. given a spot in the file system)” AFTER: “There’s a problem with the materialization cascade”

共有語が定義されると、以降の会話・コード・ドキュメントが同じ語彙になる。READMEは効果として、変数・関数・ファイル名の一貫、エージェントのナビゲーションのしやすさ、思考に使うトークンの減少を挙げ、「このリポジトリで最もクールな技法かもしれない」と書く。現在この役割は /grill-with-docs の内側にあり、詰問しながら CONTEXT.md とADRを更新していく。

失敗モード3:Doesn’t Work——/tddと/diagnosing-bugs

3番目は「合意したのに動かない」。原因はフィードバックループの不足で、処方箋は TDDとデバッグループ の徹底だ。

/tdd は red-green-refactor を強制し、機能を縦に薄く切ったバーティカルスライス単位で回す。「機能を一気に書く→テストは後→動かず全部書き直す」という暴走パターンを防ぐ。/diagnosing-bugs は 再現→最小化→仮説→計装→修正→回帰テスト の6段階を強制する。再現と最小化が独立ステップなので、AIが憶測で修正案を出せない。

失敗モード4:Ball of Mud——/to-spec・/improve-codebase-architecture

4番目は、AIで加速したらコードベースが泥団子になる失敗だ。READMEはケント・ベックとオースタハウトを引く。

“Invest in the design of the system every day.” — Kent Beck “The best modules are deep.” — John Ousterhout

/to-spec は着手前にどのモジュールを触るかをクイズしてから仕様を作る。/improve-codebase-architecture は泥団子化した箇所を走査し、HTMLレポートで候補を示す。CONTEXT.md の語彙とADRを踏まえるので、無秩序なリファクタを抑えられる。Mattは数日に1回の実行を勧めている。Claude Code skills 実践の流れは、次のコマンドを順に呼ぶ形になる。

/grill-with-docs                  # 実装前に詰問し CONTEXT.md と ADR を更新
/tdd                              # red-green-refactor を縦スライスで回す
/improve-codebase-architecture    # 数日に1回、泥団子化した箇所を洗い出す

同じ方向を別の切り口で追った例として Addy OsmaniのAgent Skills|AIコーディングエージェントに上級エンジニアの思考を注入する24のスキル もある。

設計思想は残り、それを担うスキルは入れ替わった

初出(2026年5月)から、リポジトリの中身はかなり動いている。2026年7月29日時点で skills/ 配下の SKILL.md は41個あり、公開当初に紹介した18スキルの構成とは別物だ。一方、4大失敗モードという枠組みはREADMEの骨格として今も生きている。変わったのは担い手だった。

失敗モード初出時の担い手現在の担い手
#1 ミスアラインメント/grill-me・/grill-with-docs変わらず(READMEは今も「最も人気」と明記)
#2 冗長/ユビキタス言語不在/caveman+CONTEXT.md/grill-with-docs に統合。/caveman は現在のツリーに無い
#3 コードが動かない/tdd・/diagnose/tdd・/diagnosing-bugs(改称)
#4 泥団子化/to-prd・/zoom-out・/improve-codebase-architecture/to-spec・/improve-codebase-architecture

WHAT CHANGED初出からの入れ替わり

枠組みは同じ、担い手の名前が変わった

初出時(2026年5月)

現在

初出時(2026年5月): /caveman

現在: /grill-with-docs に統合(ツリーに無い)

初出時(2026年5月): /diagnose

現在: /diagnosing-bugs に改称

初出時(2026年5月): /to-prd

現在: /to-spec

初出時(2026年5月): ubiquitous-language ほか3本

現在: 2026-08-05 のコミットで削除

出典: mattpocock/skills README・コミット c66bdee

さらに ubiquitous-language・request-refactor-plan・qa・design-an-interface の4つは、2026-08-05 のコミット c66bdee で削除された。同じコミットで personal/ バケット(edit-article/obsidian-vault)も消え、deprecated/ は空のバケットとして残っている。READMEは「引退したスキルは削除する。何に置き換わったかは changeset に書く」と明記する。write-a-prd 系(prd-to-plan/prd-to-issues)と caveman も現在のツリーに無い。

読み取れる含意は2つある。

・枠組みが実装より長生きしている。スキル集を評価するときは、コマンド名ではなく「どの失敗モードに賭けているか」を見るべきだ。
・統合の方向に動いている。/caveman が消えてユビキタス言語の獲得が /grill-with-docs に畳み込まれたのが典型で、スキルを増やすより既存の入口に機能を寄せている。

現在のカタログ面(入っているスキル、導入、呼び出し方)は mattpocock/skills完全ガイド|Claude Code用スキル集で開発プロセスを自動化 が扱う。本記事は「なぜそう作られているか」に絞る。

awesome-codex-skills・他スキル集との相互運用とCodex対応

mattpocock skillsはClaude Code Skills準拠(フォルダ+SKILL.md+frontmatter)で、同じ仕様を採るOpenAI Codexのawesome-codex-skillsとも相互運用しやすい。

項目 mattpocock/skills awesome-codex-skills cloudflare/skills
主対象 Claude Code OpenAI Codex CLI Claude Code/Cursor
思想 Real Engineering — not vibe coding Composioで実アクション集約 Cloudflare Workers/Agents SDK特化
配布 プラグイン / npx skills@latest skill-installer/ スクリプト npm または手動コピー
ライセンス MIT スキル単位 Apache-2.0
中核スキル grill-with-docs/diagnosing-bugs/tdd pr-review-ci-fix/connect workers-ai/agents-sdk

強みは、mattpocock skillsが「プロセス品質」、awesome-codex-skillsが「SaaS連携」、cloudflare/skillsが「プラットフォーム適合」。業務に応じて組み合わせるのが現実的だ。

GSD・BMAD・Spec-Kitとの対比

READMEが名指しする「プロセス所有型」は、エージェント側が要件から検証まで一気通貫で回すため短期の試作に強いが、要件のズレや既存コードとの整合は後で露呈しやすい。mattpocock skillsはフレームワークを持たず、失敗モードごとのスキルだけを用意する。主導権は人間に残り、AIが起こしがちな具体的失敗だけを構造的に防げる。二者択一ではなく、短期スパイクは前者、本流の継続開発はmattpocock skills、という併用も成り立つ。

Codexで動かすときの注意点

SKILL.md自体は流用できる。注意は3点だ。

  1. 配置パス:Claude Codeは .claude/skills/、Codexは $CODEX_HOME/skills/
  2. /setup-matt-pocock-skills はエージェントごとに再実行する(設定ファイルのパスが違う)
  3. gh CLI に依存する箇所があるため、Codex側の認証の引き渡しを確認する

READMEは、Codexネイティブのプラグイン化を検討中として、ADR(.agents/adr/0002-ship-as-a-claude-code-plugin.md)を参照先に挙げている。

社内導入の落とし穴と運用設計のコツ

ROLLOUT段階導入の目安

まず/grill-with-docs だけを定着させる

  1. Week 1

    /setup-matt-pocock-skills と /grill-with-docs のみ

  2. Week 2

    /tdd を新機能に追加

  3. Week 3

    /diagnosing-bugs をバグ発生時に追加

  4. Week 4

    /improve-codebase-architecture を週1の定例で

段階の区切りは本記事の運用案(READMEの規定ではない)

・全スキルを一気に有効化しない。応答が冗長になりクレドと矛盾する。最初の1週間は /grill-with-docs だけを徹底して CONTEXT.md と docs/adr/ の運用を定着させる。これが回らないまま /tdd を入れても、共有語のないままテストを書くことになる。
・CONTEXT.md の肥大化に備える。READMEのTipsには明示がないが、定期的な見直しで使われない用語を消す運用を別途持たせたい。
・導入ルートを混ぜない。READMEは、Claude Codeプラグインと skills.sh を両方入れると 全スキルが二重になる と明記している。「プラグイン(更新を購読する)」か「skills.sh(自分たちで編集する)」のどちらかに寄せ、理由まで先に決める。
・運用をチームで揃える。CONTEXT.md・ADR・PRDの粒度がばらつくと累積効果が出ない。PRテンプレートに「/grill-with-docs で更新した CONTEXT.md/ADR の差分」欄を足し、仕組みで強制するのが早い。
・/git-guardrails-claude-code を先に入れる。push/reset --hard/clean などをhookで止める防御策で、予期せぬgit操作の事故を減らす。

まとめ・FAQ——mattpocock skillsを最大化する次の一歩

真価は個別スキルの便利さではなく、AIエージェントが失敗する4つの理由を構造的に潰す設計思想にある。/grill-with-docs でアラインメントと共有語を作り、/tdd と /diagnosing-bugs でフィードバックループを縛り、/to-spec と /improve-codebase-architecture で泥団子化を防ぐ。

最初の一歩は3つだ。npx skills@latest add mattpocock/skills で導入して /setup-matt-pocock-skills で初期化する。1〜2週間は /grill-with-docs だけを使い、CONTEXT.md と docs/adr/ を定着させる。慣れたら /tdd・/diagnosing-bugs・/improve-codebase-architecture を足す。

銀の弾丸ではない。Mattの方法論は、Pragmatic Programmer・DDD・A Philosophy of Software Designなど古典の原則をスキルに翻訳したものだ。原典を知らずに形だけ真似ると表層的な改善に終わりうるので、READMEが引く書籍にも目を通したい。

Q1. 既存の mattpocock/skills 解説記事との違いは?

A. mattpocock/skills完全ガイド は現在のスキル構成・導入ルート・呼び出し方を扱うカタログ型だ。本記事は設計思想と4大失敗モード、担い手スキルの入れ替わりを追う。

Q2. 昔の記事で見たスキル名が動かないのはなぜ?

A. 再編で改称・統合・削除されたためだ。/caveman と write-a-prd 系は現在のツリーに無く、/diagnose は /diagnosing-bugs へ改称、ubiquitous-language・request-refactor-plan・qa・design-an-interface は2026-08-05に削除された。コマンド名ではなく「どの失敗を潰したいか」から引き直すのが確実だ。

Q3. CodexやCursorで動かすには?

A. SKILL.md仕様はほぼ共通なので配置パスを書き換える。Codexは $CODEX_HOME/skills/<name>/、Cursorは ~/.cursor/skills/<name>/。gh CLI 依存スキル(/triage・/to-tickets)は、ハーネスでCLIを呼ぶ権限を確認する。

Q4. /improve-codebase-architecture はどれくらいの頻度で使う?

A. READMEの推奨は数日に1回。結果は docs/adr/ にADRとして残すと、過去の決定を時系列で追える。

Q5. Claude Code以外のスキル管理は不要になる?

A. ならない。プロセス品質に特化しており、Slack/Linear/Notionなど実アクションを伴う連携はカバーしない。それは awesome-codex-skills のような連携型のスキル集と組み合わせる。SKILL.md 仕様は互換なので混在できる。

Q6. ソロ開発者でも効果はある?

A. ある。自分が忘れがちなアライメント、共有語、テスト粒度、全体設計の観点をエージェントが問い直してくれる。/grill-with-docs を呼ぶ習慣が、CONTEXT.md を更新し続ける動機になる。

参照ソース