Matt Pocock Skills 使用指南

发布时间: 更新时间: 总字数:4440 阅读时间:9m 作者:IP:上海 网址

mattpocock/skills 是 Matt Pocock(TypeScript 与 AI 工程领域知名开发者)开源的一套 AI Coding Agent 工程化技能包,共 27 个 Skill。与接管整个开发流程的重型框架(GSD、BMAD、Spec-Kit 等)不同,它的设计理念是小巧、可控、可组合、跨模型通用,专门解决 AI 写代码时最常见的四类问题:需求理解偏差、上下文冗长、代码缺乏反馈闭环、代码库腐化成"大泥球"。

安装

仓库支持两种安装方式:插件模式(自动更新,只读)和 skills.sh 模式(将可编辑的 Markdown 文件复制到本地项目,可自行修改,需手动更新)。同一个 Agent 只选一种方式,避免同一技能被加载两次。

bash
# 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 对话框中输入:

text
/setup-matt-pocock-skills

每个仓库只需运行一次。它会先扫描仓库,再逐个确认三件事:

  1. Issue 追踪方式:GitHub(有 GitHub remote 时默认,会执行 gh repo view 验证可达)、GitLab,还是本地 Markdown(.scratch/<feature>/)或其他工具。
  2. Triage 标签规范:是否保留五个默认标签 needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix;确认后会通过 CLI 补建缺失标签。
  3. 领域文档路径:默认写入根目录 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 小 TicketSpec 确认后,拆成适合单上下文交付的小任务
/triage按分诊角色状态机评估、补充信息、归类并流转 Issue 与外部 PR处理团队或外部用户提交的原始 Issue
/implement按 Spec 或 Ticket 实现,在预先约定的接缝处驱动 /tdd,收尾调用 /code-review日常写代码主力命令
/implement-spec在单个集成分支上按任务图调度多个实现 Subagent 并发交付整份 Spec,最后统一 /code-reviewSpec 下多个 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-whatAgent 输出晦涩行话时立刻喊停,结合 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. 初始化仓库(仅首次)

text
/setup-matt-pocock-skills
本仓库使用 GitHub Issues 管理 Ticket,文档和沟通全部使用中文。请先检查现有 CLAUDE.md 和目录结构后给我确认。

确认后 Agent 生成 docs/agents/ 三个配置文件并更新 CLAUDE.md。

2. 深度访谈与领域建模

text
/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(同一会话)

text
/to-spec
把刚才确认的方案整理成完整 Spec,发布到 GitHub Issues,明确写出测试层级和本次明确不做的范围(Out of Scope)。

Agent 不再重复采访,确认涉及的模块后,在 GitHub 创建一张 [Spec] Webhook 重试与死信队列 Issue。打开核对,确认没有夹带未讨论过的需求。

4. 拆分 Ticket

text
/to-tickets https://github.com/your-org/your-repo/issues/42

Agent 提出拆分方案,每个 Ticket 都能在单次上下文内做完并独立演示:

  • #43 投递记录状态机与失败分类(区分可重试错误与终态错误)
  • #44 指数退避调度 Worker 实现(Blocked by #43)
  • #45 死信归档与人工重放 API(Blocked by #43)

确认粒度后,Agent 批量创建 Issue、打上 ready-for-agent 标签并建立阻塞关系。

5. 按 Ticket 实现(建议新开会话,保持上下文干净)

text
/implement https://github.com/your-org/your-repo/issues/43

执行过程:

  1. 读取 #43 及父级 Spec #42,检查前置依赖是否解除,遵循 GLOSSARY.md 的命名规范。
  2. 自动触发 /tdd:先写失败的测试(Red),写最小实现让测试通过(Green),再重构(Refactor),按垂直切片推进。
  3. 跑通全量类型检查与测试套件。
  4. 自动启动两个并行 Subagent 执行 /code-review:一个只看规范与坏味道(Standards),另一个对照 #42/#43 核查是否漏掉验收标准(Spec)。修复审查意见后提交。

#44 和 #45 都只被 #43 阻塞且互相独立,也可以直接运行 /implement-spec <Spec 链接> 并发派发 Subagent 一起做完。

6. 生成 PR 与复盘

提交 PR 时按 /pr 规范生成描述(附测试前后对比、单向门/双向门定级与回滚风险评估);整个功能交付后运行:

text
/retro

它会指出这次开发暴露的环境短板,例如:“Worker 的时间模拟测试每次都要手写大量样板代码,建议在 test-utils 里补充统一的 Clock Mock 工具并写进 CLAUDE.md"。

高频分支场景

疑难 Bug 排查

text
/diagnosing-bugs
用户反馈并发导入超过 500 条数据时余额偶尔少算一笔,本地单测全绿。按诊断闭环来查,先不要直接改业务代码。

Agent 会被锁死在阶段门控中:先写出能稳定复现并发竞态的测试(Stable Red)→ 最小化复现用例 → 提出假设并加日志插桩验证根因 → 修复 → 保留回归测试。

架构体检

text
/improve-codebase-architecture

Agent 扫描整个代码库,寻找"接口复杂但内部逻辑浅薄(Shallow Module)“或职责散落的文件,生成可视化 HTML 体检报告;选中最痛的模块后,它会开启访谈模式敲定重构方案。

听不懂 AI 黑话与会话交接

Agent 解释方案时输出一堆抽象概念让人发懵,直接打断:

text
/wait-what

它会停下,结合 GLOSSARY.md 用最直白的话重讲一遍。

调研完第三方文档(/research)或做完原型(/prototype)后对话已经很长,准备开新窗口写正式代码前:

text
/handoff

它把当前所有已确认决策、踩过的坑和下一步动作浓缩成一份交接文档,在新窗口直接贴入即可继续。

使用建议

  1. ``/implement 在新窗口执行:需求讨论(/grill-with-docs)和编码实现(/implement)分离在不同会话,Spec 和 Ticket 就是上下文交接棒,避免模型受历史对话拖累。
  2. 定期运行 /improve-codebase-architecture``:官方建议每几天跑一次,把 AI 快速产出的代码持续整理成"简单接口 + 丰富内部实现"的深模块。
  3. 坚持维护 GLOSSARY.md``:统一的人机领域词汇表能减少沟通歧义、让代码命名一致,也减少 Agent 阅读代码消耗的 Token。

参考

  1. https://github.com/mattpocock/skills
  2. https://skills.sh/mattpocock/skills