AI 工程流程約束層
mattpocock/skills 是一組工程型 AI agent workflow，將功能從需求釐清推進至上線，涵蓋 PRD、issue 拆分、TDD 實作、review、diagnose 與架構整理；它不以單一 prompt 提供。Repo 自述採用 real engineering，區別於 vibe coding；這些 skill 是小型、可組合、可修改的 agent skills。
每個 skill 對應明確的工程動作，提供該動作的流程指示：
/grill-with-docs挑戰需求、對齊 domain language。/to-prd將對話與 codebase 理解合成 PRD。/to-issues將 PRD 拆成可獨立實作的 vertical slice。/tdd以 red-green-refactor 實作。/review沿 Standards 與 Spec 兩軸審查 diff。
技能透過 repo 內的 issue tracker 與 domain docs 串接；setup 會先設定這些位置。
各 skill 的設計固定採用釐清、規劃、實作、審查的順序。官方 README 也指出 agent 會加速 software entropy，因此需要定期用 /zoom-out 與 /improve-codebase-architecture 關注 system design。
grill-with-docs
to-prd
to-issues
tdd
review
diagnose
把它當成 AI 工程流程的約束層,不是 prompt library。正確順序是:釐清需求 → 寫 PRD → 拆 vertical issues → TDD 實作 → review → diagnose / architecture cleanup。
技能安裝與 repo setup
官方 quickstart 使用一行 npx 安裝。選擇要使用的 coding agent，並勾選 /setup-matt-pocock-skills。
# 官方 quickstart
npx skills@latest add mattpocock/skills安裝完成後，在你的 coding agent 內先跑一次 setup skill。它會設定 repo 的 issue tracker、triage labels 與 domain docs 位置，供後續 /to-prd、/to-issues、/tdd、/diagnose 等技能讀取。
/setup-matt-pocock-skills首次 setup 的規則設定
setup 時把 issue tracker、triage labels 與 domain doc 佈局一併指定，後續技能就有固定的讀寫位置。
/setup-matt-pocock-skills
This repo uses GitHub Issues.
Use these triage labels:
- needs-triage
- needs-info
- ready-for-agent
- ready-for-human
- wontfix
Use a single-context domain doc layout:
- CONTEXT.md at repo root
- ADRs in docs/adr/技能與工程動作
官方 reference 列出 10 個 engineering skills：
diagnose
grill-with-docs
triage
improve-codebase-architecture
setup-matt-pocock-skills
tdd
to-issues
to-prd
zoom-out
prototype
下列卡片加上工作流常用的 /review 與 /handoff，依工作階段分組。grill-with-docs、to-prd、to-issues、tdd、review 五個核心技能可完成一輪流程。
Setup · 01
/setup-matt-pocock-skills
repo 設定
設定 issue tracker、triage labels、domain docs 位置，供下游技能讀取。安裝後第一步。
Clarify · 02
/grill-with-docs
需求釐清
開始做功能前，挑戰需求、對齊 domain language、檢查現有 code 與文件。一次問一個問題，並更新 CONTEXT.md。
Plan · 03
/to-prd
轉 PRD
把目前對話與 codebase 理解合成 PRD，含 problem、solution、user stories、implementation/testing decisions、out of scope。不重新訪談。
Plan · 04
/to-issues
拆 vertical slice
把 PRD 拆成可獨立實作、可 demo 的端到端切片（tracer bullet），標 AFK / HITL 與相依順序。不做純 schema/API/UI 單層任務。
Build · 05
/tdd
TDD 實作
red-green-refactor。測 public interface 的 observable behavior，不測 implementation details。一次一個 behavior,vertical loop。
Debug · 06
/diagnose
系統性除錯
建 feedback loop → reproduce → minimise → hypothesise → instrument → fix → regression test。先建立可重現的 pass/fail signal，再修復。
Review · 07
/review
branch 審查
對固定點比較 diff，沿 Standards 與 Spec 兩軸檢查。報 blocking、non-blocking、missing tests、spec mismatch。
Understand · 08
/zoom-out
看系統全局
釐清某段 code 在整體系統中扮演的角色，適合接手陌生 codebase 時先建立全貌。
Architecture · 09
/improve-codebase-architecture
架構整理
找出 module interface 太淺、複雜度外漏、難維護的地方。對應 agent 寫太快後累積的 software entropy。
Handoff · 10
/handoff
任務交接
長任務中斷前，產生下一個 agent 可接手的 handoff doc，保留任務上下文。
Triage · 11
/triage
issue 分類
官方 engineering skills 之一。依 setup 設定的 triage labels 分類進來的 issue。
Prototype · 12
/prototype
原型探索
官方 engineering skills 之一。用於建立可丟棄的原型並驗證，在進入正式 PRD 流程前探索方向。
情境與技能對照
| 情境 | 不要這樣 | 正確用法 |
|---|---|---|
| 需求還很模糊 | 直接叫 agent 開工 | /grill-with-docs |
| 大功能 | 叫 agent 一次做完 | /to-prd → /to-issues → 每個 issue /tdd |
| Bug | 直接叫 agent 修 | /diagnose 先建立 repro loop |
| 測試 | 叫 agent 補 coverage | /tdd 測 observable behavior |
| Review | 叫 agent「看看有沒有問題」 | /review main，指定 fixed point |
| 架構變亂 | 叫 agent refactor all | /zoom-out → /improve-codebase-architecture |
三種情境與三條工作流
A. 新功能規劃
先 setup repo 規則，再用 grill-with-docs 把需求問清楚並寫入 CONTEXT.md / ADR，接著 to-prd 整理成 PRD,to-issues 拆成 thin vertical slice，每個 issue 用 tdd 實作，最後 review main 對比 main branch 檢查。
/setup-matt-pocock-skills
/grill-with-docs
/to-prd
/to-issues
/tdd
/review mainB. Bug 修復
先用 diagnose 建立可重現的 feedback loop，再用 tdd 加入 regression test 並修復，最後用 review main 確認既有行為。
診斷流程：feedback loop → reproduce → minimise → hypothesise → instrument → fix → regression-test。修復前需建立可自動執行的 pass/fail signal，避免直接猜測 bug。
/diagnose
/tdd
/review mainC. 架構整理
適合 agent 寫太快後 codebase 變亂的情況。先 zoom-out 建立系統全貌，再用 improve-codebase-architecture 找出 interface 太淺、複雜度外漏的地方，以 tdd 驗證改動，最後 review main。官方 README 指出 agent 會加速 software entropy，因此需要定期關注 system design。
/zoom-out
/improve-codebase-architecture
/tdd
/review main各階段的可複用 prompt
各階段範本可直接貼用，並替換方括號內容。/grill-with-docs 要求 agent 一次問一個問題、為各問題提供建議答案，並在必要時檢查 codebase；可從 codebase 取得的答案由 agent 查閱 code。
/grill-with-docs
I want to build [功能名稱].
Current goal:
[用 3-5 句描述你要做什麼]
Known constraints:
- [技術限制]
- [產品限制]
- [不能改的地方]
Please challenge the plan against the existing codebase, domain language, and ADRs.
Ask one question at a time.
For every question, provide your recommended answer.
If the answer can be found in the codebase, inspect the code instead of asking me./to-prd 將目前 conversation context 與 codebase understanding 合成 PRD，不重新訪談使用者。PRD 涵蓋：
problem
solution
user stories
implementation decisions
testing decisions
out of scope
/to-prd
Create a PRD from the current conversation and codebase context.
Requirements:
- Do not add features we did not discuss.
- Use existing domain language from CONTEXT.md.
- Prefer existing test seams.
- Include user stories, implementation decisions, testing decisions, out-of-scope items.
- Publish it to the configured issue tracker./to-issues
Break this PRD into independently implementable vertical slices.
Rules:
- Prefer many thin slices over few thick slices.
- Each slice must be demoable or verifiable on its own.
- Mark each slice as AFK or HITL.
- Show dependencies between slices.
- Use acceptance criteria.
- Do not create horizontal tasks like "build API", "build UI", "write tests"
unless they are part of a complete vertical slice./tdd 測試 public interface 的 observable behavior，不測 implementation details。流程採用 vertical red-green loop，每次完成一個 test 與對應 implementation，不分批寫完全部 test 後才開始實作。
/tdd
Implement issue #[issue-number] using strict TDD.
Rules:
- One behavior at a time.
- Write one failing test first.
- Implement only enough code to pass that test.
- Tests must verify public behavior, not implementation details.
- Do not mock internal collaborators unless unavoidable.
- After green, refactor only when tests pass.
- Run typecheck, lint, and tests before finishing./diagnose
Bug:
[描述錯誤]
Observed behavior:
[實際發生什麼]
Expected behavior:
[應該發生什麼]
Reproduction:
[步驟、command、URL、test、log]
Constraints:
- Do not guess before building a feedback loop.
- Create the smallest deterministic repro possible.
- Add a regression test after fixing./review 會把 diff 對固定點比較，沿 Standards 與 Spec 兩軸檢查，並參考 issue references、PRD/spec、repo coding standards、CONTEXT、ADR、config 等作為依據。
/review main
Review this branch against main.
Check two axes:
1. Standards: does the code follow this repo's documented standards?
2. Spec: does the implementation match the originating issue / PRD?
Report:
- Blocking issues
- Non-blocking issues
- Missing tests
- Spec mismatch
- Suggested fixes登入功能的需求釐清與 PR 流程
以下示範一個 email/password 登入功能，從 /grill-with-docs 釐清，經 /to-prd、/to-issues 拆解，再用 /tdd 實作第一個 issue，最後 /review main 收尾。
$ You › /grill-with-docs
I want to add email/password login to this app.
Known requirements:
- Users can sign in with email and password.
- Invalid credentials should show a safe generic error.
- Successful login redirects to dashboard.
- Reuse existing auth/session code if available.
- Do not add OAuth in this scope.
Ask one question at a time. Recommend an answer for each.
claude: Claude ›
hl: Q1 / 現有 session 用 cookie 還是 token?(我查到 src/auth/session.ts
hl: 已用 httpOnly cookie,建議沿用,不另開 token 路徑)
…釐清四個問題後,將術語與決策寫入 CONTEXT.md
$ You › /to-prd
Use existing auth terminology from CONTEXT.md.
Out of scope: OAuth, password reset, email verification.
ok: PRD: problem / solution / user stories / testing decisions / out-of-scope
$ You › /to-issues
Break the login PRD into vertical slices.
Each must include behavior, acceptance criteria, dependency order.
claude: Claude ›
#123 Login form happy path AFK 正確帳密 → 導向 dashboard
#124 Invalid credentials handling AFK 錯誤帳密 → generic error
#125 Session persistence check AFK 重新整理仍維持登入
#126 Auth copy / UX review HITL 人工確認錯誤訊息與 UX
$ You › /tdd
Implement issue #123 using strict red-green-refactor.
Start with the highest-level test seam available.
Do not implement invalid credential handling yet.
ok: typecheck ✓ lint ✓ tests ✓
$ You › /review main
Does this match #123? Are tests behavior-based?
Did we implement any out-of-scope auth features?
ok: Spec: matches #123 · no OAuth / reset leaked in
hl: Non-blocking: error copy 待 #126 HITL review
流程驗證項目
grill-with-docs 提問前讀取
src/auth/*，先查出 codebase 中已有的答案。to-issues 將登入拆成可獨立 demo 的 vertical slice，並標示 AFK 與 HITL。
tdd 每次實作一個 behavior，不提前實作 #124 的錯誤處理。
review 沿 Spec 軸確認未加入 out-of-scope 的 OAuth 功能。
六個技能的最小配置
最小可行配置
這 6 個技能可完成一輪工程流程。Debug 多的 repo 再加 /diagnose；大型 codebase 再加 /zoom-out、/improve-codebase-architecture、/handoff。
/setup-matt-pocock-skills
/grill-with-docs
/to-prd
/to-issues
/tdd
/review
# Debug 多的 repo 加
/diagnose
# 大型 codebase 加
/zoom-out /improve-codebase-architecture /handoff把它當成 AI 工程流程約束層,不是 prompt library。 釐清需求 → 寫 PRD → 拆 vertical issues → TDD 實作 → review → diagnose / architecture cleanup。