Agent架构，know-how怎么设计？（7/12）

准备起一个新的系列《Agent原理，架构与实践》。目标不贪心：

1. 希望每篇文章有1-2个点能让大家有收获；

2. 希望不被骂；

本期第七讲，咱们开始。

上一讲咱们聊了工具设计——工具是Agent的手，出参入参，一定程度上决定手好不好使。可光有手还不行，Agent还得知道"某个特定的场景，要怎么做事"——需求文档按什么格式写？原型按什么规范画？代码按什么标准出？这些经验诀窍，Agent要如何沉淀呢？

【1】问题一：垂直业务Agent，know-how能不能直接塞进系统提示词？

我们的第一反应往往是：把所有know-how塞进系统提示词。sdd-site-agent三个规范往系统提示词里一扔，Agent每次都看得到，岂不省事？

且慢，第3讲聊的啥忘了吗？假设每个规范2000个token，三个全常驻上下文，每轮调用白烧6000个token——注意力被稀释，token成本翻很多倍。

真实的情况是：

只有写需求这一步，需要需求规范；

只有画原型这一步，需要原型规范；

只有做架构这一步，需要架构规范。

将全部know-how塞进系统提示词，大部分情况下，它们都会成为与任务无关的噪音。

那正确的姿势是什么？第3讲已经给过答案，按需加载。而skill，正是"按需加载，渐进式披露"的一种标准化实现。

第一层，元数据（常驻上下文，几十个token）：skill名字+一句话说明"什么时候该用它"；

第二层，skill正文（skill.md，触发后才载入）：这个know-how的完整写法；

第三层，资源层（用到才读）：模板、示例、checklist，存在文件里；

第3讲提到的Agent长期记忆，skill就是一种典型的形式，业务场景下的know-how，它写在外部文件里，不占上下文，需要时按指针取回。

【2】问题二：Agent架构里，工具和skill，怎么分工？

上一讲咱们给Agent造了手（工具），这一讲又给了它know-how（skill）。这两者的区别是什么呢？

工具=手：动作能力，能读、能写、能跑命令。

skill=know-how：做事方法，需求怎么写、代码怎么出、什么算好。

团队新来一位同事，咱们给他两样东西：

一是命令权限：能访问代码库、能提PR、能跑流水线，这是工具；

二是团队文档：需求文档模板、代码规范、评审清单，这是skill。

只给命令权限，不给文档，他能干但不知道怎么干才对；只给文档不给命令权限，他知道该怎么干但什么也干不了。

落到咱们的mini-agent设计上：第6讲的read_spec工具负责"能读到规范文件"，这一讲的规范skill负责"规范里写了什么、怎么用"。

一个垂直Agent，工具和skill相辅相成，一起配合方能完成用户交给的任务。

【3】问题三：一个好skill，怎么写出来？

skill系列文章，写了7篇，这里咱们来个速成版，三个要点公式：

要点一：description是触发器，而不是摘要。它决定Agent什么时候想起用这个skill。写给模型看的：什么时候用+用来干什么。

要点二：正文是路由器，而不是知识仓库。正文只放主干，细节用指针指向第三层资源。

要点三：资源按需加载。模板、示例、checklist都放文件里，用到哪份，读哪份。

skill系列花了7篇文章深入聊过skill，这里就不再展开了。

【4】我们的sdd-site-agent：三个规范可以用三个skill来实现。

sdd-site-agent需要需求规范、原型规范、架构规范三类know-how。用今天的框架看：

1. 需求规范，requirement-spec skill，触发：写需求文档时，资源：模板+缺陷清单；

2. 原型规范，prototype-spec skill，触发：画原型时，资源：原型模板+组件库；

3. 架构规范，architecture-spec skill，触发：出技术方案时，资源：架构模板+决策清单；

三个规范，就是三个skill。此时，sdd-site-agent就拥有了"团队的全部know-how"：写需求时加载需求规范，设计原型时加载原型规范，出技术方案时载架构规范。每次只带当前步骤需要的那一份，上下文干净，输出对齐团队标准。

这些skill文件就是sdd-site-agent的长期记忆资产，它们不会随着对话结束而消失，它们是咱们团队的规范沉淀。

【5】简单总结

今天这一讲是整个系列挺重要的一块，前面六讲的内容，都能在这里拼起来：

1. know-how别全塞系统提示词，元数据常驻，正文和资源用时才载；

2. 工具是手，skill是know-how：手负责如何执行，know-how负责如何做对；

3. description是触发器不是摘要，正文是路由器不是仓库，资源按需加载；

补充阅读：《Agent skill规范》

https://agentskills.io/specification

工具有了（第6讲），规范也有了（这一讲），sdd-site-agent已经能干活了。可任务一大，让它一个人又写需求、又画原型、又出方案、又写代码，它还是会乱——什么时候该把这些角色拆给不同的Agent？下一讲，咱们聊聊多Agent编排。

欢迎持续关注，让我们一起，一步一步，实现自己业务专属的mini-agent。

知其然，知其所以然。

思路比结论更重要。

===全文完==

PS：公众号只能贴静态图文，无法用js实时互动，在线版设计了课后习题与实操演练，欢迎阅读原文体验。