Matt Pocock Skills最佳实践

mattpocock/skills 是由 TypeScript 专家 Matt Pocock 开源的一套面向 AI 编码助手（AI Coding Agents） 的标准化工程技能集（Agent Skills）。

该技能集旨在摒弃盲目代码生成的“Vibe Coding”模式，为 AI Agent 引入工程化约束与最佳实践，提供涵盖需求访谈、技术规格定义、测试驱动开发（TDD）、缺陷诊断及 GitHub Issue 自动化管理的全流程标准规范。

核心特性

• 知识库防污染沉淀：通过严格的领域字典（Glossary）与多上下文映射，实现跨需求的业务概念统一，同时隔离代码细节。
• Issue 跟踪集成：原生集成 GitHub Issues（依赖 gh CLI），实现自动创建与标签状态流转。
• 多 Agent 跨平台兼容：完美兼容 Claude Code、Codex CLI、Cursor、Cline 等支持 Agent Skills 规范的客户端。

2. 环境前置要求

在正式配置前，请确保本地开发环境满足以下依赖条件：

1. Node.js 运行环境：建议版本 ≥ 18.0.0（用于通过 npx 执行 Agent Skills 安装程序）。
2. GitHub CLI 工具（可选，使用工单功能必选）：安装 GitHub CLI (gh) 并完成身份认证。

1
2
3
4
5

# 检查登录状态
gh auth status

# 未登录时执行交互式登录
gh auth login

3. 安装与配置步骤

用管理员权限打开 PowerShell 执行：

1

npx skills@latest add mattpocock/skills

在交互式选项中建议选择：

1

> Symlink (Recommended)

安装后技能文件默认存储于用户家目录下的 .agents 路径

1
2

C:\Users\<Your-Username>\.agents\skills\   # Windows
~/.agents/skills/                          # macOS/Linux

技能更新与卸载

1
2
3
4
5

# 拉取并更新技能至最新版
npx skills@latest update mattpocock/skills

# 卸载技能
npx skills@latest remove mattpocock/skills

项目初始化与知识库隔离架构【核心】

规则：每一个独立的代码仓库在引入该技能集时，仅需且必须执行一次 /setup-matt-pocock-skills 执行初始化后,AI Agent 会在项目根目录与 docs/agents/ 建立标准配置。 Before(裸仓库)→ After(跑完 /setup-matt-pocock-skills):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Before                              # After
StockAnalyzer/                        StockAnalyzer/
├─ src/                               ├─ src/
├─ package.json                       ├─ package.json
└─ README.md                          ├─ README.md
                                      ├─ CLAUDE.md                 ← 新增(或追加 ## Agent skills 区块)
                                      └─ docs/
                                         └─ agents/                ← 新增目录
                                            ├─ issue-tracker.md    ← 新增
                                            ├─ triage-labels.md    ← 新增(仅 triage 已安装时)
                                            └─ domain.md           ← 新增

防污染机制与 Multi-Context 实现路径

很多开发者担心：“连续开发多个需求后，CONTEXT.md 会不会变成充斥着乱七八糟代码细节的污染源？” 答案是：绝对不会。 框架通过以下三种机制保障知识库的高纯度：

###1. 懒加载（Lazy Creation） 初始化完成后不会强制生成空文件。只有当你第一次调用 /grill-with-docs 且真正收炼出明确的领域术语或业务约束时，Agent 才会创建 CONTEXT.md 或 docs/adr/。 具体示例: 假设你第一次跑 /grill-with-docs 澄清"K 线数据导入"需求,拷问过程中定义了「K 线」「日线」「预告开播」这些术语——AI 会自动生成:

1
2
3
4
5
6

StockAnalyzer/
├─ CONTEXT.md                     ← 新增,内容如下
└─ docs/
   ├─ agents/ (略)
   └─ adr/                         ← 新增(如果有架构决策)
      └─ 0001-csv-import-format.md ← 新增(仅当出现"难以逆转 + 需要理由 + 有真实取舍"三要素时)

CONTEXT.md 样例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# StockAnalyzer 领域词典

## K 线 (K-Line)
一根 K 线代表一个交易周期(默认日线)内的四个价格:开盘、收盘、最高、最低。
日线以自然日切分。

## 预告开播 vs 真实开播
- 预告开播:直播间预设的开播时间点(数据配置)
- 真实开播:主播实际推流的时刻
业务判断"是否开播"时需明确指哪一种。

📌 关键: CONTEXT.md 只存业务词汇与规则约束,不存代码/接口/实现细节。ADR 只在"难以逆转、需要写下理由、有真实取舍"三个条件全部满足时才生成——不是每次都产。

2. 统一领域字典（Use the Glossary’s Vocabulary）

CONTEXT.md 存放的是跨需求共享的业务名词与不变量（例如定义什么叫“K 线”、什么叫“最大回撤算法”），而非特定需求的实现细节。AI 在后续任何开发中，都必须遵守该字典词汇，防止用词漂移（Vocabulary Drift）。

5. 核心命令清单 & 使用规范

🧭 万能导航：如果不确定当前场景该使用哪个技能，输入 /ask-matt 并描述你的诉求，Agent 会自动为你推荐最优的技能工作流。

💡 速记原则:

• 动代码的:/implement、/tdd、/prototype、/resolving-merge-conflicts
• 写文档到仓库的:/grill-with-docs(领域词典)、/research(调研笔记)
• 上传到工单系统的:/to-spec、/to-tickets、/triage
• 只在对话/临时目录的:/grilling、/code-review、/diagnosing-bugs、/ask-matt、/handoff、/improve-codebase-architecture

📌 补充说明:关于命令表里的"远程 / 本地"

表格里 /to-spec、/to-tickets、/triage 三个命令都出现了 “远程” vs “本地” 两种产出形式。这是因为 skills 允许你选择"issue 存哪里"——跑 /setup-matt-pocock-skills 初始化时会问你:

“这个项目的工单(issue / spec / ticket)存到哪?”

• GitHub Issues(远程模式)—— 用 gh CLI 操作 GitHub Issues
• GitLab Issues(远程模式)—— 用 glab CLI 操作 GitLab Issues
• Local Markdown(本地模式)—— 每个 issue 就是仓库里的一个 .md 文件,不依赖外部服务
• Other(Jira / Linear 等)—— 自己描述工作流

你选的答案会写进 docs/agents/issue-tracker.md,后续所有 skills 都读这个配置来决定"发到哪"。

怎么选?

6. 典型场景实战工作流

场景 1:普通业务功能开发(数据导入 / 后台接口)

推荐链路: /grill-with-docs → /to-spec → /implement → /code-review

每步的输入与产出对比:

1
2
3

/grill-with-docs
开发 K 线历史数据导入模块:支持从 CSV 文件读取日线数据,校验时间、开盘价、收盘价、成交量字段,
存入数据库;重复日期数据自动覆盖,输出导入成功条数与异常日志。

产出: 若过程中出现新术语,自动在根目录新增/更新:

1
2

+ CONTEXT.md         (新增/追加"K 线""日线""导入批次"等术语定义)
+ docs/adr/0001-csv-import-idempotency.md  (仅当决策"重复日期覆盖策略"值得记录时)

1

/to-spec

产出: 一份 spec 发布到 issue tracker:

1
2

GitHub 模式:  https://github.com/<你>/<repo>/issues/42  ← 新 issue,带 ready-for-agent 标签
本地模式:     + .scratch/csv-import/spec.md

产出: 拆分成多个可追踪的 ticket:

1
2
3
4
5
6
7
8

GitHub 模式:  多个 issue (每个 ticket 一个),标注 blocking 关系
本地模式:     .scratch/csv-import/
              ├─ spec.md
              └─ issues/
                 + 01-parse-csv-rows.md
                 + 02-validate-fields.md      (Blocked by: 01)
                 + 03-upsert-with-dedup.md    (Blocked by: 02)
                 + 04-summary-logger.md       (Blocked by: 01)

1
2
3

Shift+Tab   (切换到 Plan Mode)
/implement #01
按 01-parse-csv-rows 这个 ticket 实现。

产出: 真正动源代码:

1
2
3
4

+ src/importer/csv-parser.ts         (新增)
+ src/importer/csv-parser.test.ts    (新增)
~ src/importer/index.ts              (修改,挂载新解析器)
🔀 git commit: "feat(importer): CSV parser for K-line data"

1

/code-review

产出: 对话里输出评审报告(不写文件);发现的问题若需修复,会走另一个 commit。

场景 2:量化核心计算逻辑(指标 / 策略 / 回测)

⚠️ 强制规范: 涉及核心数值计算、资产结算等逻辑,必须强制走 /tdd 流程,先写 Failing Test 再写实现。 推荐链路: /grill-with-docs → /to-spec → /tdd

1
2
3

/grill-with-docs
实现 ATR(平均真实波幅)指标计算:输入 K 线序列,周期默认 14;严格遵循标准 ATR 算法,
兼容数据不足周期的异常场景;输出每条 K 线对应的 ATR 计算结果。

产出: 若沉淀了"ATR"“真实波幅"等术语,更新 CONTEXT.md。

1

/to-spec

产出: 一条 spec issue(含 seams 定义、user stories、testing decisions),用于指导后续 TDD 的测试点位。

1

/tdd

产出模式与 /implement 根本不同——是"红→绿"多轮交替:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

─ 循环 1 ─ 覆盖"标准周期 14 的正常场景"
+ src/indicators/atr.test.ts   (只写这一个 failing test,先跑一次确认红)
+ src/indicators/atr.ts        (最小实现让这个 test 变绿)

─ 循环 2 ─ 覆盖"数据不足周期的边界"
~ src/indicators/atr.test.ts   (追加一个 failing test)
~ src/indicators/atr.ts        (改实现让新 test 也绿,不破坏旧 test)

─ 循环 3 ─ 覆盖"输入为空数组"
~ src/indicators/atr.test.ts   (再追加)
~ src/indicators/atr.ts        (再改)

...(继续直到所有 seam 覆盖)

🔀 git commit: 通常一个循环一次小 commit,或最终一次汇总 commit(由项目规范定)

关键差异:

• /implement:一次改到位、结束跑全量测试
• /tdd:先写红色测试 → 只写让它变绿的最少代码 → 再写下一个红色测试——每一步都必须先看到测试失败(避免"测试写完就绿"的假象)

📌 为什么核心业务红线要走 TDD: 数值计算的 bug 常常"看起来对但边界错”(如漏掉 0/负数/精度)。红→绿循环强迫你先想清楚该 pass 什么、该 fail 什么——这个思考本身就是最好的边界防护。

场景 3：算法验证与原型探索

推荐链路：/grill-with-docs → /prototype

1
2

/grill-with-docs
验证 5/20 日均线交叉策略：基于内存中的 K 线数据模拟回测，暂不接入数据库，统计总收益率与最大回撤。

1

/prototype

场景 4：复杂缺陷定位与排查（Bug Fixing）

1
2

/diagnosing-bugs
回测模块的最大回撤计算结果异常：人工核算为 12.5%，程序实际输出为 18.2%，请协助定位根本原因并补充回归测试用例。

场景 5：大型需求拆解与工单流转（团队协作）

1
2

/grill-with-docs
开发策略回测后台：包含新建策略、选择数据区间、执行回测、可视化收益指标展示及导出回测报告。

1

/to-spec

1
2

/to-tickets
Agent 将自动读取 docs/agents/issue-tracker.md 并在 GitHub 创建对应的 Issues。

1

/triage

场景 6:跨需求平滑交接与上下文清理(防止对话污染)

开发完一个需求准备换到下一个需求时:

1. 在当前对话框输入 /handoff,导出当前需求的成果总结。
   • 产出位置: OS 临时目录(不污染工作区)。Windows 通常在 %TEMP%\ 下,macOS/Linux 在 $TMPDIR/ 或 /tmp/ 下。文件名类似 handoff-<时间戳>.md
   • 产出内容: 已完成的部分、进行中的状态、下一步建议动作、推荐的 skills
2. 直接关闭当前对话窗口,新建一个干净的窗口。
3. 新窗口第一句话把 handoff 文件路径丢给 AI(比如"读一下 C:\Users\<Your-Username>\AppData\Local\Temp\handoff-20260807-153000.md,继续上次的工作")。
4. 新窗口中的 AI 会重新读取纯净的领域 Context + handoff 摘要,不会受到上一个需求繁杂调试对话的干扰。

9. 团队开发规范约定

1. 一需求一窗口：每个需求开发完毕并 Commit 后，必须开启新的 AI 会话窗口，避免历史对话 Token 污染。
2. 词汇统一原则：AI 产生的任何测试名、函数名与 Issue 标题，必须严格遵守 CONTEXT.md 定义的领域术语。
3. 核心业务红线：涉及核心数值计算、交易逻辑、资金安全的代码，必须采用 /tdd 模式开发，不允许直接使用 /implement 跳过测试。
4. 初始化规范：任何新项目或新拉取的仓库，在接入 AI 协同前必须运行一次 /setup-matt-pocock-skills。
5. 冲突显性化：如果新的实现违反了已有的 ADR 决策，Agent 必须显式提示（如 Contradicts ADR-0007...），严禁静默覆盖。
6. Plan Mode 优先(Claude Code 使用者):执行 /implement、/tdd 等会改动代码的技能前,先按 Shift+Tab 切到 Plan Mode——AI 只读、不改,先给出改动计划,人工 review 通过再执行。这是防止"AI 改飞"的最关键护栏,尤其在生产代码/核心业务模块必须开启。