Agent Skill 的工程化实践

从单 Skill 设计到多 Skill 编排AI Agent 时代的工程化实践引言当 Skill 数量从 1 涨到 50过去一年关于Skill的文章大多停留在如何写好一个 Skill——SKILL.md目录、YAML frontmatter、name description描述工程、Progressive Disclosure渐进式披露。这套单 Skill 设计方法论几乎已经成为行业共识。但当一个团队的 Skill 数量从 1 个膨胀到 50 个、100 个问题就完全变了。你会遇到Skill 之间的耦合A Skill 的输出是 B Skill 的输入谁来编排Skill 的失控用户问了一句帮我订机票结果触发了 3 个不该触发的 Skilltoken 暴涨。Skill 的失败某个 Skill 的description写得不好模型从来不调用它或者被误调导致整个 Agent 卡死。Skill 的演进今天能用的 Skill下个版本模型升级后触发逻辑就变了怎么办本文不重复什么是 Skill的基础内容而是直击多 Skill 时代的工程化痛点编排、治理、可观测。我会给出三个推荐框架决策树、编排模式分类、健康度指标以及一个跨领域实战案例最后讨论 Skill 工程化的未来。一、Skill 的本质再认识从 Prompt 到可治理的能力单元在进入多 Skill 体系之前我们有必要重新对齐 Skill 的本质。已有文章把它定义为比 Prompt 更好用的提示工程方案这并不够准确。我的定义是Skill 是一个具备稳定身份、可独立治理、可被 Agent 在推理时按需装载的能力单元。它包含三层含义稳定身份name description是 Skill 在 Agent 眼中的身份证决定了它何时被选中、被谁调用。可独立治理每个 Skill 都有自己的版本号、作者、依赖、测试用例、调用指标可以独立上下线。按需装载通过渐进式披露机制Skill 的完整内容不必常驻上下文只在触发时按层级加载。理解这三层才能理解为什么 Skill 不是一个高级 Prompt而是一个工程实体。它和微服务架构中的 Service、本地函数库中的 Function、IDE 中的插件本质上是同一类事物——只不过它的运行环境是 LLM 的推理上下文。二、原创框架一Skill vs 子 Agent vs MCP 决策树很多团队在系统设计时纠结这件事到底该写成 Skill、子 Agent还是 MCP Server这三者的能力边界我用一个决策树来概括Q1: 这个能力是否需要独立的工具/资源访问 ├── 是 → 走 MCPModel Context Protocol路径 │ (如数据库查询、Git 操作、浏览器控制) │ └── 否 → Q2: 这个能力是否需要独立的上下文/记忆 ├── 是 → 走 子 Agent 路径 │ (如长链路研究、多轮对话、独立工具链) │ └── 否 → Q3: 这个能力是否可在当前 Agent 上下文中按需调用 ├── 是 → 写为 Skill │ (如代码规范检查、commit 信息生成、特定领域 prompt 模板) │ └── 否 → 应该拆成多个原子 Skill 组合边界规则细化Skill是知识/提示/模板的封装不持久化上下文不直接操作外部资源。它最适合教 Agent 怎么想、怎么写。子 Agent是独立思考者有自己的 context window、自己的工具栈、自己的终止条件。它适合需要隔离、专注、长流程的场景。MCP Server是能力的桥把外部世界数据库、文件系统、API以标准化协议暴露给 Agent。它适合需要可被多种 Agent 复用的基础设施。一个反例把调用 MySQL 查询用户订单写成 Skill结果每次都要把 SQL 模板和数据库连接信息塞进 Skill 里既臃肿又危险。正确做法是写一个 MCP ServerSkill 只负责告诉 Agent “在什么场景下用这条 SQL 的思路”。三、原创框架二多 Skill 编排的四种模式当 Skill 数量超过 10 个编排就成了核心问题。我把多 Skill 协同归为四类基本模式1. 顺序模式PipelineSkill A → Skill B → Skill C典型场景代码评审流水线。先code-lint-checkSkill 做静态检查再security-scanSkill 做安全扫描最后review-summarySkill 生成报告。每个 Skill 只关心自己的输入输出契约。实现要点把 Skill 之间的中间产物如扫描报告的 JSON定义为标准 Schema避免耦合到具体实现。2. 分支模式Router┌─ Skill B (条件1) Router ─────┼─ Skill C (条件2) └─ Skill D (默认)典型场景客服意图分发。根据用户输入的意图分类决定调用退换货 Skill、咨询 Skill 还是投诉 Skill。这里需要一个路由器——可以是另一个 Skillintent-router也可以是主 Agent 的一段逻辑。实现要点路由器的判定逻辑必须显式且可解释避免模型在歧义场景下随机选择。3. 循环模式Loop with GuardSkill A ──┐ ↑ │ └─ Skill B (终止条件判定)典型场景自动修复 CI 失败。fix-attemptSkill 尝试修复check-resultSkill 判定是否通过。如果不通过且未超过最大次数回到fix-attempt。实现要点必须设置最大循环次数和超时否则 Agent 会陷入死循环烧光 token。我见过生产事故就是因为某个 Skill 的终止判定写得太宽松循环了 200 多次。4. 协商模式Multi-Skill Consensus┌─ Skill A (主张1 置信度) User ───┼─ Skill B (主张2 置信度) └─ Skill C (主张3 置信度) │ Aggregator (投票/加权)典型场景投资决策辅助。多个 Skill 各自给出风险评估、市场情绪、技术面分析最终由聚合器加权输出。实现要点每个 Skill 必须输出结构化的置信度而不是自由文本否则聚合器无法量化决策。编排的反模式Skill 调用 SkillSkill A 在自己的 description 里硬编码调用 Skill B 的指令。这会导致循环依赖和隐式编排调试地狱。应改为显式编排由主 Agent 或外部 Orchestrator 调度。Skill 的 description 互相重叠两个 Skill 的description描述了相似的场景模型会随机选择。必须用互斥 完备MECE原则设计 description。四、原创框架三Skill 健康度指标体系可观测性是 Skill 工程化的基石。我提出四个核心指标简称S4 指标1. 命中率Hit RateHit Rate Skill 被触发的次数 / 用户请求总次数健康参考值20%-60%。如果某 Skill 的命中率长期 5%说明它的 description 不够清晰或场景已经过时如果 80%说明它在抢别人的活需要拆分或重新定位。2. 误触发率False Trigger RateFTR 人工判定为误触发的次数 / Skill 触发总次数这是最难测的指标。建议方案在灰度阶段抽样 1% 的调用做人工标注。建立用户反馈 人工复审的双轨机制。用一个 LLM-as-Judge 的 Skill 来自动评估注意评估 Skill 和被评估 Skill 必须用不同模型避免同源偏差。健康参考值 10%。超过 15% 说明 description 有歧义需要重新写。3. Token 成本Token Cost per InvocationTCI (input_tokens output_tokens) × 单价很多团队忽视了 Skill 的 token 成本。一个看似免费的 Skill如果每次触发都要加载 5000 token 的SKILL.md到上下文调用 1 万次就是 5000 万 token。优化手段用 渐进式披露分层加载meta → instructions → resources。把 Skill 的高频片段做成微型 Skill 500 token把低频片段合并为完整 Skill。用 prompt caching如果模型支持把不变的 Skill description 缓存。4. P99 延迟Latency P99P99 第 99 百分位的端到端响应时间Skill 是 Agent 推理链路上的额外一步必然增加延迟。如果某个 Skill 让 P99 从 2s 飙升到 8s就需要检查 Skill 内容是否导致模型思考过长用更明确的指令减少推理轮次。把同步 Skill 改成异步预加载。把 Skill 的执行放到子 Agent 里并发。指标看板的最小实现一个简化的 S4 看板应该长这样Skill NameHit RateFTRTCIP99状态code-review35%8%12003.2s健康db-query-helper5%45%8001.1s需优化 descriptionfix-attempt12%6%450012.5stoken/延迟双高五、跨领域实战案例电商客服 SOP 的多 Skill 编排为了把上面的框架串起来我用电商客服 SOP做一个综合案例。业务背景一个中型电商平台每天 10 万次客服咨询。原有方案是把所有规则塞进一个超长 prompt3000 行导致模型经常忘记早期规则。响应慢单次平均 4.5s。升级到新模型后整个 prompt 要重写。重构方案多 Skill 编排把超长 prompt 拆成 12 个 Skill按四类编排模式组织阶段 1意图路由分支模式intent-routerSkill根据用户输入输出意图标签refund/logistics/product-inquiry/complaint/other。阶段 2领域处理顺序 协商模式退换货链路顺序refund-policy-check→order-lookupMCP→refund-eligibility→response-generator。物流咨询分支根据订单状态分别走logistics-normal、logistics-delay、logistics-lost三个 Skill。投诉处理协商sentiment-analyzer、policy-checker、risk-assessor三个 Skill 各自评分由聚合 Skill 输出最终处理建议。阶段 3质检循环模式quality-checkSkill 对生成的回复做合规检查如果不通过且重试次数 2回到response-generator重新生成。关键 Skill 的实现片段intent-router的 YAML frontmattername:intent-routerdescription:当用户输入为中文客服对话时使用。负责识别意图并路由到对应处理 Skill。仅做意图分类不直接回答用户问题。注意description里明确写了不做回答这是路由器的关键约束避免模型直接越权生成回复。refund-eligibility的核心逻辑伪代码层面Skill 的指令会要求模型调用order-lookupMCP获取订单信息。根据订单状态、用户历史、退款政策输出结构化判定eligible/partial/not-eligible 原因。把判定结果传给response-generator。重构后的效果响应延迟平均从 4.5s 降到 2.8sP99 从 9s 降到 5.5s。token 成本单次平均从 3500 token 降到 1400 tokenProgressive Disclosure 分层加载。规则维护新增政策只需修改对应 Skill不用动全局 prompt。可观测每个 Skill 的 S4 指标独立可见能定位瓶颈 Skill。这次重构的教训Skill 拆分不是越细越好我们一度把每个退款规则拆成一个 Skill导致编排开销过大。最后合并成按业务域为一个 Skill规则用结构化数据YAML/JSON放在 resources 目录。路由器的 description 必须极简intent-router一开始 description 写得太复杂模型经常自作主张直接回复。后来精简到 2 句话路由准确率从 78% 升到 94%。循环模式一定要有熔断quality-check一开始没有最大重试限制遇到边缘 case 时反复重试烧光 token。加上 2 次限制后稳定。六、Skill 的失败模式与回退策略任何 Skill 都不是 100% 可靠的。我总结了 7 种典型失败模式及应对失败模式表现根本原因回退策略静默失活Skill 从未被触发description 与用户措辞不匹配增加触发关键词同义词、定期 A/B 测试 description过度触发Skill 在不该调用时被调用description 太宽泛缩小 scope、加入不适用场景描述上下文污染Skill 加载后导致主 Agent 行为偏移Skill 内容含强约束用隔离子 Agent 包裹 Skill执行卡死Skill 内部逻辑死循环缺少终止条件设置超时 最大重试 watchdog依赖缺失Skill 引用了不存在的 MCPMCP 未正确注册启动时自检依赖、优雅降级到本地实现版本漂移Skill 在新模型上效果变差description 对老模型有效但新模型偏好改变模型升级时跑回归测试集权限越界Skill 实际做了超出 description 的事Skill 文件被篡改签名校验 沙箱执行 操作审计回退策略的三个层次Skill 内回退Skill 自身提供 fallback 路径如主路径失败时调用简化版。编排层回退编排器发现 Skill 超时/错误时跳过它或替换为等价 Skill。平台层回退整个 Agent 链路降级到无 Skill 的基础模式保证核心功能可用。七、Skill 的版本化、CI/CD 与灰度发布当 Skill 数量超过 20没有版本化就是灾难。我推荐如下实践1. 版本规范遵循 SemVermajor.minor.patch。major破坏性变更description 语义、输入输出 schema。minor新增能力向后兼容。patch文档、提示词微调。2. CI 流水线每次提交触发lint SKILL.md ─┐ schema check ─┼─→ unit test → eval test → package → registry description regression ─┘其中description regression特别重要用历史应该触发该 Skill 的真实 query作为测试集验证 description 改动后命中率不退化。3. 灰度发布金丝雀Canary先对 1% 的用户启用新版本 Skill。A/B 对照新旧版本同时运行按 S4 指标对比。紧急回滚发现 FTR 飙升或 P99 异常时一键回滚到上一个稳定版本。4. Skill Registry建立内部 Skill 注册表类似 npm每个 Skill 有 metadata作者、依赖、License、Eval Score。支持按场景搜索如所有退款相关 Skill。强制要求每个 Skill 配套一个最小 Eval 测试集。八、Skill 工程化的未来展望站在 2026 年中看Skill 工程化正在经历几个清晰的演进方向1. 从技能库到技能市场企业内部的 Skill Registry 会进一步开放形成跨企业的 Skill Marketplace。但要解决两个问题版权与计费Skill 的 prompt 是知识产权、安全审计Skill 不能携带恶意指令。可以预见会出现第三方Skill 审计服务。2. 自动 Skill 发现与生成未来会有Skill Miner工具从团队历史对话、issue 列表、工单中自动挖掘重复模式生成 Skill 草稿由人工 review 后入库。这把 Skill 创建从专家工程变成团队共创。3. Skill 之间的语义级互操作现在的 Skill 通信靠自由文本 约定俗成未来会出现标准化的Skill-to-Skill Protocol结构化输入输出 schema、版本协商、能力声明。这和微服务从REST 混沌走向OpenAPI gRPC是同一个故事。4. 与 Agent OS 的融合未来的 Agent OS无论是 Claude Code、Codex、Cursor 还是新平台会把 Skill 作为一等公民原生支持 Skill 的发现、加载、编排、可观测。Skill 不再是附加品而是 Agent 能力的标准交付形态。5. Skill 的反脆弱设计随着模型越来越强Skill 的作用可能会从教模型怎么做演化为约束模型不要做什么——反脆弱 Skill如安全护栏、合规检查、越权阻断会成为新的增长点。结语回到开篇的问题单 Skill 设计是入门多 Skill 编排是工程Skill 治理是艺术。