mattpocock/skills 保姆级部署教程：30 万星工程师实战 Agent 技能库

一句话定位：TypeScript 教育者 Matt Pocock 开源的 mattpocock/skills，是他本人每天在真实工程项目里给 Claude Code、Codex、GitHub Copilot、Gemini CLI 等编码 Agent 用的一套实战技能库——不搞 vibe coding，而是把《程序员修炼之道》《领域驱动设计》《架构整洁之道》里的工程基本功拆成可被 Agent 直接调用的 /grill-me、/tdd、/code-review、/improve-codebase-architecture 等命令。

slogan：My agent skills that I use every day to do real engineering — not vibe coding.

仓库地址：https://github.com/mattpocock/skills · 许可证：MIT · ⭐ 约 30.8 万 · 官网：skills.sh/mattpocock/skills

▲ 图 1：mattpocock/skills 仓库 README 顶部的官方横幅与 skills.sh 徽章（README 内嵌，官方截图）

一、项目简介

做 TypeScript 在线教育的 Matt Pocock（Total TypeScript 作者）在仓库里直接放话：他受够了 GSD、BMAD、Spec-Kit 这类"替你接管整个流程"的 Agent 框架——它们确实能跑起来，但把工程师本人的控制权也一并收走了，一旦流程里出 bug，你根本没法在里面改。于是他自己写了一套反过来的东西：小、易改、可组合、跟模型无关，每个技能就是一份 Markdown，塞进你的项目里你能随手改。

这套技能库要解决的是用编码 Agent 时最常见的四种翻车：① Agent 没听懂你到底要做什么（对齐失败）；② Agent 啰嗦半天、术语满天飞（缺共享语言）；③ Agent 写的代码一跑就挂（没有反馈环）；④ 代码越堆越像一团泥（没人管架构）。对应地，他给了 /grill-me、/grill-with-docs、/tdd、/diagnosing-bugs、/improve-codebase-architecture 等一系列可被 Agent 直接调用的技能。

项目以 MIT 许可证开源，作者明确鼓励你"上手改、改成自己的"。除了 Claude Code 走插件市场自动更新之外，其他方式装进去的都是可编辑副本——更新靠你自己重跑一次安装命令，这是作者有意为之：技能是你项目的一部分，不是黑盒插件。

二、功能特点

整个仓库按"谁来调用"分成两轴：User-invoked（你手动敲 /xxx 才触发，负责编排）和 Model-invoked（Agent 自己判断合适就调用，负责沉淀纪律）。一个用户触发的技能可以调用模型触发的技能，但不能再触发另一个用户触发的技能。

三、环境要求

• 宿主 Agent：任选其一——Claude Code、Codex、GitHub Copilot CLI / VS Code、Gemini CLI，或者任何支持 npx skills 安装器的 Agent（cursor、opencode、devin、windsurf、amp、pi 等）。
• 运行时：只要你能跑对应 Agent 的 CLI 即可；走 npx skills@latest 这条路需要本机有 Node.js（自带 npx）。
• 网络：能访问 github.com 与 skills.sh；走插件市场的安装方式会从对应市场（如 claude-plugins-official、mattpocock 这个 marketplace）拉取。
• 项目仓库：建议是一个用 Git 管理的代码仓库；每个新仓库第一次用之前要跑一次 /setup-matt-pocock-skills，回答几个关于 issue tracker、标签、文档位置的问题。
• 许可证：MIT，随便改、随便用，包括商用。

四、保姆级部署步骤

作者强调：每个 Agent 只装一种方式——同时装会让你每个技能出现两遍。下面按你用的 Agent 选一条走。

4.1 Claude Code（推荐，自动更新）

一条命令装插件：

claude plugin install mattpocock-skills@claude-plugins-official

装完默认自动更新，无需手动维护。

4.2 Codex

先加 marketplace，再装插件，启动时自动更新：

codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock

4.3 GitHub Copilot（CLI 与 VS Code）

CLI 下：

copilot plugin marketplace add mattpocock/skills
copilot plugin install mattpocock-skills@mattpocock

然后一次性把 marketplace 加进 ~/.copilot/settings.json，让它自动更新：

{
  "extraKnownMarketplaces": {
    "mattpocock": {
      "source": { "source": "github", "repo": "mattpocock/skills" },
      "autoUpdate": true
    }
  }
}

在 VS Code 里，则用命令面板跑 Chat: Install Plugin From Source，输入仓库地址 github.com/mattpocock/skills，它每天自动更新。

4.4 Gemini CLI（手动更新）

分两条路装，把工程类和效率类分别拉进来：

gemini skills install github.com/mattpocock/skills.git --path skills/engineering
gemini skills install github.com/mattpocock/skills.git --path skills/productivity

以后想更新，把这两条命令再跑一遍即可。

4.5 其他 Agent（cursor / opencode / devin / windsurf / amp / pi 等）

用通用安装器 skills：

npx skills@latest add mattpocock/skills -a <agent>

把 <agent> 换成你实际用的 Agent 名（cursor、opencode、devin、windsurf、amp、pi）；不带 -a 它会让你自己选。安装器会问你要带哪些技能，记得勾上 setup-matt-pocock-skills——不然后面没法跑初始化。

这种方式装进去的是可编辑副本，作者故意这么设计：技能文件在你项目里，你可以改。要更新就重跑：

npx skills@latest update
npx skills@latest add mattpocock/skills -a <agent>

4.6 每个新仓库跑一次初始化

装完插件 / 技能文件之后，进到你的项目仓库里，在 Agent 对话里跑一次：

/setup-matt-pocock-skills

它会依次问你三件事：

1. 你想用哪个 issue tracker（GitHub、GitLab、本地文件，或你自己描述的任何东西）；
2. 分诊时给 ticket 打什么标签（/triage 要靠这些标签）；
3. 新建的文档（GLOSSARY.md、ADR、spec 等）希望存到哪个目录。

回答完，整个仓库就接入这套技能了。

五、配置说明

这套技能库本身几乎没有"全局配置"——作者的设计哲学就是把配置摊在你项目里：

• GLOSSARY.md：由 /grill-with-docs 与 /domain-modeling 自动维护，沉淀项目术语。README 里给的例子：以前要说"课程里某一节课在某个 section 下被真正落到文件系统"，现在就叫 "materialization cascade"——一句话省掉 20 个字，Agent 也跟着少烧 token。
• ADR（架构决策记录）：同一组技能在盘问过程中把"很难口头解释的决定"顺手写成 ADR 落进仓库。
• Issue tracker 与标签：在 /setup-matt-pocock-skills 里一次性选好，之后 /triage、/to-spec、/to-tickets、/wayfinder 都按这套约定走。
• 可编辑副本：除 Claude Code 插件外，所有方式装进去的技能都是你项目里的普通 Markdown 文件，直接改、直接 commit，作者鼓励你"hack around with them, make them your own"。

六、使用方法

6.1 日常对齐：先 /grill-me 或 /grill-with-docs 再动手

作者把这两个技能称为他仓库里最受欢迎的两个。每次想让 Agent 改点东西之前，先跑一次。它会像面试官一样追问你：你到底要解决什么问题？边界情况是什么？什么算"做完了"？非代码场景用 /grill-me，要写代码就用 /grill-with-docs——后者会顺便把术语沉淀进 GLOSSARY.md，并把关键决定写成 ADR。

6.2 写代码：/tdd 管反馈环，/code-review 管合入前

实现阶段交给 /implement：它会在事先约定的接缝处自动跑 /tdd（先写失败测试，再让测试过），提交前再过一遍 /code-review。/code-review 是双轴并行的——一个子 Agent 专看"符不符合仓库规范 + Fowler 坏味道"，另一个专看"有没有忠实实现原 spec"，两个子 Agent 互不知道对方，避免互相污染。

6.3 大活：/to-spec → /to-tickets → /implement-spec

大到一个会话装不下的工作，先用 /to-spec 把当前对话综合成一份 spec 发到 issue tracker，再用 /to-tickets 拆成带阻塞关系的曳光弹工单，最后用 /implement-spec 把工单当任务图，并行派给子 Agent，最后自动跑 /code-review。

6.4 架构体检：/improve-codebase-architecture

作者建议每隔几天跑一次。它会扫一遍代码库，找出"可以加深"的模块候选，输出一份可视化 HTML 报告，再逐个盘问你要不要改。注意它是体检不是抢救：对一个已经糊成泥的老仓库，它会列出真问题，但不会替你把泥拆开。

6.5 卡住了：/wait-what 与 /diagnosing-bugs

Agent 上一句话你没看懂，立刻敲 /wait-what，它会用你项目 GLOSSARY.md 里的术语重新用大白话解释一遍。遇到硬 bug 或性能回退，走 /diagnosing-bugs 的分阶段诊断环：先做一个能稳定复现 bug 的反馈环，再最小化、提假设、插桩、修复、补回归测试。

七、常见问题 FAQ

问一：它和 GSD、BMAD、Spec-Kit 有什么区别？我已经装了一个，还要不要装这个？
答：作者本人的批评很直接——那几类框架"接管整个流程"，把工程师的控制权也收走了，一旦流程里出 bug 你很难在里面改。mattpocock/skills 反过来：技能小、可编辑、跟模型无关，装进去的就是你项目里的 Markdown 文件，你想怎么改怎么改。如果你喜欢"流程被框架托管"，那这一套不是给你的；如果你想要"纪律在我手里、我随时能改"，那就换过来。

问二：我同时用 Claude Code 和 Codex，两个都装会怎样？
答：作者在 README 里明说：每个 Agent 只装一种。同时装会让你每个技能出现两遍。如果不同 Agent 各用各的，那是各装各的；同一个 Agent 里别叠两种安装方式。

问三：为什么 Gemini CLI / npx 装完不能自动更新？
答：这是有意设计。除了 Claude Code 插件走插件市场自动更新之外，其他方式装进去的都是可编辑副本——作者认为技能是你项目的一部分，不该被远端静默覆盖。要更新就重跑一遍 gemini skills install ... 或 npx skills@latest update && npx skills@latest add ...。

问四：我已经有一个老仓库了，能直接跑 /improve-codebase-architecture 让它自动把泥拆开吗？
答：不能。它的定位是体检不是抢救：会扫出真实的"可加深"模块候选，列成 HTML 报告让你挑一个，再用 /grill-with-docs 那种盘问方式和你一起改。指望它一键把老仓库重整，会失望。

问五：我不写 TypeScript，这套技能还能用吗？
答：能。作者本人主要在 TypeScript 项目里用，但技能内容是通用的工程纪律（TDD、领域建模、code review、架构深化、bug 诊断），README 里也强调"与模型无关、与语言无关"。你只要把它装进你用的 Agent 里，在任何语言的仓库里跑 /setup-matt-pocock-skills 即可。

相关链接

• 项目仓库：mattpocock/skills
• 项目主页（skills.sh）：skills.sh/mattpocock/skills
• 作者通讯（约 6 万订阅）：AI Hero Newsletter
• 工程类技能目录：skills/engineering
• 效率类技能目录：skills/productivity
• 初始化技能：setup-matt-pocock-skills
• 盘问式对齐技能：grill-me 与 grill-with-docs
• 架构体检技能：improve-codebase-architecture