Matt Pocock Skills 使用指南与实践

Matt Pocock（TypeScript 布道者、Total TypeScript 创始人）把自己在 Claude Code 里每天在用的工程流程开源成了 mattpocock/skills。它把资深工程师的工作习惯封装成可被 AI 代理执行的指令，让 AI 按既定流程工作，而不是自由发挥导致代码质量失控。

截至 2026 年 9 月，该项目在 GitHub 星标已突破 26 万（增长极快，以官方仓库实时数据为准），整套技能采用 MIT 协议，纯文件形式、不绑定平台，兼容 Claude Code、Cursor、Codex、Copilot、Amp、Cline、Gemini CLI 等主流编码代理（官方称 works with any agent）。

截图来源：github.com/mattpocock/skills，实时星数请以页面为准。

它解决什么问题

AI 编码代理的能力上限早已不是问题，真正的短板是缺少流程约束——让它自己猜，它就写出「看起来合理、实则悄悄腐蚀代码库」的代码。Matt 给出的三条核心判断：

• 问题：代理的表现取决于你给它的流程。流程缺失时，它写出 plausibly 的代码，代码库随之慢慢腐烂。
• 解法：一个 Skill 只编码一种好习惯（盘问方案、写规格、审 diff），代理每次都按同一套方式执行。
• 复利：Skill 首尾相接——上一个的输出是下一个的输入（对话 → Spec → 工单 → 代码 → 审查）。每调优一个环节，整条链路都变好。

安装

安装只需一条 npx 命令，Claude Code 还可直接装成官方插件。具体命令、Windows Symlink 注意、Codex 绑定方式等请直接看官方文档，更新最快也最准：

• 官方站：aihero.dev/skills
• 源码仓库：github.com/mattpocock/skills

项目初始化与知识库防污染架构（核心）

每个独立代码仓库只需执行一次 /setup-matt-pocock-skills，它会在项目里建立如下结构：

your-repo/
├─ CLAUDE.md                 ← 追加 ## Agent skills 区块
└─ docs/
   └─ agents/                ← 新增目录
      ├─ issue-tracker.md    ← 工单跟踪配置（GitHub/GitLab Issues 或本地 Markdown）
      ├─ triage-labels.md    ← 分诊标签定义
      └─ domain.md           ← 领域术语初稿

这套体系最值钱的地方，是用「防污染」机制把业务知识沉淀下来，而不是让决策散落在聊天记录里。三道机制：

1. 懒加载（Lazy Creation）：初始化不强行生成空文件。只有当你第一次用 /grill-with-docs 提炼出业务术语时，才会创建 CONTEXT.md 或 docs/adr/。所以跑完 setup 看不到 CONTEXT.md 是正常的。
2. 统一领域字典 CONTEXT.md：只存跨需求共享的业务名词与不变量（例如「一根 K 线代表一个交易周期内的开盘/收盘/最高/最低价」），不存代码细节。
3. Multi-Context 物理隔离：大型项目用 CONTEXT-MAP.md 划分子系统（如 src/ordering/CONTEXT.md 与 src/billing/CONTEXT.md 各自隔离），避免一个巨型词典变成垃圾堆。

架构决策则落到 docs/adr/（Architecture Decision Records），违反 ADR 时必须显式提示，不能静默覆盖。

25 个技能全景（6 大类）

所有技能按使用时机分为 6 大类。多数人会从「主工作流」开始。其中 /to-spec、/to-tickets、/triage 的产出位置，由初始化时选定的工单存储模式（远程 GitHub/GitLab 或本地 Markdown）决定，详见上文「工单存哪：远程 vs 本地模式」。

01 入门启动类（Getting Started）

• /setup-matt-pocock-skills — 给一个仓库做一次性初始化，让其他技能知道项目怎么运作。
• /ask-matt — 内置导航器：描述你当前的处境，它推荐该用哪个技能。

02 主工作流（The Main Flow）

从想法到上线的主干，按顺序串联。

• /grill-with-docs — 就一个方案接受结构化访谈，把决策和领域术语记录进文档（更新 CONTEXT.md、生成 ADR）。
• /to-spec — 把已达成共识的对话，转成正式、可执行的书面规格（Spec）。（前身是 /to-prd；产出位置随初始化选定的存储模式走，远程/本地皆可）
• /to-tickets — 把完整 Spec 拆成粒度足够小、代理可直接独立开发的工单。（由 /to-plan 与 /to-issues 合并而来；远程模式下经 gh/glab 真实建 issue，本地模式下落 .scratch/ 目录） 项目如果在github上，并且安装了gh，该技能会自动连接github创建相关tickets。具体下文再介绍工单存哪的两种模式。
• /implement — 按 Spec 以测试优先的方式把代码实现出来，产出源码 + 测试 + 一次提交。
• /code-review — 对照团队编码规范与原始 Spec 审查 diff，内置 Fowler 十二条代码坏味道基线。

03 探索塑形类（Shaping）

针对开放性问题做探索并产出决策，反哺主工作流。

• /wayfinder — 把大型、方向模糊的工作梳理成「决策地图」（decision ticket），逐个明确决策点与优先级。
• /prototype — 用代码回答一个设计问题，验证完即删。（v1.2 起改为产出单个可分享 HTML，并作为「主要来源」保留在分支上）
• /research — 从一手 / 原始来源检索，输出带引用来源的调研结论。

04 维护运维类（Upkeep）

保障代码库与工单列表健康，持续为主流程产生可执行工作项。

• /improve-codebase-architecture — 自动识别值得重构的模块，输出可视化分析报告。
• /diagnosing-bugs — 从一个可复现的失败用例出发，逐步推导定位根因。（v1.2.3 新增 Redact 章节，要求先对密钥脱敏）
• /resolving-merge-conflicts — 处理合并（Merge）或变基（Rebase）冲突，逐 hunk 引导解决。
• /triage — 把零散的原始 Issue 分类、分级、整理成可直接承接的标准工作项。（同样随初始化选定的存储模式，产出落远程 issue 或本地 .md）
• /wizard — 生成一步步的引导脚本，指导人工完成环境搭建、配置等操作。

05 效率技能（Productivity Skills）

面向人的工作流，不直接生产代码。

• /grill-me — 在投入资源落地一个想法前，先和代理互相质询、对齐思路。
• /handoff — 把长会话的上下文、进度、结论整理成标准文档，让另一个代理无缝接手。
• /to-questionnaire — 把开放性问题转成结构化问卷文档，发给他人填写收集信息。
• /teach — 把技术主题拆成多节循序渐进的会话，跨多个 session 系统学习。
• /wait-what — 代理输出过于晦涩时，让它用大白话重说一遍。（v1.2 新增，专治模型啰嗦）
• /writing-for-agents — 当你自己要写 Skill 或写给代理看的文档时，掌握面向代理的写作规范。（前身 /writing-great-skills，v1.2 重构更名）

06 参考基准类（Reference Skills）

底层可复用能力层，通常被其他技能调用，也可单独作规范参考。

• /codebase-design — 设计深度模块时的统一架构设计词汇表。
• /domain-modeling — 统一项目内核心术语的定义并书面沉淀。
• /grilling — 通用方案压力测试方法，是 /grill-with-docs 等的底层逻辑。
• /tdd — 测试驱动开发的完整规则集，定义「红—绿—重构」循环规范。

典型实战工作流

• 普通功能：/grill-with-docs → /to-spec → /implement → /code-review。多工单时一次只 implement 一个（按 Blocked by 顺序），保垂直切片。
• 数值 / 算法类：强制走 /tdd，先写 failing test，红→绿多轮交替（如 ATR 指标计算）。核心业务红线：数值计算、交易逻辑必须 TDD。
• 原型探索：/grill-with-docs → /prototype，验证完即弃（或保留 HTML）。
• 疑难 Bug：/diagnosing-bugs，从复现失败开始。
• 大型拆解：/to-tickets + /triage 把大需求拆成可执行工单。
• 跨会话交接：/handoff 导出摘要到临时目录 → 关窗口 → 新窗口读取继续，彻底切断上下文干扰。

工单存哪：远程 vs 本地模式

注意下面的 /to-spec、/to-tickets、/triage 三个命令都标注了「远程」和「本地」两种产出形式——这源于初始化时你做的一个选择。

跑 /setup-matt-pocock-skills 时，它会问你一个问题：

「这个项目的工单（issue / spec / ticket）存到哪？」

可选答案有四类，你选的那一项会被写进 docs/agents/issue-tracker.md，之后所有技能都读这个配置来决定「发到哪」：

• GitHub Issues（远程模式） —— 用 gh CLI 操作 GitHub Issues。
• GitLab Issues（远程模式） —— 用 glab CLI 操作 GitLab Issues。
• Local Markdown（本地模式） —— 每个 issue 就是仓库里的一个 .md 文件，不依赖任何外部服务。
• Other（Jira / Linear / 飞书等） —— 自己描述工作流，让技能尽量对齐。

两种模式下 /to-tickets 产出对比

远程模式（选了 GitHub）：调用 gh issue create，在你的 GitHub 仓库真实创建多个 issue。产出是网页上能看到的 issue，不落本地文件：

GitHub 上多出这些新 issue:
├─ #42  [csv-import] Parse CSV rows into K-line records
├─ #43  [csv-import] Validate field types and ranges       (blocked by #42)
├─ #44  [csv-import] Upsert batch with duplicate handling  (blocked by #43)
└─ #45  [csv-import] Import summary logger                 (blocked by #42)

本地模式（选了 Local Markdown）：在仓库里新建目录，一个 ticket 一个 .md 文件，全部落地在磁盘上：

.scratch/csv-import/               ← <feature-slug>，以特性名命名
├─ spec.md                         ← /to-spec 的产出放这里
└─ issues/                         ← 一堆 ticket 文件
   ├─ 01-parse-csv-rows.md
   ├─ 02-validate-fields.md
   ├─ 03-upsert-with-dedup.md
   └─ 04-import-summary-logger.md

每个 issue 文件内部长这样：

# Parse CSV rows into K-line records
Status: ready-for-agent
Blocked by:

## Description
...ticket 内容...

## Comments
...后续讨论追加到这里...

怎么选

场景	推荐模式
团队协作、有 GitHub/GitLab 仓库、希望 issue 状态和讨论对所有人可见	GitHub / GitLab 远程模式
个人项目 / 不想开外部账号 / 想让 issue 跟代码一起进 Git 版本控制	本地模式
公司统一用 Jira / Linear / 飞书等	Other —— 初始化时详细描述工作流，skills 会尽力对齐

💡 无论选哪种模式，/handoff、/improve-codebase-architecture 生成的临时文件都始终放在 OS 临时目录，不受这里的模式选择影响——那是「会话性产出」，不是「工单」。

团队协作规范建议

1. 一需求一窗口：避免 Token / 上下文污染。
2. 词汇统一：严格遵守 CONTEXT.md 术语，不擅自造词。
3. 核心业务红线：数值计算、交易逻辑必须 /tdd。
4. 初始化规范：新仓库必跑 /setup-matt-pocock-skills。
5. 冲突显性化：违反 ADR 必须提示，禁止静默覆盖。
6. 改动前先 Plan：改代码前切 Plan Mode 人工 review（Claude Code 用 Shift+Tab）。

常见问题（FAQ）

• Q：CONTEXT.md 会不会变成垃圾堆？ 不会。靠职责分离（业务词入 CONTEXT.md、架构决策入 ADR）、提纯更新、物理隔离和「新窗口」四重机制保证。
• Q：跑完 setup 没看到 CONTEXT.md？ 正常，遵循懒加载，首次用 /grill-with-docs 提炼术语时才生成。
• Q：命令没触发？ 检查是否安装成功、客户端是否加载到该技能、是否跑过 setup。
• Q：Codex 里怎么调？ 去掉斜杠，直接 grill-with-docs。
• Q：首选哪种安装模式？ Symlink 模式，便于全局统一更新。

延伸资源

• 官方站与技能详情：aihero.dev/skills
• 源码仓库：github.com/mattpocock/skills（MIT）
• 社区简体中文本地化：vinvcn/mattpocock-skills-zh-CN