mattpocock/skills

README の “real engineering, not vibe coding” を、実務での選び方に変換する運用地図。v1.1 の軸は to-spec → to-tickets → implement。巨大自動運転ではなく、ズレを減らす小さなループを差し込む。

1 — 概要

Operating model

mattpocock/skills（package 1.1.0 / plugin manifest 1.2.0）は、コーディングエージェントに読み込ませる小さなスキル集。リポジトリ全体のプロセスを奪うのではなく、計画確認、共有語彙、TDD、診断、トリアージ、設計改善という「事故りやすい瞬間」にだけ介入する。

22plugin entries

13user-invoked

9model-invoked

1setup contract

入口は /ask-matt。状況に合うスキルへルーティングする。主経路は idea → grill → to-spec → to-tickets → implement。

Source: README.md, package.json, .claude-plugin/plugin.json, .agents/invocation.md

Design stance

GSD / BMAD / Spec-Kit のように全体ワークフローを所有するより、ユーザーが制御を持ったまま必要なスキルを組み合わせる設計。失敗時にプロセス自体を直しやすい。

読み方: これはスキル一覧ではなくルーティング表。今起きている失敗を見て、入れるループを選ぶ。迷ったら /ask-matt。

2 — インストール

skills.sh（編集可能）

スキルをプロジェクトへコピーする。hack して自分用に直したいとき向き。

shell

npx skills@latest add mattpocock/skills

/setup-matt-pocock-skills を必ず選び、repo ごとに一度走らせる。

Claude Code plugin（購読）

read-only の managed bundle。作者が ship したら追従する。自分でメンテしない。

claude code

/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock

どちらも最後は /setup-matt-pocock-skills が必要。Codex 等は skills.sh 経由で Agent Skills 標準へ入る（native Codex plugin は roadmap）。

3 — 呼び出しモデル

User-invoked vs model-invoked

スキルは 誰が到達できるか で分類する。旧来の Commands / Skills 区分は廃止済み。

種別	到達方法	description の向き	例
user-invoked	人間が slash 名を入力したときのみ	人間向けの一行要約（`disable-model-invocation: true`）	`/grill-me`, `/to-spec`, `/wayfinder`, `/ask-matt`
model-invoked	人間またはエージェントの自動選択	モデル向けトリガー文（"Use when…"）	`/tdd`, `/grilling`, `/prototype`, `/research`

user-invoked は model-invoked を呼べるが、別の user-invoked は呼べない。依存は /skill 形式の prose invocation で表現し、フォルダ横断リンクは使わない。共有語彙は /codebase-design と /domain-modeling に集約される。

4 — メインフロー（idea → ship）

ask-matt router

/ask-matt が定義する主経路。コードベースがあるなら /grill-with-docs で合意と CONTEXT.md / ADR を残す（内部は /grilling）。設計疑問は /handoff → /prototype → /handoff で runnable に解消する。複数セッションの build なら /to-spec → /to-tickets まで同一 context windowを保ち、ticket ごとに fresh session で /implement を走らせる。

Grill

/grill-with-docs で合意と domain docs。コードベースなしなら /grill-me。/grilling は確認ゲートまで待つ。

Spec

複数 session なら /to-spec → /to-tickets。単発ならそのまま implement へ。

Implement

/implement が ticket を TDD slice で組み立て。内部で /tdd（red → green）を呼ぶ。

Review

/code-review で Standards + Spec の二軸レビュー後 commit。refactor はここ。

On-ramps & standalone

状況	入口	備考
外部から来た raw issue / PR	`/triage`	`/to-tickets` 由来は triage しない。PR は setup のトグル次第
硬い bug / flake	`/diagnosing-bugs`	feedback loop 確立後に fix。post-mortem で architecture へ
1 session に収まらない霧	`/wayfinder`	決定チケットの地図。終わったら `/to-spec` へ合流
調査を delegate したい	`/research`	background agent が primary sources を読み cited Markdown を残す
context が smart zone 付近	`/handoff`	fresh session へ。mid-phase の `/compact` は避ける

5 — 失敗モード別ルート

Misalignment

Agent didn't do what I want

作る前の合意が薄い。/grill-me または /grill-with-docs で設計ツリーを質問で潰す。事実はコード探索、決定は人間に聞く。/grilling は共有理解の確認まで計画を実行しない。

Main skills: grill-me, grill-with-docs, grilling

Vocabulary drift

Agent is too verbose

同じ概念を毎回20語で説明している。CONTEXT.md と ADR に共有語彙を置き、会話とコードの命名を短くする。/domain-modeling が能動的に更新する。

Main skills: grill-with-docs, domain-modeling, setup-matt-pocock-skills

Broken output

Code doesn't work

エージェントが動くフィードバックループを持っていない。/tdd は pre-agreed seam で RED → GREEN。/diagnosing-bugs は再現信号から原因へ進む。

Main skills: tdd, diagnosing-bugs

Entropy

Ball of mud

生成速度が設計負債も加速している。/to-spec は触る module を確認してから spec を作り、/to-tickets で vertical slice（または wide refactor の expand–contract）に分ける。/prototype で捨て UI/CLI を試し、/improve-codebase-architecture で deep module 候補を探す。

Main skills: to-spec, to-tickets, prototype, improve-codebase-architecture

6 — セットアップ契約

Hard vs soft dependency

/setup-matt-pocock-skills は、他の engineering skills が共有する repo 固有の契約を作る。Issue tracker（GitHub / GitLab / local markdown / その他）、triage labels、domain docs の置き場を記録する。

依存タイプ	対象スキル	必要な契約	ない場合
hard	`to-tickets`, `to-spec`, `triage`, `wayfinder`	Issue tracker と triage label vocabulary	Issue 作成先や label が間違う
soft	`diagnosing-bugs`, `tdd`, `improve-codebase-architecture`, `codebase-design`, `domain-modeling`	domain glossary と ADR	動くが、語彙と判断が浅くなる

Quickstart checklist

Install

skills.sh または Claude plugin でセットを入れる。

Select setup

/setup-matt-pocock-skills を必ず選ぶ / 実行する。

Record contract

tracker・labels・domain docs を docs/agents/ に書く。

Route work

以後は /ask-matt か主経路で同じ語彙で作業する。

7 — 品質ループ

Feedback first

/diagnosing-bugs の中心は「まず高速で決定的な pass/fail signal を作る」こと。/tdd は reference-only の red → green。refactor はループ外で、/code-review 側。テストは pre-agreed seam のみ。tautological test（期待値が実装と同じ再計算）は anti-pattern。

Signaltest / CLI / browser / harness

Reproduceuser symptom を確認

Hypothesize3-5 個、予測つき

Instrument仮説に対応する probe

Fixregression test → fix

Postmortem防げた設計を確認

Code review gate

/code-review は固定点（commit / branch / tag）からの diff を Standards（repo 標準 + Fowler smell baseline 約12種）と Spec（originating issue / PRD との一致）の二軸で並列 sub-agent レビューする。repo 標準が baseline より優先。smell は judgement call であり hard violation ではない。

TDD contrast

やらない	やる	理由
全テストを先に書く	1 test → 1 implementation	想像上の振る舞いではなく、学びに反応した test になる
private method を検証する	合意した seam の振る舞いを検証する	内部リファクタで壊れない
実装と同じ式で期待値を作る	独立した source of truth から期待値を取る	tautological test を避ける
mock で形だけ通す	real code path を通す	本当の統合バグを拾える

8 — チケット化フロー

Spec to tickets

v1.1 で to-prd は /to-spec に改名、to-plan / to-issues は /to-tickets に統合された。/to-spec は会話を spec にまとめ、/to-tickets は blocking edges 付きの tracer-bullet tickets に分解する。local tracker なら edges はテキスト、実 tracker なら native blocking links。

Conversation

既に話した内容と codebase 状態を合成する。

Spec

/to-spec で Problem / Solution / Stories / Testing を発行する。

Tickets

/to-tickets で vertical slices + Blocked by。wide refactor は expand–contract。

Implement

ticket ごと fresh session で /implement → /code-review → commit。

外部由来の issue / PR だけ needs-triage から triage state machine に乗せる。/to-tickets 出力は agent-ready なので triage しない。

Triage state machine

Role	意味	次の動き
`needs-triage`	maintainer 評価待ち	bug/enhancement と実装可能性を判断
`needs-info`	reporter から情報待ち	具体質問に回答が来たら再評価
`ready-for-agent`	AFK agent が拾える	agent brief を投稿
`ready-for-human`	人間判断が必要	判断ポイント込みで brief 化
`wontfix`	対応しない	理由を残して閉じる

9 — Wayfinder

Situational on-ramp

/wayfinder は greenfield や巨大 feature など、1 session に収まらない霧向けの on-ramp。主経路の置き換えではない。地図は issue tracker 上の wayfinder:map と子チケット。産物は deliverable ではなく decisions。

概念	意味
Destination	地図の到達点。全セッションがここに向き直す
Map as index	決定の詳細はチケットにだけ置き、地図は gist + link
Not yet specified	スコープ内の霧。frontier が進むとチケット化する
Out of scope	destination 外。卒業しない
HITL / AFK	人間との対話が要るか（grilling / prototype）vs agent 単独（research）

霧が晴れたら /to-spec に合流してから /to-tickets → /implement。地図をそのまま /implement に投げるとリンクされた決定が崩れる。

選び方: 1 session で握れるなら /grill-with-docs。握れない霧なら /wayfinder。スコープがはっきりした feature に wayfinder は使わない。

10 — 設計レビュー

Deepening opportunities

/improve-codebase-architecture は、浅い module を深くする候補を探す。語彙は /codebase-design、ドメインモデルは /domain-modeling から借りる。目的は美しい抽象化ではなく、locality と leverage。

語彙	見るポイント	判断質問
`Module`	interface と implementation を持つ単位	削除すると複雑さは消えるか、caller に散るか
`Interface`	caller が知る必要のある契約	test surface として十分に安定しているか
`Seam`	振る舞いを差し替える場所 / テスト境界	adapter が2つ以上あり、現実の seam になっているか
`Depth`	小さな interface の背後にある大きな振る舞い	caller は少ない知識で大きな効果を得ているか

運用のコツ: 迷ったら /ask-matt。実装前は grill-with-docs、巨大な霧は wayfinder、ship は to-spec → to-tickets → implement → code-review、壊れたら diagnosing-bugs、調査は research、泥団子化したら improve-codebase-architecture。

11 — 参考リンク

Source references

GitHub: mattpocock/skills — Skills For Real Engineers
skills.sh: mattpocock/skills — npx skills@latest add mattpocock/skills
README.md — 目的、Quickstart、plugin 導線、4つの失敗モード、スキル一覧
CHANGELOG.md — v1.1.0 の rename / 統合 / wayfinder 昇格
.claude-plugin/plugin.json — Claude plugin として公開される 22 entries
.agents/invocation.md — user-invoked / model-invoked の定義と依存の書き方
.agents/adr/0002-ship-as-a-claude-code-plugin.md — plugin 配送の判断
skills/engineering/ask-matt/SKILL.md — idea → ship のルーターと on-ramp
skills/engineering/to-spec/SKILL.md — 会話を spec に発行
skills/engineering/to-tickets/SKILL.md — blocking edges 付き tickets / wide refactor
skills/engineering/wayfinder/SKILL.md — 巨大作業の決定地図
skills/engineering/implement/SKILL.md — spec / tickets から TDD で ship
skills/engineering/code-review/SKILL.md — Standards + Spec の二軸レビュー
skills/engineering/research/SKILL.md — background agent による primary-source 調査
skills/engineering/tdd/SKILL.md — red → green と seam / anti-patterns
skills/productivity/grilling/SKILL.md — facts vs decisions と確認ゲート
skills/productivity/writing-great-skills/SKILL.md — スキル執筆の参照（Negation / Negative Space 含む）
.agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md — hard / soft dependency の判断