前言¶

方案讨论里常见两种失效方式：口头对齐很快，事后各执一词；或者一上来就写长篇设计文档，细节还没问清就固化了错误假设。更稳妥的做法是把「拷问式访谈」和「可版本化的文档」绑在一起：每澄清一个概念就写进术语表，真正值得留痕的取舍才落成 ADR。

下面介绍 SkillHub 上的 grill-with-docs（@user_3c6cb52e/grill-with-docs）。它给 AI Agent 一套可复用的访谈纪律，并在会话过程中维护 CONTEXT.md 与 docs/adr/，还附带若干仅依赖 Python 标准库的校验脚本，便于在追问前后做客观检查。

这是什么¶

grill-with-docs 是社区来源（source: community）的 Agent Skill，分类为 ai-agent，当前版本 1.0.0，发布者为 user_3c6cb52e。SkillHub 页面标注 requires_api_key=false，安装与使用不依赖额外 API Key。

Skill 包内的 SKILL.md 说明：核心规则衍生自 Matt Pocock 的 grill-with-docs（MIT）；本仓库在保留访谈与文档锚定规则的基础上，增加了 3 个标准库校验脚本、3 份参考文档，并在文档中提及配套 agent/command（见后文注意项）。

官方入口：

• SkillHub 展示页：https://www.skillhub.cn/skills/user_3c6cb52e/grill-with-docs
• 安装坐标：@user_3c6cb52e/grill-with-docs

核心功能¶

以下能力均来自已安装的 Skill 包（SKILL.md 与同目录文件），可按需裁剪使用。

访谈节奏与目标¶

Agent 被引导对当前计划或设计做持续追问，沿设计树逐枝深入，一次只问一个问题，并在每轮等待你的反馈后再继续。若问题可通过读代码回答，应优先探索代码库而非空问。

会话目标包括：与用户达成对方案的一致理解；在依赖关系上按决策逐项收敛。

与文档结构的配合¶

Skill 假定仓库中可能出现如下结构（单上下文或多上下文由是否存在 CONTEXT-MAP.md 区分）：

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

文件采用惰性创建：没有 CONTEXT.md 时，在首个术语澄清后再建；没有 docs/adr/ 时，在第一次需要 ADR 时再建。CONTEXT.md 仅作术语表与关系说明，不写实现细节；格式见包内 CONTEXT-FORMAT.md。ADR 使用 docs/adr/NNNN-slug.md 编号，格式见 ADR-FORMAT.md。

会话中的四条纪律¶

1. 对照术语表：用户用语与 CONTEXT.md 冲突时立即指出，并要求选定 canonical 含义。
2. 收紧模糊表述：对 overloaded 词汇提议精确术语（例如区分 Customer 与 User）。
3. 用具体场景压测：构造边界场景，检验领域关系是否自洽。
4. 与代码交叉验证：陈述与实现不一致时，把矛盾点摊开让用户裁定。

术语一旦落定，应当场更新 CONTEXT.md，不要攒批。ADR 仅在同时满足「难以逆转」「缺上下文会显得反常」「源于真实权衡」三项时才建议撰写。

包装层工具（stdlib）¶

Skill 提供三个 Python 脚本，用于访谈前后的确定性检查：

推荐工作流（摘自 SKILL.md）：

1. 开场前：若已有 CONTEXT.md / docs/adr/，先跑 linter 与 scanner；对 src/ 跑 glossary 一致性，把告警当作首轮追问素材。
2. 进行中：维持「一轮一问」；改术语后必要时重跑 linter；新增 ADR 后重跑 adr_scanner.py。
3. 收尾：再跑一遍 glossary_code_consistency.py，汇总新增术语、ADR 与未决项。

示例命令（在仓库根目录，路径按你的 Skill 安装位置调整）：

python3 scripts/context_md_linter.py CONTEXT.md
python3 scripts/adr_scanner.py docs/adr/
python3 scripts/glossary_code_consistency.py --context CONTEXT.md --code src/

安装与启用¶

安装 SkillHub CLI¶

若本机尚未安装，可按 SkillHub 官方说明执行（完整安装或仅 CLI）：

command -v skillhub && skillhub --version

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

文档：https://skillhub.cn/install/skillhub.md

安装 grill-with-docs¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。

skillhub install grill-with-docs --namespace user_3c6cb52e --dir <你的 skills 目录>

常见路径（来自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

SKILL.md frontmatter 中列出的框架还包括 Hermes Agent、OpenClaw、QClaw、WorkBuddy 等；各客户端以「能加载该目录下的 SKILL.md」为准，具体菜单名称因产品而异。

安装完成后，在 Agent 中启用或引用 @user_3c6cb52e/grill-with-docs，让模型按 SKILL.md 中的 <what-to-do> 与 <supporting-info> 执行即可。

典型用法¶

用自然语言启动一场「带文档的拷问」¶

把 Skill 加载到 Agent 后，可直接给出与上游一致的意图（SKILL.md 原文要点）：

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask the questions one at a time, waiting for feedback on each question before continuing. If a question can be answered by exploring the codebase, explore the codebase instead.

中文场景下可等价表述为：请针对当前方案逐条追问，每轮一个问题并给出你的推荐答案；能查代码就先查代码；澄清的术语写入 CONTEXT.md，满足 ADR 三条件时再写 docs/adr/。

在已有 CONTEXT 的仓库里续谈¶

若根目录已有 CONTEXT.md，先跑 linter，再开始访谈，可减少「术语表本身格式不对」带来的噪音：

python3 path/to/grill-with-docs/scripts/context_md_linter.py CONTEXT.md

Agent 在会话中应持续对照 glossary，并在你确认后即时改文件，而不是会话结束再补文档。

适用场景与注意¶

适合谁

• 需要在开工前把领域语言、边界场景和关键取舍讲清楚的技术负责人或结对小组。
• 希望 CONTEXT.md 与 ADR 与代码同仓维护、可 diff 可评审的团队。

限制与注意

• SkillHub 简介仅一句泛化描述；实际行为以包内 SKILL.md 为准。安装后建议通读 CONTEXT-FORMAT.md、ADR-FORMAT.md 与 references/ 下的说明。
• SKILL.md 提到 companion：cs-grill-with-docs agent 与 /cs:grill-with-docs 命令，路径指向包外的 ../../agents/、../../commands/。当前 SkillHub 下载包内主要为 SKILL.md、格式说明、参考文档与 scripts/；若你的环境没有对应 command 定义，直接依赖 Skill 正文即可。
• 社区页统计（以抓取资料为准）：评分 100000，下载 10810，安装计数 0；数据会随平台更新变化，引用时以 SkillHub 页面为准。
• 校验脚本为辅助手段，不能替代人对 trade-off 的判断；访谈仍应「一轮一问」，避免模型一次性抛出过长问卷。

结尾¶

grill-with-docs 把「高强度方案访谈」和「术语表 + ADR」绑在同一套 Agent 纪律里，并用标准库脚本把文档与代码的一致性做成可重复检查的步骤。若你正在用 Cursor、Claude Code 或 Codex 等支持 Skills 的客户端，可通过 SkillHub 安装 @user_3c6cb52e/grill-with-docs，在真实仓库里从一场单问单答的 grilling 开始，把共识写进 CONTEXT.md 和 docs/adr/。

官方地址：https://www.skillhub.cn/skills/user_3c6cb52e/grill-with-docs