---

SKILL.md, not in references

category: skill-design

problem_type: architecture_pattern

severity: medium

- Authoring a skill that ends in an AskUserQuestion-style menu

- Reviewing a skill where the agent renders a menu and stops

tags: [skill-design, menu-routing, skill-md-vs-references, ce-plan,

related_issue: https://github.com/EveryInc/compound-engineering-plugin/issues/714

```

这段 frontmatter 的作用不是让人读起来更工整，而是让 Agent 更容易检索。它的设计是提高机器可读性，降低 Agent 的检索开销：

- `title`与`tags`：作为第一层过滤的结构化字段初筛，Agent 不用执行文件 I/O 读正文，只要通过并发`grep`元数据就能完成高速匹配。

- `module`与`component`：来精准判断当前开发的上下文是否触碰到了相同的底层模块。

- `applies_when`：提供显式的自描述触发条件，未来的 Agent 读取这几行就能在几毫秒内判定当前任务是否命中此规则。

从线上仓库的实测数据来看，Thinkroom 当前已有的 35 个有效 Leanings 中，知识轨道的文档占据了绝大多数。整个系统运转的重心，已经从单纯的“线上故障修补记录”，演进成了“团队共享的工程判断准则库”。


图 2：docs/solutions census 图。35 个 Learning 在 skill-design、best-practices、integrations 等类别中的分布。

如何获取一个 Learning

知识沉淀的核心痛点在于“时效性引起的熵增”。

在 Bug 刚修复或技术决策刚达成的片刻，路径排查、失败尝试的排除、真正的根因以及 Diff 细节，在当前上下文窗口中的信息保真度最高。因此，这时候原地生成的 Learning 有非常高的信息密度。一旦到周报或复盘会时再补写，大量关键链路信息就会丢失，最终降级为“修复某配置错误”这种低价值的流水账，对后续的 Agent 指导产生不了大的作用。

因此，系统需要将知识捕获硬编码为调试流水线的终点。

在测试跑通的现场，工程师可以直接触发`/ce-compound`指令。系统会随之启动一套多 Agent 并发提取、单点串行写入的架构：

- **Context 分析器**：负责判定 Category 分类、生成标准文件名并初始化 Frontmatter 结构；

- **解决方案提取器**：全量审计当前 Session 对话、代码 Diff 以及测试断言结果，结构化提炼出问题表象、排查路径、最终解法与预防手段；

- **相关文档查重器**：并发检索已有的`docs/solutions/`语料，做重叠度交叉比对，提示合并或引用，防御知识碎片化。

这套存储拓扑背后有一个工程评判准则：丢失后会让团队感到心疼、无法一键找回的隐性知识，必须进入 Git 接受审查；而随时可以低成本重新派生的物理快照，应当留在临时目录。

检索机制

许多复盘文档最终沦为“Wiki 坟墓”，本质上是因为传统检索是在考验团队的纪律性。Thinkroom 的检索设计直接将人进行解耦，**放弃向人推送（Push），改为由工作流在关键节点主动拉取（Pull）**。

检索系统通过底层的`learnings-researcher`协议，将历史知识的检索彻底硬编码到了日常研发最频繁使用的 5 个核心 Agent 技能中：

- **`/ce-plan`**（规划阶段）：在结构化开发计划之前自动检索，将历史经验转化为当前的硬性约束条件与关键技术决策；

- **`/ce-brainstorm`**（需求梳理）：在对齐需求时自动检索，利用过去的死胡同来划分当前设计的边界；

- **`/ce-code-review`**（自动化审计）：作为 Always-on Reviewer 逐行扫描 Diff，把历史 Learning 直接转化为当前的审查判断；

- **`/ce-debug`**（调试排查）：在报错并进行根因假设时，让已知根因模式直接跳过常规排查排队，实现优先匹配；

- **`/ce-ideate`**（想法探索）：在生成构想时自动接入，避开历史上已经验证失败的技术方向；

这种低成本的过滤机制带来了两个工程实效：

- 极致的响应速度：即使未来面对成百上千篇 Learning，也无需支付高昂的 Token 和时间开销去深读全量语料。

- 极低的上下文噪声：Agent 在当前任务中面对的是高度提炼的确定性约束，有效避免了长文本导致的注意力失焦。

`。


图 6：read time、write time、on demand 三种刷新节奏

实战闭环案例：一个新技能特征的完整流转

为了看清这套系统在日常研发中是如何流转的，我们以 Thinkroom 最近刚上线的一个新技能`/ce-explain`为例。

在这整个端到端的合入过程中，系统在各个阶段自动触发了知识系统，整个演进过程完全不需要人类。

- Brainstorm 阶段（需求梳理）：在没有向开发者提出任何问题之前，Agent 先从共享缓存中拉取了当前仓库的画像快照（`repo-profile cache`）。在此次运行中，由于没有命中缓存，系统在后台动态派生了新的快照并将其持久化，以便供接下来的 9 个关联技能直接使用。有了这个快照，Agent 得以快速扫描现有系统，提前摸清了所有的历史相似设计。

- Plan 阶段：在规划阶段，检索协议自动捞出了 5 篇历史 Learning 注入上下文。在撰写技术方案时，其中 3 篇被标记为“必须遵循”的硬性条件，包括：之前踩坑换来的菜单内联路由机制（Issue #714 的血泪遗产）、`$ARGUMENTS`可移植性，以及`SKILL_DIR`脚本锚定规则。最终，这 3 篇 Learning 沉淀为了本轮开发计划中“关键技术决策”的核心依据。

- Implementation 阶段（代码实现）：在真正的编码阶段，Agent 严格执行了规划中的设计约束。不仅如此，针对历史 Learning 中提到的各类边界防御手段，新技能在生成的过程中，还在测试侧对应长出了属于它自己的镜像回归测试。

- Review 阶段（自动化审查）：在提交代码后的审计阶段，自动化 Review 工具对照 8 篇相关的历史 Learning 全量扫描了本次合入的 Diff，给出了全部通过的判断。在此期间发生了一个插曲：一名人类工程师曾提出一个看似更优雅的优化意见，但 Review 验证器利用由 Learning 沉淀演进来的`AGENTS.md`直接驳回了该提议，因为那个改动会重新引入历史上的已知漏洞。记忆在此处不单单是指引工作，而是在防御代码回退。

- Vocabulary & Residue（概念沉淀与演进残留）：当 Brainstorm 阶段刚刚敲定需求边界的瞬间，新抽离出的概念`Explainer`与`Check-in`就已经被同步写入了领域概念字典`CONCEPTS.md`中。同时，本次 Review 遗留下来一个非阻断式的优化项，被团队故意延后并提为了 Issue #1057。


## 小结

在 Agent 工作流中，系统的长期价值不仅取决于单个任务的执行速度，更取决于它能否将本次任务的经验无缝留给下一次。如果每次修复都流失在当前会话窗口里，哪怕大模型再聪明，团队在工程层面上依然会陷入反复“失忆”的死循环。

这套方案最核心的借鉴意义，不在于倡导大家去“多写文档”，而在于把知识流动的管道彻底建在现有工作流里：在修完问题时原地捕获，做计划前深度检索，写代码时强制遵守，审查 Diff 时自动化校验，发现过期时精准刷新。知识沉淀不再是额外的人力负担，而是变成了智能体工程系统天然的一部分。

传统软件工程里，我们习惯于复用代码和组件。而在迈向智能体工作流的进程中，更值得被复用和固化的，是那些从真实工程泥潭里提炼出来的技术判断、团队约定与架构经验。

一次 Bug 修复结束的地方，本就应当是下一次开发变得更轻松的开始。","createTime":1783489945,"ext":{"closeTextLink":0,"comment_ban":0,"description":"","focusRead":0},"favNum":0,"html":"","isOriginal":0,"likeNum":0,