Skill集合工具包——Mattpocock

Skills 是带触发判据的极简 Markdown 指令文件，让 LLM 编码 agent 按工程纪律干活；Matt Pocock 把自己日常用的 .agents 目录开源成 mattpocock/skills，专治 agent 的”不对齐、啰嗦、跑不通、泥球”四大病。

简介

mattpocock/skills（GitHub，MIT 协议）是 Matt Pocock（TypeScript 圈知名作者，ex-Vercel/Stately，Total TypeScript 创作者）公开的一套 AI 编码 agent 的 Skills 合集，副标题原话：”Skills for Real Engineers. Straight from my .agents directory.”——也就是把他自己日常用的 .agents 目录抽出来开源。

定位：给”正经做工程”的人用，不是 vibe coding。它不教模型写代码，而是给模型套上一层工程纪律的”操作规程”。设计哲学援引经典工程文献：《The Pragmatic Programmer》（小步、反馈是限速）、《Domain-Driven Design》（通用语言）、《XP Explained》（每日投资设计）、《A Philosophy of Software Design》（深模块）。

这套 skills 解决 LLM 编码 agent 的四个典型失败模式：

失败模式	含义	对应 skill
Misalignment（不对齐）	agent 干的不是你想要的	/grill-me、/grill-with-docs 先盘问对齐
Verbosity（啰嗦）	没有共享词汇，用一堆字描述	CONTEXT.md 建立领域通用语言
Code doesn’t work（跑不通）	没有反馈回路，盲飞	tdd 红绿循环、diagnosing-bugs
Ball of mud（泥球）	agent 加速软件熵增	to-spec、improve-codebase-architecture

skill 的原理（带 frontmatter 的 SKILL.md、user-invoked 与 model-invoked 两条触发路径、渐进披露、no-op 测试等）详见 《AI编程——Skill原理》，本文不再重复，直接看清单与使用。

Skills 清单

分两大类（Engineering / Productivity），每类再分 user-invoked / model-invoked。

Engineering（工程类）

用户触发：

Skill	作用
ask-matt	路由器，问清情况后推荐用哪个 skill 或 flow
grill-with-docs	边盘问对齐边建项目领域模型，顺手更新 CONTEXT.md 和 ADR
triage	把 issue 按状态机推过一道 triage 角色流
improve-codebase-architecture	扫描代码库找”加深机会”，出 HTML 可视化报告，再就你选的那个盘问到底（建议每几天跑一次）
setup-matt-pocock-skills	每个仓库跑一次：配置 issue tracker、triage label、文档存放位置
to-spec	把当前对话变成 spec，不经访谈直接发到 issue tracker
to-tickets	把 plan、spec 或对话拆成”示踪子弹” ticket，声明阻塞边
implement	按 spec 或 ticket 实现，在约定 seam 处驱动 tdd，收尾跑 code-review
wayfinder	把超大任务规划成 issue tracker 上的一张”调查地图”，逐个解

模型触发：

Skill	作用
prototype	建一次性原型回答设计问题（逻辑问题用终端 app，UI 问题用变体）
diagnosing-bugs	纪律化诊断循环：复现→最小化→假设→插桩→修→回归测试
research	对高可信一手资料调研，产出带引用的 markdown，后台 agent 跑
tdd	红绿重构，一次一个垂直切片
domain-modeling	建并打磨领域模型，挑战术语、用边界用例压测，更新 CONTEXT.md 与 ADR
codebase-design	“深模块”设计纪律：小接口藏大行为，接口处可测
code-review	双轴并行子 agent 审查 diff：Standards（编码规范＋Fowler 坏味道）＋ Spec（忠实实现原 issue 或 PRD）
resolving-merge-conflicts	按 hunk 解合并冲突，依据双方意图的一手来源，永不 --abort

Productivity（生产力类）

用户触发：

Skill	作用
grill-me	死磕式访谈，把决策树每个分支问到死
handoff	把当前对话压缩成交接文档，供下一个 agent 续
teach	跨多次会话教你一个新技能或概念，用当前目录当教学沙盒
writing-great-skills	写 skill 的元 skill——词汇和原则（上文”原理”一节就是它的内容）

模型触发：

Skill	作用
grilling	grill-me 和 grill-with-docs 背后共用的那套访谈循环

样例：tdd

挑 tdd 展开一个 skill 的真实写法，因为它最能体现”用 skill 沉淀纪律”的思路。

frontmatter：name: tdd，description 命中”red-green-refactor / 集成测试”等触发词，disable-model-invocation: false（可被模型自动触发）。

正文要点：

• 好测试：通过公共接口验行为、读起来像规约、扛得住重构。
• Seam（缝）：只在”预先约定并和用户确认过”的公共边界测，不测未确认 seam；任何测试动手前先写下 seam 并与用户确认。
• 三大反模式：
  1. 实现耦合——mock 内部协作者或测私有方法，特征是”重构即崩但行为没变”；
  2. 同义反复——断言把代码逻辑重算一遍，永远不可能挂，期望值必须来自独立真值源；
  3. 横切——先写全测试再写全实现。正确做法是垂直切片：一条测试→一段最小实现→重复，每条测试都是示踪子弹。
• 循环三规：先红后绿（只写够过测试的代码，不投机）、一切一片、重构不在循环内（归 code-review）。

可见 tdd 把教科书里的 TDD 纪律，拆成了”触发判据＋可执行步骤＋反模式清单”，agent 读到就照着走，而不是自由发挥。

安装与使用

两种安装方式，对应两种哲学，按需选一种。

维度	方式 A：skills.sh	方式 B：Claude Code 插件
命令	npx skills@latest add mattpocock/skills	/plugin marketplace add mattpocock/skills 后 /plugin install mattpocock-skills@mattpocock
形态	复制进项目，可改	托管只读包，随作者更新
哲学	fork 派，改造成自己的	订阅派，跟作者走
必做	装完跑 /setup-matt-pocock-skills	每仓库跑一次 /setup-matt-pocock-skills

shell 形式的插件安装：

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

skills.sh 装的时候已经能装进 Codex 等 Agent-Skills 标准的 agent；原生 Codex 插件在 roadmap 上。

典型动线

/grill-me          盘问对齐，把决策树问完
   ↓
/to-tickets        拆成示踪子弹 ticket
   ↓
/implement         按 ticket 实现，自动驱动 /tdd（红绿）
   ↓
/code-review       双轴审查收尾

日常维护：每几天跑 /improve-codebase-architecture 治泥球；遇到 bug 模型自动走 diagnosing-bugs；要交接就 /handoff。

小结

一句话：Matt Pocock 的 skills 本质是把老一辈软件工程纪律（TDD、DDD 通用语言、深模块、示踪子弹）封装成 Claude Code 能读的、带触发判据的极简 Markdown 指令，靠”确定性步骤＋自动触发＋渐进披露”三件套，让 LLM agent 从盲飞乱写变成按工程规矩干活。

核心要点速记：

要点	记住
本体	一个带 frontmatter 的 SKILL.md
三字段	name（命令名）、description（自动触发判据）、disable-model-invocation（是否只能手动调）
两路径	user-invoked 编排工作流、model-invoked 沉淀纪律
三层信息	in-skill steps / in-skill reference / external reference
收紧原则	no-op 测试——删了不影响工作就删
四大病	不对齐、啰嗦、跑不通、泥球

延伸方向：想自己写 skill，直接读仓库里的 writing-great-skills 那个元 skill，它是这套规范的源头。