grill-with-docs

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 4 处。

Entry SHA-256: 610d091047bcfb9db0f75c057d15538481a721111579fc5ec7f83ad9131a2165

2. Why This Skill Is Clever

一句话核心机制

这是一层极薄的组合适配器：它启动 /grilling 的递进式访谈，同时把 /domain-modeling 的术语与决策记录纪律注入访谈过程，让“想清楚”和“写下来”发生在同一会话里。

触发与边界

• Direct source： frontmatter 明确写着 disable-model-invocation: true，所以它是由人显式启动的工作流，而不是模型自行挑选的后台能力。
• Supporting context： agents/openai.yaml 同样设置 policy.allow_implicit_invocation: false；仓库文档把入口描述为输入 /grill-with-docs。
• 适用边界： 它面向需要被追问、澄清，并希望同步沉淀领域文档的计划或设计。若只想进行不落盘的思考访谈，组合中的文档纪律会显得过重。
• 不是 strict pure wrapper： 原文同时点名 /grilling 与 /domain-modeling 两个依赖，不满足“把全部工作委托给恰好一个实现技能”的展开条件。因此本报告的原文区只展示所选 SKILL.md，两个依赖仅作为分析证据。

信息架构 / 执行顺序

1. 人显式调用 grill-with-docs。
2. Run a/grillingsession 把控制流交给访谈原语：围绕尚未解决的设计决策持续追问。
3. using the/domain-modelingskill 为同一个会话叠加领域建模纪律：澄清词义、核对代码、按需更新 glossary，并只为真正重要的取舍保留 ADR。
4. 会话的认知结果不只停留在上下文窗口；符合条件的术语和决策会在推进过程中变成仓库内的持久工件。
5. 完成标准仍来自两个依赖：访谈要收敛到共享理解，文档输出则受严格内容边界和资格门槛约束。

第 2–5 步的具体机制来自 supporting context（grilling、domain-modeling 与配套文档），不是这份一行式原文自身展开的规则。

最巧妙的设计点

1. 把调用权限写进元数据 — disable-model-invocation: true
   - Direct source： 入口边界是机器可读字段，不依赖描述性文字。
   - Interpretation： 高压访谈会打断用户当前流程；要求显式调用能避免模型“自作主张”开始连环追问。

2. 复用成熟控制流 — Run a/grillingsession
   - Direct source： 它不复制访谈算法，只引用已有会话原语。
   - Supporting context： /grilling 用 design tree、frontier 和 rounds 管理问题依赖，并把事实查找与用户决策分开。
   - Interpretation： 复用避免两个采访流程逐渐产生不同的提问节奏和完成条件。

3. 用第二个技能注入持久副作用 — using the/domain-modelingskill
   - Direct source： 领域建模不是访谈结束后的另一步，而是访谈运行时采用的纪律。
   - Supporting context： /domain-modeling 要求术语一旦明确就就地更新 CONTEXT.md，ADR 则必须同时满足难逆转、缺上下文会意外、存在真实权衡三项门槛。
   - Interpretation： 这把文档从“会后可能补写”变成认知收敛过程的一部分，减少决策与记录之间的失真窗口。

4. 描述直接承诺双重结果 — which also creates docs ... as we go
   - Direct source： 一句话同时交代体验（relentless interview）、目标（sharpen）和持续产物（docs）。
   - Interpretation： 对一个极薄的组合技能而言，这种描述比重复依赖细节更有效：用户先知道它为何存在，再由依赖技能承担机制。

防失败机制与 trade-off

明确的不变量

• Direct source： 禁止模型隐式调用；执行的是 /grilling 会话，并同时使用 /domain-modeling。
• Supporting context： /grilling 不允许把可自行查到的事实甩给用户，也不应在共享理解确认前行动；/domain-modeling 要求 glossary 不含实现细节，并对 ADR 使用三重门槛。

它预防的失败

• 避免为“带文档的访谈”复制一套容易漂移的采访算法。
• 避免访谈结论只留在聊天上下文、稍后重写时被弱化。
• 避免模型未经邀请就启动高摩擦的密集追问。

代价与可移植性风险

• 这份入口本身几乎没有降级策略；任一依赖未被宿主正确解析，组合行为就可能残缺。
• /skill-name 调用、disable-model-invocation 和 OpenAI policy 文件都属于具体 harness 的约定；移植到其他代理框架时必须重新实现依赖解析与调用权限。
• “边谈边写”会产生真实文件副作用，适合单写者或有明确文档治理的仓库；多人并行时需要额外的冲突、引用和陈旧性检查。
• 入口过薄提升复用，但也降低局部可读性：只读这一行无法知道访谈轮次、文档格式和 ADR 门槛，运行时必须可靠加载两个依赖。

可迁移原则

1. 组合，不复制： 新工作流若只是“既有控制流 + 一项横切纪律”，用适配器连接它们，不要复制双方正文。
2. 副作用要显式： 技能会写文件、改状态或打断用户时，把权限边界放进机器可读元数据。
3. 让记录贴近决策时刻： 在认识刚收敛时持久化，减少会后整理造成的信息损耗。
4. 薄入口也要写清价值差异： 描述应回答“组合后新增了什么用户价值”，而不是只罗列依赖名。
5. 为组合依赖设计失败模式： 在其他 harness 中移植时，增加依赖存在性检查和清晰报错，避免只运行一半。

今日实践题

如果你要把“代码评审”与“安全威胁建模”组合成一个新技能，哪些内容应留在薄入口，哪些规则必须继续由两个底层技能分别拥有？请再写出一个能够阻止隐式副作用的机器可读边界。

Evidence note

• Direct source： 本报告原文区中的 grill-with-docs/SKILL.md，包括 frontmatter、描述和唯一执行句。
• Supporting context： 仅读取并用于解释架构的 grilling/SKILL.md、domain-modeling/SKILL.md、agents/openai.yaml 与仓库 docs 页面；它们不是所选原文，也未混入双语 reader。
• Interpretation： 关于组合适配器、失真窗口、依赖脆弱性、多人治理与迁移原则的判断，是基于上述证据的工程分析。