← 返回博客
AI Agent

AI Agent 的"技能包"设计哲学：什么该封装，什么该扔掉

2025-03-22

如果换一个项目就不能用了，那它不是 Skill，而是 Playbook。

为什么 Skill 是最重要的组件

在五组件架构中，如果让我只保留一个组件，我会保留 Skill。

原因很简单：Agent 会因为组织结构调整而重新划分，Command 会因为业务流程变化而重写，Rule 会随着合规要求更新，MCP 会因为工具链切换而替换。但一个好的 Skill——比如"如何做等价类划分"、"如何评估风险优先级"——这些方法论的半衰期远超任何具体的项目和工具。

Skill 是 AI Agent 系统的核心知识资产。 设计好 Skill，就是在积累可复用的智力基础设施。

Skill 的四个"不是"

1. Skill 不是 Agent 的 prompt 片段

很多人的第一反应是把 Agent 的 system prompt 拆成几段，每段叫一个"Skill"。这只是文本分割，不是能力拆分。真正的 Skill 应该是独立于任何 Agent 的——不同的 Agent 可以调用同一个 Skill。

2. Skill 不是工作流

"先分析需求，再设计用例，最后写自动化脚本"——这不是一个 Skill，这是一个 Command（工作流）。Skill 只描述"如何做某一件事"，不描述"什么时候做"或"做完之后做什么"。

3. Skill 不是工具的封装

"如何使用 Jira API 创建 Issue"不是 Skill，这是 MCP 集成。Skill 是认知能力——"如何判断一个 bug 的优先级"才是 Skill。

4. Skill 不是业务规则的容器

"交易金额超过 $10,000 需要额外审批"不是 Skill，这是 Rule。

业务无关性：最关键的设计约束

Skill 的黄金法则：如果换一个项目就不能用了，那它不是 Skill，而是 Playbook。

看起来是 Skill 的东西 问题 应该怎么做
"分析 DeFi 协议的安全风险" 绑定了特定领域 拆分为通用的 "risk_assessment" + DeFi 领域的 domain Rule
"生成符合 XX 格式的测试报告" 绑定了特定输出格式 Skill 定义结构化数据，格式化交给 template
"检查 Spring Boot 接口的参数校验" 绑定了特定技术栈 标注为"平台特定 Skill"

Skill 的标准封装：能力契约

每个 Skill 是一个目录，核心是一个 SKILL.md 文件：

my_skill/
├── SKILL.md          # 必需：能力契约
├── assets/           # 可选：模板、示例输出
├── scripts/          # 可选：结构化输出生成
└── references/       # 可选：外部规范、字段字典

SKILL.md 七个必选章节：

  1. Purpose——一句话说清楚解决什么问题
  2. Inputs——明确输入的来源、格式、降级处理
  3. Outputs——结构化的输出定义（JSON Schema）
  4. Procedure——最低 3 步的可执行流程
  5. Guardrails——声明"不做什么"
  6. Examples——至少 2 个完整示例
  7. Metadata——版本、依赖、标签

Skill 的粒度：找到甜蜜区

过大的 Skill

症状：Procedure 超过 15 步，从分析到执行全包

解法：按职责拆分。一个经验法则——一个 Skill 应该只有一种"输出类型"。

过小的 Skill

症状：一个 Skill 只输出一个字段

解法：向上合并到最近的有意义的"能力单元"

甜蜜区

  • Procedure 在 5-10 步之间
  • 产出一个结构化的文档/数据块
  • 可以被 2-3 个不同的 Command 复用

五个质量检查

  1. 跨业务：换到不同项目还能用吗？
  2. 多入口：是否被至少两个不同的 Command 调用？
  3. 稳定输出：同样输入是否产出相同结构的输出？
  4. 无执行依赖：是否不依赖特定执行环境？
  5. 问题清晰：不看文档能否理解它解决什么问题？

一个从失败中学到的案例

早期我做过一个 Skill 叫 "comprehensive_analysis"（综合分析），结果：

  • 不可复用：只有一个 Command 调用它
  • 不可调试：不知道哪个环节出错
  • 不可演进：改善某部分需要重新测试整个 Skill
  • 上下文爆炸：指令太长，后面的步骤经常被"忘记"

后来拆成 5 个独立的 Skill，可维护性和输出质量都有质的提升。

经验：宁可重复声明接口，也不要把不同的认知能力塞在一个容器里。

这是"AI Agent 工程化实践"系列的第三篇。下一篇将探讨多 Agent 协作的"竞争假设"模式。