mattpocock/skills 是知名 TypeScript 教育家、Total TypeScript 创始人 Matt Pocock 的个人 Agent 技能库，2026 年开源后迅速成为 GitHub 上关注度最高的技能集合之一（22 万 + stars）。仓库副标题为 “Skills for Real Engineers. Straight from my .agents directory.” —— 它直接来自作者的日常开发环境，是作者真实使用的技能，而非演示性质的教学样本。
读者指南：本文第 1-5 章讲设计（所有人可读），第 6 章是与本仓库的对比（作者视角，普通用户可跳过），第 7 章给出可操作的借鉴结论（每条配落地第一步），第 8 章是 5 分钟快速开始。想直接上手的读者可以从第 8 章开始。
项目收录 35 个 SKILL.md，按用途分为五个桶（bucket）：
| 目录 | 定位 |
|---|---|
engineering/ |
日常代码工作（18 个，推荐发布） |
productivity/ |
非代码类工作流工具（7 个，推荐发布） |
misc/ |
保留但不推广（4 个） |
in-progress/ |
公开的 beta 技能，收集反馈（6 个） |
deprecated/ |
已废弃 |
仓库的核心理念在 README 中直言不讳：
Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve. These skills are designed to be small, easy to adapt, and composable. They work with any model. They’re based on decades of engineering experience.
与市面上”拥有流程”的框架（GSD、BMAD、Spec-Kit——均为试图接管整个开发流程的方法论体系，如 GSD 是 GitHub 的 spec 驱动工作流）不同，该仓库把技能设计为小、可适配、可组合的纪律单元：作者明确鼓励用户 “Hack around with them. Make them your own.”。针对的四个真实失败模式：对齐失败（agent 没做用户想做的事）、过度冗长（agent 用 20 个词说 1 个词能说的话）、代码不工作（缺乏反馈回路）、代码库变成大泥球（软件熵加速）。
如果只用一个词概括这个仓库，”组合”（composition）是最恰当的。与绝大多数”一个技能 = 一份完整手册”的仓库不同，这里的技能形成一座金字塔：
grilling（访谈）、domain-modeling（领域建模）、codebase-design（深模块设计）、tdd（测试驱动开发）、research（研究）、prototype（原型）、code-review（评审）、diagnosing-bugs（诊断）。它们承载全部方法论，任何时候都可以被触发。grill-with-docs、grill-me、wait-what、handoff、implement 等（SKILL.md 仅 7-16 行）。路由技能的正文经常只有一句话，例如 grill-with-docs 的完整 SKILL.md：---
name: grill-with-docs
description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
disable-model-invocation: true
---
Call the Skill tool twice, for "grilling" and "domain-modeling".
grilling 是复用度最高的原语：grill-me、grill-with-docs、triage、wayfinder、improve-codebase-architecture 五个技能都在驱动它。ask-matt 则是整个组合系统的显式地图——一个”技能路由”技能，负责回答”现在这种情况该用哪个技能”。
这种架构的收益：方法论只写一遍，出现在一个地方（原语），修 bug 是一处编辑；路由技能几乎不消耗上下文，只在用户真正需要时把原语拉进来。代价是组合依赖字符串约定（”Call the Skill tool with X”），用户经 skills.sh 只安装子集时，路由技能的调用会静默失效——这是该组合架构的一个固有风险。仓库未内置探测机制（唯一做安装探测的是 setup-matt-pocock-skills），新用户需要注意。
ask-matt 不只是技能地图，它编码了整个仓库的组合骨架：“idea → ship” 主流程——grill-with-docs（对齐）→ to-spec（综合成规范）→ to-tickets（拆成票）→ implement（按票实现，内部驱动 tdd，收尾 code-review），两条 on-ramp（triage 分诊、diagnosing-bugs 诊断），以及 prototype 经 handoff 的绕行桥。
grilling 是仓库最受欢迎的模式（README 自述 grill-me / grill-with-docs 为 “These are my most popular skills”），也是对齐失败（failure mode #1）的解法。它把”让 agent 向用户提问”这件事从随意的对话改造成有结构的纪律：
设计树（design tree）：每一次决策都会分支成挂在它下面的子决策。访谈的目标是遍历整棵树，直到每个分支都被访问过、没有留下任何静默假设。
前沿轮次（frontier rounds）：把”所有前提已经满足、现在就能问的问题”（前沿，frontier）作为一整轮一次性抛出。每个问题编号，并附上模型的推荐答案，然后停下来等用户回答，再计算下一轮前沿。这种批处理是注意力经济学的精巧设计——一次等待换来一整片问题的答案，而不是一问一答的低效往返。
职责切分：“Finding facts is your job, never the user’s.”（找事实是 agent 的活，永远不是用户的活）。前沿问题需要查文件、查环境时，派 sub-agent 去找，不阻塞其余问题；但决策永远是用户的——每个决策都交给用户拍板。
终止条件：前沿为空——设计树的每个分支都已访问，没有剩余静默假设。在用户确认达成共识之前，不得开始行动。
一次 grilling 对话长这样（问题编号 + 推荐答案，一轮抛出一整片前沿）：
❓ **Q1** - **目标范围**：这个改动要覆盖哪些功能，明确排除哪些？
➡️ 建议先只做核心流程，边缘场景留到第二期
❓ **Q2** - **数据模型**：现有 schema 需要迁移吗？
➡️ 建议不需要，增量加字段即可
（注：grill-with-docs 的描述中提到的 ADR 即 Architecture Decision Record，架构决策记录——记录”为什么这么设计”的短文档，防止无上下文的未来维护者误改。）
wayfinder 是对”一个 agent 会话装不下的大型工作”最严肃的结构化回答之一。核心洞见：多会话的规划必须是一个共享物，而不是会话内的状态。
wayfinder 默认是规划模式（plan, don’t do）：地图完成的标准是”路已清晰、没有待决事项”，而不是交付物。tdd 把”红→绿循环”重构为 seam 治理。它的目标不是教 agent 跑 TDD，而是让循环”产出值得留的测试”：
expect(add(a, b)).toBe(a + b)）。期望值必须来自独立的事实源。code-review 阶段，防止红绿循环被稀释。codebase-design 获取词汇——”a reference to consult, not a session to run”（是供查阅的参考，不是要跑一遍的会话）。diagnosing-bugs 的宣言是：“Phase 1: Build a feedback loop. This is the skill. Everything else is mechanical.”（构建反馈回路。这才是技能本身，其余全是机械动作）。
git bisect run）[DEBUG-a4f2]，清理是一个 grep。improve-codebase-architecture。writing-for-agents 是”关于怎么写 agent 文档的文档“——本仓库所有 SKILL.md 的质量来源，也是少数把技能写作理论化的公开案例。它的工具箱：
package.json、--help 是 lookup，重述它们的是缓存）、相关性检查（防 sediment——”添加感觉安全、删除感觉冒险”的默认命运）、no-op 测试（”这条指令相对默认行为改变行为吗？不改变就整句删除，而不是删词”）。codebase-design 是仓库的共享词汇底座，把 Ousterhout 的深模块哲学（”最好的模块是深的：大量功能通过小接口暴露”）封装成一组强制术语：module / interface / depth / seam / adapter / leverage / locality。它被 tdd、improve-codebase-architecture 引用。
写作上值得注意的手法：
_Avoid_ 列表。每个技能都在两个调用模式中选一个：
disable-model-invocation: true（OpenAI 生态对应 policy.allow_implicit_invocation: false），只有人类输入斜杠命令才能到达。它们的职责是编排——承载有状态的会话流程。判据本身被自我文档化在 writing-for-agents/SKILL-MECHANICS.md 里：用户调用技能零上下文载荷但只能靠人触发；模型调用技能靠 description 的措辞承担触发分支。README 用一句话总结：”User-invoked skills orchestrate; model-invoked skills hold the reusable discipline. A user-invoked skill may invoke model-invoked skills, but never another user-invoked one.”（用户调用技能编排，模型调用技能持有可复用纪律。用户调用技能可以调用模型调用技能，但绝不调用另一个用户调用技能。）
CONTEXT.md 是项目共享语言的单一事实源——一个纯词汇表，严格遵循 “totally devoid of implementation details”（完全不含实现细节），不是 spec、不是草稿本。它定义领域术语（Issue tracker / Issue / Decision ticket / Triage role），每条带 _Avoid_（避免使用的词），还有 “Flagged ambiguities”（记录曾经产生歧义、现已解决的术语）。
多个工程技能（如 tdd、diagnosing-bugs）开篇就带同一条指令：”read CONTEXT.md (if it exists)… respect ADRs in the area you’re touching”（阅读 CONTEXT.md（若存在）……遵守你改动区域的 ADR）。词汇是跨技能组合的胶水：tdd 用 codebase-design 的 seam 词汇，code-review 的 Spec 轴（见 4.4）查 spec。domain-modeling 技能负责主动构建与打磨这个词汇表，配 ADR 三条件门（难反转 + 无上下文会惊讶 + 真权衡——满足三者才写 ADR）。
值得注意的是：仓库在元层面实践自己的方法论——它自己的 CONTEXT.md 就是这个词汇表系统的产物，.out-of-scope/ 目录记录被拒绝的请求防止重复建议，ADR 记录”为什么发 Claude Code 插件而不是 Codex 插件”这种真实权衡。
几乎所有技能都使用同一种语法：显式进程闸门 + 可勾选完成标准。
这是 writing-for-agents 的 completion criteria 理论（Clarity + Demand）的直接产物——仓库在实践它讲授的理论。
sub-agent 派发是仓库的标准操作，对”什么该进 sub-agent 窗口”有清晰的经济观：
上下文经济的另一半是会话卫生规则，定义在 ask-matt/PHASE-BOUNDARIES.md：五个选项的决策树（Continue / /clear / /handoff / sub-agent / /compact），按 primary vs secondary source 的损耗经济学排序——Continue 最先排除，/clear 最便宜，/handoff 只在换 harness、换目录、换人或中途分叉时用，/compact 垫底。配套的 smart zone（约 150k token）指模型仍能清晰推理的窗口：ask-matt 建议对齐到 to-tickets 保持一个不中断的窗口，超窗即做交接或压缩。
仓库提供两种安装路径，对应两种哲学：
.claude-plugin/）：claude plugins install mattpocock-skills，作为官方市场中的托管、只读、自动更新的捆绑包——订阅而非 fork。插件只发布 engineering/ 和 productivity/ 两个推广桶里的 25 个技能，misc / in-progress / deprecated 不出现。npx skills add mattpocock/skills）：把技能文件复制进项目成为普通文件，用户拥有并可以编辑——”Nothing updates behind your back”。适用于 Codex 等所有 Agent-Skills 标准 harness。配套的安装引导：/setup-matt-pocock-skills 在每个仓库跑一次，询问 issue tracker 选择（GitHub / Linear / 本地文件）、triage 标签约定、文档保存位置。工程技能通过 setup 生成的 issue-tracker 配置文件（issue-tracker-github.md / issue-tracker-gitlab.md / issue-tracker-local.md，每个 tracker 一种）获得 tracker 抽象，统一的措辞是”应该已提供给你，否则让用户跑 /setup-matt-pocock-skills”。
两条路径怎么选：想零维护、跟随作者更新，选插件订阅；想改造成自己的技能、或使用 Codex 等非 Claude 的 harness，选 skills.sh 复制。注意 README 的警告：不要两条都装——”installing both leaves you with every skill twice”（两条都装会得到每个技能的两份）。
仓库的治理密度在同类项目中罕见：
ask-matt 路由图必须保持准确（”a router that lies” 是明确的失败模式）、scripts/link-skills.sh symlink 分发。.agents/adr/）：记录真实架构决策——0002-ship-as-a-claude-code-plugin.md 详细分析为何发 Claude Code 插件而非 Codex 插件（Codex manifest 只接受单一路径、symlink 安装即断），以及”为什么 setup 指针只放在硬依赖技能里”（软依赖技能保持 token 精简，避免 cargo-cult）。.changeset/ 管理每个技能微调（连”grilling 问题间加分隔线”都有 changeset），sync-plugin-version.mjs 同步 plugin 与 package 版本。docs/<bucket>/<skill>.md 有人类可读的文档页，统一四段结构：What it does / When to reach for it / Common questions / It’s working if。| 维度 | awesome-skills（本仓库） | mattpocock/skills |
|---|---|---|
| 技能形态 | 大而全的独立 SKILL 包（30-224 行，自成体系） | 小而组合：底层原语 + 薄路由（7-140 行，方法论只写一遍） |
| 组合机制 | 技能之间基本独立，靠 description 触发 | 路由技能显式调用原语（”Call the Skill tool twice”），ask-matt 是显式地图 |
| 共享词汇 | 无仓库级词汇文件；双语约定（中英分层）是主要规范 | CONTEXT.md 领域词汇单一事实源 + ADR，几乎所有技能都读 |
| 调用切分 | 未区分用户/模型调用 | disable-model-invocation 原则化切分，判据自我文档化 |
| 测试体系 | unit-test/ 测试金字塔（静态 + 端到端 JSONL 断言） | 几乎没有测试体系（被本仓库深扫确认的弱点） |
| 分发 | sync.sh 复制到本地三个 harness |
Claude Code 官方插件市场 + skills.sh 双轨，changeset 版本管理 |
| 深度解析 | 三篇深度解析文章（gstack / google / superpowers） | 无（以实战技能为主） |
| 独特资产 | 双语文档体系、测试金字塔、四类评审（doc-reviewer） | grilling 设计树、wayfinder 决策票地图、writing-for-agents、diagnosing-bugs 回路纪律 |
重叠区域：本仓库的 openspec-assistant（规范驱动开发）与其 to-spec → to-tickets → implement → tdd → code-review 流水线同属 SDD 阵营，但思路互补——我们的重在角色协同（架构师 / 开发 / QA）与 /opsx 指令体系，他们的重在纪律化的小步流水线。本仓库的 doc-reviewer 四类评审与其 code-review 双轴（Standards + Spec）也可互相参照。
每条结论附落地第一步——下一条读完就可以动手，具体机制回看对应小节。
ask-matt 这类路由地图防止”技能太多找不到”。
grill-with-docs 把”对齐访谈”和”词汇沉淀”绑定，一次会话同时产出共享语言与 ADR——”it might be the single coolest technique in this repo”。
_Avoid_ 避免用词），放到 CONTEXT.md，然后在技能里加一行”读 CONTEXT.md 再动手”。editorial-card-designer 的现有规则。.out-of-scope/ 防重复建议）——这让仓库的每一项方法论都经过了真实使用的检验。
CONTEXT.md（哪怕 5 个术语），并在下一次做出难反转的决策时写一条 ADR——先做这两件事，其余机制随用随加。unit-test/ 体系为新技能补测试即可。想直接体验这个仓库，不需要先读完上文：
装插件（Claude Code 用户，30 秒）：
claude plugins install mattpocock-skills
或想拥有可编辑副本（适用于 Codex 等任意 harness）：
npx skills add mattpocock/skills
两条路径二选一，不要都装（会得到每个技能的两份）。
/setup-matt-pocock-skills——回答 issue tracker、triage 标签、文档目录三个问题。只用 productivity 技能可跳过。/grill-me——体会”设计树前沿轮次”的对齐访谈（§3.1）。这是作者的招牌技能。/grill-with-docs（对齐 + 词汇沉淀）、/tdd（seam 治理）/wayfinder（决策票地图，§3.2）/diagnosing-bugs（回路纪律，§3.4）skills/productivity/writing-for-agents/SKILL.md——本仓库全部技能的质量来源（§3.5）/ask-matt，它会按主流程给你路由（§2）。