mattpocock/skills 完整教學

89,000+ 星的 AI 工程技能套件，把軟體工程實務轉化成可重複執行的 slash commands。

1. 專案定位

這個套件是什麼？

mattpocock/skills 是 Matt Pocock（Total TypeScript 作者）開源的 Claude Code skill 集合。與 GSD、BMAD、Spec-Kit 等「接管整個流程」的方案不同，這套 skills 刻意保持：

• 小：每個 skill 只做一件事
• 可組合：skills 之間無強依賴，可自由搭配
• 可客製化：你可以也應該 hack 這些 skills，讓它們符合你的工作方式
• 跨模型：適用 Claude Code、Codex、Cursor 等任何支援 slash commands 的工具

解決的 4 個核心問題

2. 安裝指南

2.1 官方推薦：skills.sh 安裝器（30 秒）

1npx skills@latest add mattpocock/skills

互動式選單會讓你選擇：

1. 要安裝哪些 skills
2. 安裝到哪個 coding agent（Claude Code / Codex / Cursor 等）

2.2 手動安裝（完全控制）

 1# 1. Clone repo
 2git clone https://github.com/mattpocock/skills ~/.config/mattpocock-skills
 3
 4# 2. 軟連結所有 active skills 到 ~/.claude/skills/
 5cd ~/.config/mattpocock-skills
 6bash scripts/link-skills.sh
 7# 輸出：linked diagnose -> .../skills/engineering/diagnose
 8
 9# 3. 驗證連結
10ls ~/.claude/skills/

2.3 初始化設定（必做一次）

1在 Claude Code 中執行：
2/setup-matt-pocock-skills

這個 skill 會問你：

• Issue tracker：GitHub Issues / Linear / 本地 .scratch/ markdown
• Triage 標籤：你的 issue 標籤命名規則
• 文件儲存位置：ADR、PRD 放在哪

完成後會在你的 repo 建立：

1docs/
2├── adr/                         # Architecture Decision Records
3└── agents/
4    └── triage-labels.md         # 標籤對應表
5CONTEXT.md                       # 領域語言詞彙表（初始可為空）

3. 核心架構解析

3.1 Skill 分類

1skills/
2├── engineering/   9 個 active skills（每日程式碼工作）
3├── productivity/  4 個 active skills（工作流工具）
4├── misc/          1 個 active skill（工具類）
5├── personal/      — 不對外推廣
6├── in-progress/   — 草稿，可搶先試用
7└── deprecated/    — 已停用（保留供參考）

3.2 SKILL.md 格式

每個 skill 的入口是 SKILL.md，頂部有 YAML frontmatter：

1---
2name: grill-me
3description: "觸發條件：說明 Claude 什麼時候應自動執行此 skill"
4argument-hint: "（選用）提示使用者可傳入的參數"
5disable-model-invocation: true  # 若此 skill 是 prompt injection，設此旗標
6---

3.3 CONTEXT.md 的角色

CONTEXT.md 是共享語言詞彙表，不是 規格文件或備忘錄。 只記錄：術語定義、要避免的同義詞、術語之間的關係。

Example:

1## Language
2
3**Issue tracker**: 存放 issues 的工具（GitHub Issues、Linear、本地 .scratch/）。
4_避免使用_: backlog manager, backlog backend
5
6**Issue**: Issue tracker 中一個被追蹤的工作單位。
7_避免使用_: ticket（除非外部系統本身用這個詞）

當 Claude 持有這份詞彙表，它能用更短的語言表達複雜概念，節省 token，命名也更一致。

4. Skills 詳細用法

4.1 Engineering Skills（每日程式碼工作）

/grill-with-docs ⭐ 最強推薦

觸發時機：任何新功能或重大改動前，先跑一次。

做了什麼：

1. 對你的計畫進行「無情訊問」，逐一確認每個決策分支
2. 偵測你用的術語是否與 CONTEXT.md 衝突，立即澄清
3. 檢查程式碼與你說的是否一致
4. 達成共識時，即時更新 CONTEXT.md
5. 若決策符合 ADR 條件（難以逆轉、令人意外、有真實取捨），提供建立 ADR

1使用方式：
2/grill-with-docs
3
4然後描述你要做的事，Claude 開始逐一問問題。

/tdd

觸發時機：實作任何功能或修 bug。

核心原則：

• 垂直切片（Vertical Slices）：一個測試 → 一個實作 → 重複
• 禁止：先寫全部測試再寫全部實作（水平切片）
• 測試驗證行為，不驗證實作細節

1使用方式：
2/tdd
3
4描述你要建的功能，Claude 會：
51. 設計 public interface
62. 一次寫一個 failing test（RED）
73. 最小實作讓測試通過（GREEN）
84. 重構（REFACTOR）

/diagnose

觸發時機：遇到難以重現的 bug 或效能回歸。

6 個階段（不可跳過）：

1. 建立回饋迴圈（最重要！有確定性回饋信號才能繼續）
2. 重現：確認你複現的是使用者說的那個 bug，不是別的
3. 最小化：找到最小重現路徑
4. 假設：列出有序假設清單（最可能 → 最不可能）
5. 儀器化：針對最高順位假設加 logging / assertions
6. 修復 + 回歸測試：修完補一個回歸測試

/to-prd

把目前對話脈絡自動合成成 PRD（產品需求文件），並以 GitHub issue 提交。 不做訪談，直接從你們已經討論的內容合成。

1/to-prd

/to-issues

把 PRD 或計畫拆解成可獨立認領的 GitHub issues（垂直切片）。

1/to-issues

/triage

透過狀態機（triage roles）處理 issues，依你在 setup 時定義的標籤流動。

/improve-codebase-architecture

深度分析 codebase，找出「模組深化機會」（shallow → deep modules）， 建議能提升可測試性與 AI 可導航性的重構。建議每幾天跑一次。

/zoom-out

讓 Claude 往上一層抽象，給你一張「相關模組地圖」，用 CONTEXT.md 的詞彙說明。

/prototype

建立拋棄式原型：

• 狀態/業務邏輯問題 → 可執行的 terminal app
• UI 問題 → 同一個 route 下切換的多個激進設計

/setup-matt-pocock-skills

初始化每個 repo 的設定。第一次使用前必跑。

4.2 Productivity Skills（非程式碼工作流）

/grill-me

/grill-with-docs 的非程式碼版本，純粹做決策訊問，不更新 CONTEXT.md / ADR。

1/grill-me
2然後描述你的計畫。

/caveman

超壓縮溝通模式，刪去所有填充詞但保留技術精確性。 自稱可減少約 75% token 用量。

/handoff

把目前對話壓縮成 handoff 文件，讓另一個 agent（或下一個 session）接續工作。

1# 內部執行
2mktemp -t handoff-XXXXXX.md  → 存到此路徑

/write-a-skill

引導你用標準結構建立新 skill，含漸進式揭露設計與打包資源。

4.3 Misc Skills

/git-guardrails-claude-code

建立 Claude Code hooks，攔截危險的 git 操作（push、reset –hard、clean 等）。

5. 應用場景

場景 A：新功能開發標準流程

11. /grill-with-docs    → 澄清需求、建立共識、更新 CONTEXT.md
22. /to-prd             → 合成 PRD，提交為 issue
33. /to-issues          → 把 PRD 拆成可認領的 issues
44. /tdd                → 逐一實作（RED → GREEN → REFACTOR）

場景 B：除錯困難 bug

11. /diagnose           → 建立回饋迴圈 → 最小化 → 假設清單 → 修復
22. /tdd                → 補回歸測試

場景 C：維護架構健康

1每幾天執行一次：
2/improve-codebase-architecture  → 找到 shallow modules → 提出深化建議

場景 D：跨 session 交接

1/handoff [下一個 session 要做什麼]  → 生成 handoff.md → 新 session 直接讀

6. 資安掃描報告

6.1 掃描摘要

整體評級：🟢 低風險

本套件為純文字 skill 集合（SKILL.md 為 markdown prompt），不含任何可執行程式碼邏輯，幾乎零攻擊面。

6.2 發現項目

6.3 未發現項目

• ❌ 無 eval / exec / os.system 等程式碼注入模式
• ❌ 無 hardcoded secrets / tokens / API keys
• ❌ 無 curl | sh 管道下載模式（安裝器用 npx，不是 curl | sh）
• ❌ 無對外網路請求（scripts/ 全為本機操作）
• ❌ 無 chmod 777 / sudo 等特權提升

6.4 建議

1. 安裝前確認 npx skills@latest 對應的 npm 套件為官方套件（目前為 https://skills.sh）
2. 若在受管環境（CI/CD、公司電腦），考慮用手動 clone 方式取代 npx 安裝
3. 安裝的 skills 為 markdown prompt，不會直接執行任何 shell 命令——安全邊界由 Claude Code 的工具使用權限控制

7. FAQ

Q: 這套 skills 和 GSD / BMAD 有什麼不同？
A: GSD / BMAD 試圖擁有整個開發流程，這套 skills 則是小型可組合工具。你決定何時用哪個 skill，保持完整控制權。

Q: 可以只用其中幾個 skill 嗎？
A: 可以。skills 間沒有強依賴。最推薦入門順序：/grill-with-docs → /tdd → /diagnose。

Q: CONTEXT.md 是必須的嗎？
A: 不是，但強烈建議。沒有它，agent 每次都需要重新學術語，浪費 token 也容易不一致。

Q: 這些 skills 只能用在 Claude Code 嗎？
A: 不是，設計上支援任何 agent 工具。安裝器（skills.sh）支援多種目標（Codex、Cursor 等）。

Q: 可以修改這些 skills 嗎？
A: 強烈建議！README 明確說「Hack around with them. Make them your own.」MIT 授權。

Q: deprecated/ 裡的 skills 為何被淘汰？
A: 功能已被整合進新的 skills（例如 grill-with-docs 涵蓋了舊版的 design-an-interface），或實踐上發現更好的方法。仍可參考。

8. 進階技巧

8.1 自訂 CONTEXT.md

成功的 CONTEXT.md 只存放術語，不存放 spec。格式：

 1## Language
 2
 3**[術語]**: [定義一句話]
 4_避免使用_: [同義詞列表]
 5
 6## Relationships
 7
 8- [術語A] 對應多個 [術語B]
 9
10## Flagged ambiguities
11
12- "[舊術語]" 曾被用來指 X 和 Y — 已解決：現在用 [正確術語]

8.2 建立自己的 Skills

用 /write-a-skill 引導，遵循以下原則：

• SKILL.md frontmatter 必須有 name 和 description
• description 決定 Claude 何時自動觸發這個 skill
• 用漸進式揭露：基本行為在 SKILL.md，細節在 details/ 或其他 md 檔

8.3 Skill 組合進現有 repo

1# 不 clone 全部，只連結你要的 skills
2mkdir -p ~/.claude/skills
3ln -sfn /path/to/mattpocock-skills/skills/engineering/grill-with-docs \
4  ~/.claude/skills/grill-with-docs

8.4 /caveman 模式省 token

在長對話後半段切換：

1/caveman

Claude 會切換成超壓縮輸出，只留技術核心，省去大量重複說明。

9. 整合進其他工作流

9.1 與 paper-qa-lite 整合

若你在研究技術主題，可以：

1. paper search: mattpocock skills agent workflow 蒐集相關論文
2. pq: 用本地 RAG 問「這些 skills 和學術 prompt engineering 有何異同？」

9.2 與 graphify 整合

1# 建立知識圖，了解 skills 間的相互依賴
2graphify analyze /tmp/skills-mattpocock

9.3 搭配 quarkdown 做內部分享

1qd from: inbox/2026-05-18-tutorial-skills.md as report

輸出 HTML/PDF 適合 team review。

9.4 搭配 NotebookLM 做深度問答

1nlm: inbox/2026-05-18-tutorial-skills.md

把全套 skills 文件加入 NotebookLM 做 AI 問答。

10. 重點摘要 Checklist

使用這套 skills 前，確認以下：

• 執行過 /setup-matt-pocock-skills（一次性初始化）
• repo 有 CONTEXT.md（可為空，第一次 /grill-with-docs 後會填入）
• 了解 4 個核心問題（溝通 / 詞彙 / 回饋 / 架構）和對應 skills
• 新功能前先跑 /grill-with-docs
• 實作時用 /tdd（垂直切片，不是水平切片）
• Bug 時用 /diagnose（先建回饋迴圈，再假設）
• 每幾天跑一次 /improve-codebase-architecture

11. 進一步閱讀

• 官方 README：github.com/mattpocock/skills
• Newsletter（~60,000 subscribers）：aihero.dev/s/skills-newsletter
• skills.sh 安裝平台：skills.sh/mattpocock/skills
• 參考書目（README 引用）：
  • The Pragmatic Programmer — David Thomas & Andrew Hunt
  • Domain-Driven Design — Eric Evans
  • A Philosophy of Software Design — John Ousterhout
  • Extreme Programming Explained — Kent Beck