在 agent 产品里，skill 很容易变成一个万能词。只要是给 AI 看的说明、流程、提示、规则，都可能被叫成 skill。

但在 SketchUp Agent Harness 这样的产品里，skill 不是一个松散文档夹。它是产品架构的一部分。

SAH 至少有三层 skill：product runtime skills、project/session dynamic runtime skills、maintainer development skills。这三层必须分开。

Product runtime skills 是产品表面

Product runtime skills 是随产品交付给设计师的运行时能力。它们可以描述空间规划、组件搜索、语义定位、导入图纸、设计规则、视觉反馈和布局验证。

这些 skills 的目标读者不是维护者，而是正在用 agent CLI 操作设计项目的 agent。

所以它们必须满足几个要求：

  • 能通过产品安装或插件机制进入用户可加载的位置；
  • 不依赖维护者源码路径；
  • 不包含某个客户项目或某张图纸的局部事实；
  • 不泄露产品开发过程中的临时实现细节；
  • 能长期作为产品行为的一部分被测试和维护。

Product runtime skill 是产品 surface。它不是开发者随手写的 prompt。

Dynamic runtime skills 是项目局部记忆

设计师使用产品时，某些信息只对当前项目有意义。

例如某张导入图纸里的符号图例、设计师对某次导入做过的纠正、当前项目的房间命名习惯、某个 source 的低置信度区域、用户明确说“这个项目后续都按这个偏好处理”。

这些信息可以帮助 agent 在当前项目继续工作，但它们不应进入产品 baseline。

它们适合成为 project/session dynamic runtime skills，保存在当前设计项目支持的 agent skill 位置。它们是 guidance，不是 canonical truth。真正的结构化事实仍然在 design_model.json 和 imports/ 里。

Development skills 属于维护者工作区

维护者也需要 skills，但那是另一类东西。

开发 skills 服务产品开发：架构决策、Ruby bridge 修改、MCP tools、release smoke、runtime skill authoring、issue triage、语言审计等。

这些 skills 不应该放进产品 repo 的 skills/ 目录，也不应该被产品插件 manifest 暴露给设计师。

原因很简单：维护者 workflow 和设计师 runtime 是两种不同上下文。混在一起会让用户运行时看到维护者实现细节，也会让开发过程中的临时判断影响产品行为。

三层混淆会造成什么问题

如果 product runtime skill 写入 source-specific correction，下一位用户可能被上一张图纸的错误经验影响。

如果 dynamic runtime skill 被提交到产品 repo，局部记忆会变成全局行为。

如果 development skill 被安装给设计师，agent 可能按维护者开发逻辑行动，而不是按设计师工作流行动。

如果 product runtime skill 只存在源码目录，不通过安装机制分发，设计师就被迫 clone repo 或复制文件，产品边界就坏了。

这些不是文档整理问题，而是 product governance 问题。

Skill 不应该替代 truth

Dynamic runtime skills 也不应该替代 design_model.json。

Skill 可以告诉 agent：“这个项目里，厨房图纸符号 X 表示某种门洞”。但真正的门洞、墙体、尺寸、source provenance 应该进入 structured truth 或 import evidence。

如果把事实都写进 skill，项目会失去可验证状态。Agent 可能看懂提示，但工具层无法 validate、diff、execute 或 repair。

所以 skill 是 guidance，truth 是 state。二者不能互相替代。

什么时候局部经验可以晋升

有些 dynamic runtime memory 可能暴露出产品缺口。

例如多个项目都需要同一种 source symbol handling，或者多个设计师都以同样方式纠正导入结果。这时不能直接复制某个项目的 dynamic skill 到产品 baseline。

更合理的晋升路径是：抽象通用模式，去掉 source-specific facts，增加多样化测试，更新 product code、docs 或 baseline runtime skills，必要时再沉淀为中央知识对象。

这就是 skill governance 在产品架构里的作用。

Source trace