# 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`)](https://cli.github.com/) 并完成身份认证。 ``` # 检查登录状态 gh auth status # 未登录时执行交互式登录 gh auth login ``` ## 3. 安装与配置步骤 用管理员权限打开 PowerShell 执行： ``` npx skills@latest add mattpocock/skills ``` 在交互式选项中建议选择： ``` > Symlink (Recommended) ``` 安装后技能文件默认存储于用户家目录下的 `.agents` 路径 ``` C:\Users\\.agents\skills\ # Windows ~/.agents/skills/ # macOS/Linux ``` 技能更新与卸载 ``` # 拉取并更新技能至最新版 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`):** ``` # 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 会自动生成: ``` StockAnalyzer/ ├─ CONTEXT.md ← 新增,内容如下 └─ docs/ ├─ agents/ (略) └─ adr/ ← 新增(如果有架构决策) └─ 0001-csv-import-format.md ← 新增(仅当出现"难以逆转 + 需要理由 + 有真实取舍"三要素时) ``` CONTEXT.md 样例: ``` # 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 会自动为你推荐最优的技能工作流。 |命令|作用说明|推荐优先级|生成物 / 副作用| |---|---|---|---| |`/grilling <描述>`|**轻量版需求访谈**,只拷问、不写文档|⭐⭐⭐⭐⭐|**无文件产出**——只在对话里问答| |`/grill-with-docs <描述>`|深度需求访谈,自动更新领域词典|⭐⭐⭐⭐⭐|📄 新增/更新 `CONTEXT.md`(有新术语时)
📄 新增 `docs/adr/NNNN-xxx.md`(仅当出现难以逆转的架构决策)| |`/to-spec`|将对话总结为技术规格并发布到 issue 追踪器|⭐⭐⭐⭐|🎫 GitHub Issue(远程模式)
📄 `.scratch//spec.md`(本地模式)| |`/implement`|按 spec/ticket 实现代码,自带完工纪律|⭐⭐⭐⭐|📝 修改源码文件(`src/**`)
📝 新增/修改测试文件
🔀 一个 `git commit`| |`/tdd`|严格 TDD:先写 failing test 再写实现|⭐⭐⭐⭐⭐|📝 交替新增测试文件与实现文件
🔀 通常配合多次小 commit| |`/prototype`|快速原型验证|⭐⭐⭐|📝 新增原型代码文件(标注"prototype"字样)
🌿 建议提交到 throwaway 分支| |`/diagnosing-bugs`|标准化缺陷排查|⭐⭐⭐⭐⭐|**主要为对话输出**(假设+验证方案)
📝 可能新增回归测试文件| |`/code-review`|工程规范与安全性代码审查|⭐⭐⭐⭐|**无文件产出**——评审报告在对话里| |`/to-tickets`|将方案拆解为工单|⭐⭐⭐|🎫 多个 GitHub Issues(远程)或 📄 `.scratch//*.md` 一 ticket 一文件(本地)| |`/triage`|批量管理 Issue 状态|⭐⭐|🎫 修改远程 issue 的标签/评论| |`/handoff`|会话摘要,便于新窗口继续|⭐⭐⭐|📄 **写入 OS 临时目录**(不污染工作区),Windows 一般在 `%TEMP%\claude-handoff-*.md`| |`/research`|技术调研|⭐⭐⭐|📄 在仓库既有的调研文档目录下新增 Markdown(带引用来源);无固定目录时会说明放哪| |`/resolving-merge-conflicts`|辅助解决合并冲突|⭐⭐|📝 修改冲突文件
🔀 完成 merge/rebase commit| |`/improve-codebase-architecture`|架构审查与优化建议|⭐|📄 **HTML 报告写入 OS 临时目录**(不入库),自动打开浏览器| |`/ask-matt`|技能路由|⭐⭐⭐⭐⭐|**无文件产出**——只在对话里推荐| **图例:** 📄 = Markdown 文档 | 📝 = 源码 | 🎫 = 远程工单 | 🔀 = git commit | 🌿 = 独立分支 > 💡 **速记原则:** > > - **动代码的**:`/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 都读这个配置来决定"发到哪"。 ### 怎么选? | 场景 | 推荐模式 | | -------------------------------------------- | ----------------------------------- | | 团队协作、有 GitHub/GitLab 仓库、希望 issue 状态和讨论对所有人可见 | **GitHub / GitLab 远程模式** | | 个人项目 / 不想开外部账号 / 想让 issue 跟代码一起进 Git 版本控制 | **本地模式** | | 公司统一用 Jira / Linear / 飞书等 | **Other**——初始化时详细描述工作流,skills 会尽力对齐 | 💡 **补充:** 无论选哪种模式,`/handoff`、`/improve-codebase-architecture` 生成的临时文件都**始终**放在 OS 临时目录,不受这里的模式选择影响——那是"会话性产出",不是"工单"。 ## 6. 典型场景实战工作流 ### 场景 1:普通业务功能开发(数据导入 / 后台接口) **推荐链路:** `/grill-with-docs` → `/to-spec` → `/implement` → `/code-review` **每步的输入与产出对比:** ``` /grill-with-docs 开发 K 线历史数据导入模块:支持从 CSV 文件读取日线数据,校验时间、开盘价、收盘价、成交量字段, 存入数据库;重复日期数据自动覆盖,输出导入成功条数与异常日志。 ``` **产出:** 若过程中出现新术语,自动在根目录新增/更新: ``` + CONTEXT.md (新增/追加"K 线""日线""导入批次"等术语定义) + docs/adr/0001-csv-import-idempotency.md (仅当决策"重复日期覆盖策略"值得记录时) ``` ``` /to-spec ``` 产出: 一份 spec 发布到 issue tracker: ``` GitHub 模式: https://github.com/<你>//issues/42 ← 新 issue,带 ready-for-agent 标签 本地模式: + .scratch/csv-import/spec.md ``` 产出: 拆分成多个可追踪的 ticket: ``` 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) ``` ``` Shift+Tab (切换到 Plan Mode) /implement #01 按 01-parse-csv-rows 这个 ticket 实现。 ``` **产出:** 真正动源代码: ``` + 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" ``` ``` /code-review ``` **产出:** 对话里输出评审报告(不写文件);发现的问题若需修复,会走另一个 commit。 ### 场景 2:量化核心计算逻辑(指标 / 策略 / 回测) ⚠️ **强制规范:** 涉及核心数值计算、资产结算等逻辑,必须强制走 `/tdd` 流程,先写 Failing Test 再写实现。 **推荐链路:** `/grill-with-docs` → `/to-spec` → `/tdd` ``` /grill-with-docs 实现 ATR(平均真实波幅)指标计算:输入 K 线序列,周期默认 14;严格遵循标准 ATR 算法, 兼容数据不足周期的异常场景;输出每条 K 线对应的 ATR 计算结果。 ``` **产出:** 若沉淀了"ATR""真实波幅"等术语,更新 `CONTEXT.md`。 ``` /to-spec ``` **产出:** 一条 spec issue(含 seams 定义、user stories、testing decisions),用于指导后续 TDD 的测试点位。 ``` /tdd ``` **产出模式与 `/implement` 根本不同——是"红→绿"多轮交替:** ``` ─ 循环 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` ``` /grill-with-docs 验证 5/20 日均线交叉策略：基于内存中的 K 线数据模拟回测，暂不接入数据库，统计总收益率与最大回撤。 ``` ``` /prototype ``` ### 场景 4：复杂缺陷定位与排查（Bug Fixing） ``` /diagnosing-bugs 回测模块的最大回撤计算结果异常：人工核算为 12.5%，程序实际输出为 18.2%，请协助定位根本原因并补充回归测试用例。 ``` ### 场景 5：大型需求拆解与工单流转（团队协作） ``` /grill-with-docs 开发策略回测后台：包含新建策略、选择数据区间、执行回测、可视化收益指标展示及导出回测报告。 ``` ``` /to-spec ``` ``` /to-tickets Agent 将自动读取 docs/agents/issue-tracker.md 并在 GitHub 创建对应的 Issues。 ``` ``` /triage ``` ### 场景 6:跨需求平滑交接与上下文清理(防止对话污染) 开发完一个需求准备换到下一个需求时: 1. 在当前对话框输入 `/handoff`,导出当前需求的成果总结。 - **产出位置:** OS 临时目录(**不污染工作区**)。Windows 通常在 `%TEMP%\` 下,macOS/Linux 在 `$TMPDIR/` 或 `/tmp/` 下。文件名类似 `handoff-<时间戳>.md` - **产出内容:** 已完成的部分、进行中的状态、下一步建议动作、推荐的 skills 2. **直接关闭当前对话窗口,新建一个干净的窗口**。 3. 新窗口第一句话把 handoff 文件路径丢给 AI(比如"读一下 `C:\Users\\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 改飞"的最关键护栏,尤其在生产代码/核心业务模块必须开启。** --- > 作者: XiongNeng > URL: https://xiongneng.me/posts/ai/matt-pocock-skills/