23 万 star 的 skills 仓库最该抄的：写码前让 agent 先审问你 20 分钟

先承认一件事：我昨天又被 coding agent 坑了。给它一句"把用户登录改成微信授权"，它埋头写了半天，交回来一个登录页——可我要的是后端改接第三方 OAuth，跟前端半点关系没有。

问题从来不在模型有多笨，在于我给的是一句话，剩下的全指望它猜。猜需求就是赌概率，赌对了算运气，赌错了是常态。

mattpocock 的 skills 仓库，治的就是这个病。

一个 23.1 万 star 的仓库，最受欢迎的是两个"审问"skill

mattpocock 是 TypeScript 圈绕不开的名字。他把自己每天在用的 agent 配置（.agents 目录）整个开源了出来，2026 年 2 月 3 日建仓，到今天 231,171 star、19,741 fork，MIT 协议，半年多涨到这个量级。仓库描述就一句大白话：Skills for Real Engineers. Straight from my .agents directory.——他不是给你看演示，是把他天天用的东西直接扔出来。

仓库里一共 39 个 skill。README 自己写：最受欢迎的两个就是 grill-me 和 grill-with-docs。今天拆 grill-with-docs。

一句话说清它是干什么的：写码前，让 agent 用面试的方式把你审问到"你们俩对要做的事达成了一致"，而且边问边把项目词汇和关键决策写进仓库文件。

它的 SKILL.md 全文只有一行：

Call the Skill tool twice, for “grilling” and “domain-modeling”.

一个 skill 委托给两个底层 skill：grilling 负责审问，domain-modeling 负责把结论写下来。这是第一个反常识——它根本不是什么精妙提示词，而是"面试算法 + 文档纪律"两个组件的组合。文档自己也承认，这行委托是它最大的故障点：依赖没加载全，grilling 就退化成无差别问题轰炸；domain-modeling 没加载上，就是"聊得挺好，但什么也没留下来"。

grilling：面试不是聊天，是算法

grilling 的核心不是"多问几句"，而是把提问本身变成一个有明确结束条件的算法：

• 设计树：把方案拆成一棵决策树，每个决策往下挂着它依赖的子决策。
• frontier（前沿）：只有"前提已经定下来"的决策，才是现在能问的问题。前提没定的，问了也是白问。
• 一轮问完整个 frontier：把这一层能问的问题一次全问掉，每个问题编号、附一个推荐答案，然后闭嘴等用户回答。不挤牙膏，不问一个等一个。
• 用户的回答会重塑这棵树，把 frontier 往外推，解锁下一批问题，进入下一轮。
• 结束条件：frontier 空了——每个分支都走完，没有一处"没问就默认"的角落，才算对齐，确认之后才动手。

两个纪律值得单拎出来。找事实是 agent 的活，不是用户的活：要查文件系统、接口、代码库，派子 agent 去查，别拿这种问题烦用户；决策是用户的活：每个决策都摆到你面前，等你拍板。它不该问你任何自己能查到的东西。

给你一份可以直接抄的轮询模板，来自 SKILL.md 的原始格式：

1
2
3
4
5

❓ Q1 - 决策A：推荐答案A
➡️ 你的回答
---
❓ Q2 - 决策B：推荐答案B
➡️ 你的回答

规则就四条：一轮只问当前 frontier；每题编号；每题给推荐答案；问完一整轮才等回答。它把"澄清需求"从一门玄学变成了一次广度优先遍历——这层设计，是这仓库里最值得抄的东西。

domain-modeling：边问边写，不是问完再总结

审问不是白问。每敲定一个术语，当场写进 CONTEXT.md——不攒批，随问随写。CONTEXT.md 是术语表，不是 spec：一个词一到两句定义，加一行 _Avoid_ 列出你决定放弃的说法。

README 给了个特别直观的例子。某个课程仓库里，“materialization cascade” 这一个词，取代了下面这整整一句：

“There’s a problem when a lesson inside a section of a course is made ‘real’ (i.e. given a spot in the file system)”

词一压缩，后面每一轮会话都少理解成本。术语表的价值就在这里：项目的词，一次敲定，你、你的同事、你的 agent 从此说同一种话，不用每次都重新推导。

决策的另一个去处是 ADR，但门槛高得多——三个条件同时满足才写：难反悔、没有上下文会让人惊讶、真是权衡之后的选择。缺一个都不写。所以一次成功的会话可能一个 ADR 都没有，这是设计，不是故障。

反转：这套东西真的让 agent 更强吗

先说最刺耳的那个质疑。作者自己引了公开反驳：一个术语和它的白话解释，喂给模型可能得到一模一样的结果；词汇真正压缩的是人跟人之间的沟通成本。按这个最刻薄的理解，术语表对 agent 的增益存疑，但它让"你、同事、agent"三方对齐这件事本身没变。作者的结论是：就算按这个读法，术语表依然值得，只是价值挪了位置。

再说最大的坑。作者列出的被报最多的问题，不是审问太长，而是 CONTEXT.md 会失控：一旦放任模型往里写，术语表会变成流水账、变成伪 spec，500 行、1000 行地长。规则就一句——它是术语表，别的都不是。作者的修法也很朴素：让 agent 自己删，原话是 “make my CONTEXT.md more concise and remove any implementation details from it”。

还有个更扎心的。审问出来的边界、默认值、异常场景，大多数只留在对话里，换个会话就没了。这是作者承认的最大实质投诉——没有一本账把每个答案追到 spec、ticket、test。它的补救办法是：会话结束别急着清上下文，把整段对话直接喂给链上的下一个 skill to-spec，让它合成正式 spec。

它处在整条构建链的最前面

grill-with-docs 不是一个孤立的技巧，它是作者主构建链的链头：

1

grill-with-docs → to-spec → to-tickets → implement → code-review

它在任何 spec 落盘之前运行，产出的是"共同理解 + 已统一的词汇"，后面的 to-spec 拿到这些就能直接合成，不用再采访你一遍。跟它邻居的几个 skill 怎么选，文档给了张表：

横向比一下你现在的日常做法：直接开干是猜需求，写错了再改；自己手写需求文档是你写一堆、agent 读，但你的词和它的词未必对齐；grill-with-docs 是 agent 问、你答，词当场定、决策当场记——对齐发生在写码之前，而不是写完代码的 review 之后。

真实场景里它长这样：给一个没有文档的老仓库，直接说 “help me document my repo” 或 “scaffold my existing repo with a CONTEXT.md”，它会读代码、然后开始审问你。文档里有个用户案例：一个没有任何领域文档的老仓库，被审问了 50+ 个问题才把 CONTEXT.md 建成型。听着吓人，但你想想，那 50 个问题本来就是你迟早要在代码 review 里踩的坑。

上手成本很低。Claude Code 一条命令装进官方 marketplace：

1

claude plugins install mattpocock-skills

Codex 和其他 agent 用同一套安装器：npx skills@latest add mattpocock/skills，装完在仓库里跑一次 /setup-matt-pocock-skills 配置 issue tracker 和文档目录，就能用了。注意它是 user-invoked：SKILL.md 里写了 disable-model-invocation: true，你不输入 /grill-with-docs，它不会自己冒出来——所以真正的门槛不是安装，是养成"改代码之前先审问一轮"的习惯。

丑话说前头

• 依赖加载有已知 bug：在别的编排层（spec 驱动、多 agent 框架）里跑，文件写入可能静默不执行——审问照跑，但 CONTEXT.md 和 ADR 就是不出来。作者自己标了"filed and unfixed"，跑完记得检查工作目录。
• 名字确实烂：作者承认没人喜欢 grill-with-docs 这名字，有提案改成更诚实的 grill-domain-model，一直没动。
• CONTEXT.md 的命名也吵：既然"它是术语表"，为啥不叫 GLOSSARY.md？有人 fork 了仓库就为改名。作者的理由是 CONTEXT-MAP 在多上下文仓库里读起来更顺。
• 术语表对 agent 的增益有争议（就是前面那个反转），别指望它立竿见影提升模型能力，先把它当"对齐工具"用。
• 配置是仓库级的，写进 docs/agents/，每仓库一份，没有全局模式——作者的态度就一句：Config is death. 多仓库用户会觉得烦。

如果你现在用 Claude Code 或 Codex，今天就能做的最小实验：挑一个下周要改的模块，先 /grill-with-docs 审问一轮，看看它写出来的 CONTEXT.md 是不是比你脑子里的口头描述更准。把"猜需求"换成"问需求"，是 coding agent 时代最便宜的一笔质量投资。

搬砖程序员带你飞，专注 Golang / AI / 后端。每天一篇，讲清楚一个技术真相。