Matt Pocock Skills 使用指南
mattpocock/skills是 Matt Pocock(TypeScript 与 AI 工程领域知名开发者)开源的一套 AI Coding Agent 工程化技能包,共 27 个 Skill。与接管整个开发流程的重型框架(GSD、BMAD、Spec-Kit 等)不同,它的设计理念是小巧、可控、可组合、跨模型通用,专门解决 AI 写代码时最常见的四类问题:需求理解偏差、上下文冗长、代码缺乏反馈闭环、代码库腐化成"大泥球"。
安装
仓库支持两种安装方式:插件模式(自动更新,只读)和 skills.sh 模式(将可编辑的 Markdown 文件复制到本地项目,可自行修改,需手动更新)。同一个 Agent 只选一种方式,避免同一技能被加载两次。
# Claude Code(推荐,自动更新;--scope project 可仅安装到当前项目)
claude plugin install mattpocock-skills@claude-plugins-official
# Codex(启动时自动更新)
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
# GitHub Copilot(CLI 与 VS Code)
copilot plugin marketplace add mattpocock/skills
copilot plugin install mattpocock-skills@mattpocock
# Gemini CLI(手动更新,重跑两条命令即可更新)
gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
gemini skills install https://github.com/mattpocock/skills.git --path skills/productivity
# Cursor / Windsurf / OpenCode / Devin 等其他 Agent,或需要本地可编辑副本
npx skills@latest add mattpocock/skills -a <agent>
# 省略 -a 可交互选择;更新:npx skills@latest update 后重跑 add 以获取新增技能VS Code 下的 Copilot 也可直接运行 Chat: Install Plugin From Source 并填入 https://github.com/mattpocock/skills,按天更新。
初始化仓库
进入代码仓库,在 Agent 对话框中输入:
/setup-matt-pocock-skills每个仓库只需运行一次。它会先扫描仓库,再逐个确认三件事:
Issue 追踪方式:GitHub(有 GitHub remote 时默认,会执行gh repo view验证可达)、GitLab,还是本地 Markdown(.scratch/<feature>/)或其他工具。Triage 标签规范:是否保留五个默认标签needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix;确认后会通过 CLI 补建缺失标签。领域文档路径:默认写入根目录GLOSSARY.md与docs/adr/(monorepo 场景才会提供多上下文的GLOSSARY-MAP.md方案)。
确认后,它生成 docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md,并在 CLAUDE.md(优先)或 AGENTS.md 中追加 ## Agent skills 索引块。后续所有工程 Skill 都会读取这些配置,无需重复交代项目背景。
27 个 Skill 速查
Skill 分为两个调用层级:User-invoked(必须手动输入 /skill-name,负责任务编排)与 Model-invoked(承载具体工程纪律,可手动调用,也会被上层 Skill 按场景自动触发)。不知道该用哪个时,输入 /ask-matt 描述处境,它会推荐合适的 Skill 或组合。
Engineering(19 个)
User-invoked(流程编排):
| Skill | 作用 | 典型场景 |
|---|---|---|
/setup-matt-pocock-skills | 配置仓库的 Issue Tracker、Triage 标签与领域文档布局 | 新接入项目时运行一次;切换 Issue 工具时重跑 |
/ask-matt | 技能路由器,根据当前处境推荐 Skill 或组合 | 刚上手这套技能库,不确定从哪里切入 |
/grill-with-docs | 深度访谈对齐需求,同时提炼领域词汇,内联更新 GLOSSARY.md 与 ADR | 新功能或重要改造的需求起点,希望术语与架构权衡沉淀到文档 |
/wayfinder | 将超过单个 Agent 会话容量的大型工程拆解为 Issue 上的"决策地图",逐个敲定不确定性 | 大型重构、全新系统搭建的初期规划 |
/to-spec | 不再重复提问,把当前对话直接收敛为 Spec 并发布到 Issue 追踪器(创建前会追问涉及哪些模块) | 访谈确认无误后定稿 |
/to-tickets | 将 Spec 或计划拆为一组声明阻塞关系的 tracer-bullet 小 Ticket | Spec 确认后,拆成适合单上下文交付的小任务 |
/triage | 按分诊角色状态机评估、补充信息、归类并流转 Issue 与外部 PR | 处理团队或外部用户提交的原始 Issue |
/implement | 按 Spec 或 Ticket 实现,在预先约定的接缝处驱动 /tdd,收尾调用 /code-review | 日常写代码主力命令 |
/implement-spec | 在单个集成分支上按任务图调度多个实现 Subagent 并发交付整份 Spec,最后统一 /code-review | Spec 下多个 Ticket 互不阻塞,希望并发提速 |
/improve-codebase-architecture | 扫描代码库寻找"深模块化(Deep Module)“重构机会,生成可视化 HTML 报告并访谈改进 | 每隔几天对代码库做一次体检 |
/retro | 会话结束后复盘,按严重程度输出对 Agent 环境(导航、自动检查、规范文件、工具链)的改进建议 | 持续打磨项目的工程基础设施 |
Model-invoked(工程纪律):
| Skill | 作用 | 典型场景 |
|---|---|---|
/prototype | 构建用完即扔的原型(单文件 HTML 或多套 UI 变体)回答设计问题 | 交互形态或状态流转没想清楚时低成本试错 |
/research | 针对技术问题查阅高可信度一手资料(官方文档/源码),在仓库中保存带引用的 Markdown 结论 | 调研陌生库的 API 行为或版本兼容性,避免凭空臆测 |
/diagnosing-bugs | 硬核 Debug 闭环:稳定复现(变红)→ 最小化 → 假设 → 插桩验证 → 修复 → 回归测试 | 疑难 Bug 或性能退化,防止 AI 乱猜着改 |
/tdd | 强制 Red-Green-Refactor 循环,按垂直切片推进 | 业务逻辑与 Bug 修复(常由 /implement 自动调用) |
/domain-modeling | 打磨领域模型:对照术语表挑刺、边界场景压测,即时更新 GLOSSARY.md 与 ADR | 业务概念模糊、同义不同词(常由 /grill-with-docs 自动调用) |
/codebase-design | “深模块"设计原则与词汇:小接口封装复杂行为,在干净可测的接缝处划分模块 | 模块拆分、接口设计或架构评审 |
/code-review | 两个并行 Subagent 对固定基点以来的 Diff 做双轴审查:Standards(规范/坏味道)与 Spec(是否忠实实现需求) | Commit 或提 PR 前用新鲜视角抓问题 |
/pr | 规范 PR 正文:最小变更摘要、修改前后可运行证据、合并风险定级(单向门/双向门与爆炸半径) | 生成方便 Reviewer 快速决策的 PR 描述 |
/wizard | 生成交互式 Bash 向导脚本,引导人工完成只有人能做的步骤 | 云基础设施配置、CI 密钥填写、一次性数据迁移割接 |
Productivity(7 个)
User-invoked:
| Skill | 作用 | 典型场景 |
|---|---|---|
/grill-me | 对计划或想法无情追问,直到设计树每个分支都讨论清楚(不产出代码和文档) | 非代码事务、个人项目、文章大纲的快速头脑风暴 |
/handoff | 将当前对话压缩为结构化交接文档,让新的 Agent 会话无缝接手 | 上下文快满、模型开始降智,或调研/原型完成准备切换窗口正式开发 |
/teach | 将当前目录作为有状态的学习工作区,跨多个会话循序渐进教授一项技能 | 系统学习新技术、源码框架或工程概念 |
/to-questionnaire | 先盘问"发给谁、想拿回什么答案”,再把开放决策整理成发给特定干系人的 Markdown 问卷 | 产品/法务/设计等跨团队卡点,需要异步征询意见 |
/wait-what | Agent 输出晦涩行话时立刻喊停,结合 GLOSSARY.md 用缺失的上下文重新解释 | 模型输出过于学术、黑话连篇时 |
Model-invoked:
| Skill | 作用 | 典型场景 |
|---|---|---|
/grilling | “追问直到设计树闭合"的可复用访谈原语 | 被 grill-me、grill-with-docs、triage、wayfinder 等自动调用 |
/writing-for-agents | 如何编写面向 Agent 的高质量文档(SKILL.md、AGENTS.md/CLAUDE.md 及索引文档) | 定制新 Skill、优化项目的 CLAUDE.md |
实战示例:从零到一开发新功能
以 SaaS 后端新增"Webhook 失败自动重试与死信队列(DLQ)“为例,使用 GitHub Issues:
1. 初始化仓库(仅首次)
/setup-matt-pocock-skills
本仓库使用 GitHub Issues 管理 Ticket,文档和沟通全部使用中文。请先检查现有 CLAUDE.md 和目录结构后给我确认。确认后 Agent 生成 docs/agents/ 三个配置文件并更新 CLAUDE.md。
2. 深度访谈与领域建模
/grill-with-docs
我想为租户的 Webhook 投递系统增加失败自动重试和死信队列功能。不要急着写代码,逐轮向我提问确认边界条件和架构权衡,每个问题附上推荐选项。Agent 会分轮追问:重试用指数退避还是固定间隔?最大重试几次进死信?4xx 响应重试还是直接进死信?死信支持人工一键重放吗?逐一拍板后(例如:仅 5xx 和网络超时指数退避重试 5 次,4xx 直接标记死信,支持重放但不可编辑 Payload),访谈过程会自动触发 /domain-modeling,把确认的术语(Delivery Attempt、Dead Letter、Terminal Failure)写入 GLOSSARY.md,把"为何选数据库轮询表而非引入 RabbitMQ 延迟队列"的权衡写入 docs/adr/0003-webhook-retry-queue.md。
3. 收敛生成 Spec(同一会话)
/to-spec
把刚才确认的方案整理成完整 Spec,发布到 GitHub Issues,明确写出测试层级和本次明确不做的范围(Out of Scope)。Agent 不再重复采访,确认涉及的模块后,在 GitHub 创建一张 [Spec] Webhook 重试与死信队列 Issue。打开核对,确认没有夹带未讨论过的需求。
4. 拆分 Ticket
/to-tickets https://github.com/your-org/your-repo/issues/42Agent 提出拆分方案,每个 Ticket 都能在单次上下文内做完并独立演示:
#43投递记录状态机与失败分类(区分可重试错误与终态错误)#44指数退避调度 Worker 实现(Blocked by#43)#45死信归档与人工重放 API(Blocked by#43)
确认粒度后,Agent 批量创建 Issue、打上 ready-for-agent 标签并建立阻塞关系。
5. 按 Ticket 实现(建议新开会话,保持上下文干净)
/implement https://github.com/your-org/your-repo/issues/43执行过程:
- 读取
#43及父级 Spec#42,检查前置依赖是否解除,遵循GLOSSARY.md的命名规范。 - 自动触发
/tdd:先写失败的测试(Red),写最小实现让测试通过(Green),再重构(Refactor),按垂直切片推进。 - 跑通全量类型检查与测试套件。
- 自动启动两个并行 Subagent 执行
/code-review:一个只看规范与坏味道(Standards),另一个对照#42/#43核查是否漏掉验收标准(Spec)。修复审查意见后提交。
#44 和 #45 都只被 #43 阻塞且互相独立,也可以直接运行 /implement-spec <Spec 链接> 并发派发 Subagent 一起做完。
6. 生成 PR 与复盘
提交 PR 时按 /pr 规范生成描述(附测试前后对比、单向门/双向门定级与回滚风险评估);整个功能交付后运行:
/retro它会指出这次开发暴露的环境短板,例如:“Worker 的时间模拟测试每次都要手写大量样板代码,建议在 test-utils 里补充统一的 Clock Mock 工具并写进 CLAUDE.md"。
高频分支场景
疑难 Bug 排查
/diagnosing-bugs
用户反馈并发导入超过 500 条数据时余额偶尔少算一笔,本地单测全绿。按诊断闭环来查,先不要直接改业务代码。Agent 会被锁死在阶段门控中:先写出能稳定复现并发竞态的测试(Stable Red)→ 最小化复现用例 → 提出假设并加日志插桩验证根因 → 修复 → 保留回归测试。
架构体检
/improve-codebase-architectureAgent 扫描整个代码库,寻找"接口复杂但内部逻辑浅薄(Shallow Module)“或职责散落的文件,生成可视化 HTML 体检报告;选中最痛的模块后,它会开启访谈模式敲定重构方案。
听不懂 AI 黑话与会话交接
Agent 解释方案时输出一堆抽象概念让人发懵,直接打断:
/wait-what它会停下,结合 GLOSSARY.md 用最直白的话重讲一遍。
调研完第三方文档(/research)或做完原型(/prototype)后对话已经很长,准备开新窗口写正式代码前:
/handoff它把当前所有已确认决策、踩过的坑和下一步动作浓缩成一份交接文档,在新窗口直接贴入即可继续。
使用建议
- ``/implement
在新窗口执行:需求讨论(/grill-with-docs)和编码实现(/implement)分离在不同会话,Spec 和 Ticket 就是上下文交接棒,避免模型受历史对话拖累。 定期运行/improve-codebase-architecture``:官方建议每几天跑一次,把 AI 快速产出的代码持续整理成"简单接口 + 丰富内部实现"的深模块。坚持维护GLOSSARY.md``:统一的人机领域词汇表能减少沟通歧义、让代码命名一致,也减少 Agent 阅读代码消耗的 Token。
参考
最近更新
最新评论