这两年我给不少团队做 AI Agent 应用落地一个体会越来越深AI Agent 能不能在业务里站稳关键不在模型选得多强、prompt 写得有多花而在你给它配的那套“工程工作流”是否扛得住变化。单纯把大段 prompt 塞给 Agent 的做法项目初期很爽等需求一多、场景一换维护成本直接爆表。后来我把重心移到 Skills 这套机制上才慢慢把 Agent 的交付物从“一次性对话”变成了“可持续迭代的工程资产”。Skills 说白了就是给 Agent 准备的一套“技能包”每个技能包有名字、有触发条件、有调用协议包里可以塞脚本、参考文档、知识目录。Agent 收到任务后会先看技能清单判断当前任务该调哪个技能然后动态加载对应内容。和插件机制比它更像一份“岗位说明书”Agent 知道自己什么时候该干什么事也知道自己手里有哪些工具能用。这篇文章适合两类人一类是被 prompt 管理折腾到想放弃的同学另一类是想把 Agent 能力产品化、交给团队其他人共同维护的同学。我会从概念、目录结构、编排、调试一路讲到踩坑实录全部是落地过程中的一手经验。1. Skills 到底是什么先把这个概念揉碎1.1 从 Prompt 到 Skill 的必然演进先说一个很多人没想明白的点prompt 本质上是一段线性文本它承载不了复杂的分支逻辑。你可以在 prompt 里写“如果你遇到 A 情况就做 X遇到 B 情况就做 Y”但一旦分支超过五六个模型就开始顾此失彼。更麻烦的是当你有几十个业务场景时不可能每个场景都维护一份独立 prompt它们之间会有大量重叠改了 A 往往影响 B。Skills 的出现本质上是把 Agent 的能力组织方式从“线性文本”升级成了“结构化模块”。每个技能包就是一个独立的、可被动态加载的子任务单元。Agent 在运行时可以同时挂载多个技能根据任务需要逐层展开。这种设计借鉴了函数式编程的思想把能力封装成带接口定义的模块由调度器按需调用。我见过不少团队在 prompt 上死磕把系统提示词写到两三千字结果模型输出质量反而下降。原因很简单上下文窗口被无关信息占满真正的关键指令反而被稀释了。Skills 的思路恰恰相反——它让 Agent 保持住一个精炼的“元提示”真正的领域知识和操作细节都被折叠进技能包内部用到才展开。1.2 Skill、Tool、Plugin 的边界这三者经常被混着说但它们的粒度完全不同。搞清楚边界你才知道该把什么逻辑放进哪个层级。Tool 是单一动作比如“读文件”“执行 shell 命令”“调用某个 API”。它没有业务语义也不关心什么时候该被使用。Plugin 是一组工具的打包方案解决的是“该连哪些外部服务”的问题但同样不承担推理策略。Skill 则完全不同它是面向任务的完整能力包包含工具的挑选逻辑、执行步骤、领域规则、校验条件甚至还有配套脚本。我用一个修车比喻来解释Tool 是扳手Plugin 是工具箱里那层装扳手的格子Skill 是“换轮胎工艺卡”。工艺卡上写着用哪个规格的扳手、按什么顺序拧、扭矩多少、装完之后怎么检查。Agent 读工艺卡才知道整套动作怎么串起来。所以你在实际配置时不要把什么都往 Skill 里塞也不要把一个 Skill 拆得太碎。判断标准很简单这个单元是否能独立解决一个完整的业务子问题如果能它就该是一个 Skill如果只是操作某个数据源它放 Tool 层就够了。2. SKILL.md 是入口不是文档目录结构与配置细节2.1 一套可复用的 Skills 目录结构先给出一套我跑顺了的目录结构你们可以直接抄作业skills/ ├── requirements-analysis/ │ ├── SKILL.md │ ├── reference/ │ │ ├── story_format.md │ │ └── checklist.md │ └── scripts/ │ └── parse_requirements.py ├── code-review/ │ ├── SKILL.md │ ├── reference/ │ │ └── review_rules.md │ └── scripts/ │ └── collect_review_context.sh └── release-guard/ ├── SKILL.md └── reference/ └── release_checklist.md每个技能包统一包含三个部分SKILL.md是入口相当于给 Agent 看的第一页索引reference/放详细规则、模板、知识文档这部分会被“懒加载”scripts/放可执行脚本Agent 可以按需调用。目录设计上有一个核心原则主文件要短知识要外置。整个技能包必须可以整体拷贝到另一个项目里直接用。所以路径引用尽量用相对路径不得硬编码某个机器上的绝对路径。我在交付技能包时还会附上一个 README写清楚这个技能包依赖哪些外部命令、需要什么环境变量方便下一个接手的人独立部署。2.2 SKILL.md 的 frontmatter 怎么写才不会被 Agent 忽略SKILL.md 开头的 frontmatter 不是摆设那是整套工作流的“路由表”。我的标准模板长这样--- name: code-review version: 1.2.0 description: 当用户要求检查代码质量、提交前检查、排查潜在缺陷时使用该技能不要在数据库迁移评审时使用。 allowed-tools: - read_file - run_shell - grep dependencies: - requirements-analysis ---别看字段少每个都有自己的讲究。name要短像命令名一样方便其他技能引用不要写成“关于代码审查的专业技能指南”这种话。version必须写技能一多你就会发现不同版本的同一技能输出格式可能完全不同没有版本号你根本不知道 Agent 加载的是哪套逻辑。description是整个文件里最重要的字段它直接决定技能会不会被正确触发。这里先按下不表第三节专门展开。allowed-tools用来限制技能能操作的工具范围这是安全边界不是你小说里的装饰品。dependencies声明当前技能依赖哪些其他技能Agent 在编排时会主动去检查这些依赖是否可用。3. 让 Agent 学会“在正确时机调用”触发描述与上下文折叠3.1 description 是触发开关不是产品介绍新手最容易犯的错是把 description 写成产品说明书“本技能提供代码审查能力包含……”这种东西放在首页没问题但给 Agent 看完全无效。Agent 做技能路由时匹配的是“当前用户意图”和“技能的触发条件”之间的语义关联你写再多的功能介绍不如写清楚“什么时候该用它”。我总结出一套实用的写作公式触发场景 典型意图 反例边界。还是拿 code-review 这个技能来说description: 当用户提到以下意图时使用 - 想检查代码质量、找 bug、做提交前审查 - 在 CI 阶段希望自动做一轮代码走查 - 怀疑某段代码有性能隐患或安全隐患 不要将此技能用于 - 数据库表结构评审 - 依赖升级评估为什么要把反例边界写进去因为多个技能的 description 在语义空间中很容易互相重叠不写反例Agent 就会随机挑一个撞上的技能来用。我做过一次对比测试同样一组技能加上反例边界之后路由准确率从七成左右提到了九成以上。这个数字说明技能路由本质上是一个信息检索问题你的 description 写得越像“检索索引”召回的命中率越高。实操中还有个细节我会刻意在 description 里写入业务方真实会说的口语词比如“帮我看看这段代码稳不稳”“这个提交能上吗”这类接地气的表达往往比书面语更容易被模型匹配到。3.2 上下文折叠别把细节灌进上下文上下文折叠是 Skills 机制里最有工程价值的设计很多人却完全没利用起来。它的核心思想是SKILL.md 只保留一个“引导页”详细规则全部折叠到 reference 和 scripts 里Agent 只有在真正需要时才会展开读取。打个比方你桌上摊着一整本五百页的操作手册找东西反而困难但如果你只放一份目录上面写着“遇到 A 情况翻第 120 页”你就知道该去哪找答案。上下文折叠就是这个道理。我见过有人把几十条审查规则全写在 SKILL.md 里Agent 光读文件就消耗了几千 token等真要输出审查结论时注意力早就被拖垮了。我的做法是SKILL.md 正文只写执行流程的骨架比如“第一步先读取 reference/review_rules.md 中的规则第二步运行 scripts/collect_review_context.sh 抓取变更上下文第三步按规则逐条比对并输出结构化结论”。具体规则长什么样、脚本怎么实现全部外置。实测下来一个包含几十个文件的技能包初始加载占用可以控制在 300 到 500 token 以内展开后才会逐步增加。这种设计带来的直接好处是Agent 可以在多个技能之间来回切换而不丢失主任务因为它的工作记忆始终留给最核心的业务目标。4. 多技能编排协议、检查点与降级4.1 定义输入输出协议让 Skill 之间能“对上话”单个技能做功只能解决孤立的子问题真正常见的诉求是把多个技能串成一条工作流。这时候最关键的问题是技能之间怎么传数据我推荐两种实践方式按项目严格程度自行选择。轻量方式统一要求每个技能以“结论 结构化数据”收尾。比如需求分析技能跑完必须输出一个列表每条需求包含 ID、描述、优先级、验收标准。下游技能靠解析这些结构化数据继续干活。这种方式适合快速迭代、技能数量不超过五六个的小项目。严格方式为每个技能定义一份 JSON SchemaAgent 输出之前必须把结果转成 JSON交给scripts/validate_output.py做格式校验不合格就退回重写。我曾经给一套跨平台的数据采集系统配过这种方案采集技能把原始结果写入data/raw.json清洗技能读取这个文件继续处理每个中间产物都落盘、都带校验。这里我要强调“中间产物落盘”的价值一是可追溯出问题时能看到每一步的实际数据二是可续跑某一步挂了之后修完可以接着跑不用从头再来三是方便排查可以单独拿一个中间文件去测试下游技能不用重新跑全流程。4.2 编排层怎么控制顺序检查点的力量技能之间的先后顺序不能靠 Agent 的“临场发挥”要靠编排层显式控制。我的策略是引入“检查点”机制每一道工序完成之后都必须通过验收才能放行到下一道工序。一个典型的代码提交流水线大概是这样的pipeline: - skill: requirements-analysis output: docs/requirements.json - gate: validate docs/requirements.json 存在且格式合法 - skill: code-review output: docs/review_report.md - gate: 检查 review_report.md 中不包含阻断级问题 - skill: release-guard output: docs/release_decision.md检查点本质上是一个断言如果上一工序的产物不符合预期就把任务打回去重新执行。很多人设计工作流时只画了“顺利路径”但真实环境里失败才是常态。检查点越早、越频繁返工成本就越低。我宁可在每道工序后都加一个轻量校验也不愿等到最后一步才发现中间某环节输出的是空文件。另外要提一个关于并发编排的教训当两个技能各自独立、不共享状态时让 Agent 并行调度确实能提速但我个人建议默认还是顺序执行。因为并发的收益在大部分业务流程里并不明显但引入的不确定性很多——同一个技能被并发调用两次、写同一个文件导致覆盖、模型上下文切换混乱。除非性能实测确实成为瓶颈否则不值得为了那点速度去赌稳定性。4.3 失败与降级工作流的鲁棒性设计技能编排跑在真实环境里会遇到各种你没预料到的情况外部依赖的接口超时、脚本抛异常、Agent 跑到一半上下文超限、中间产物被误删。一个成熟的技能工作流必须具备三层保护机制。第一层是重试。对瞬时故障网络抖动、接口 5xx给每个技能配一个简单的重试策略最多重试 3 次间隔按指数退避比如 1 秒、3 秒、9 秒。第二层是降级。给关键步骤准备一条备选路径比如在线搜索不可用时自动切换到本地知识库某个脚本执行失败时改用 Agent 的纯推理能力生成兜底方案。第三层是安全中止。如果某个技能连续 3 次输出校验失败果断停止整个流水线进入人工介入流程别让模型在错误的状态里反复空转。我见过最典型的空转场景Agent 反复用同一个脚本去读一个根本不存在的路径每次失败后它不尝试查找真实路径而是换个姿势继续执行同一个注定失败的方案。这种问题光靠重试解决不了必须设置止损条件告诉 Agent当异常持续出现时不要再浪费 token直接上报人类。这里分享一个我踩过坑之后的习惯给每个工作流维护一份 incident log每出一次线上异常就记录问题现象、临时补丁、最终解决方案两周后再统一整理把反复出现的补丁固化成技能包的新版本。这套动作听着像是软件开发流程其实一个技能包就是一个需要持续打磨的代码库只是它的执行引擎是 LLM 而已。5. 工作流的验证录制回放与自动化测试5.1 录制回放把 Agent 的决策过程固化下来很多团队把技能包配好之后直接上线等线上出问题再回来排查这跟不写测试就把代码推上生产一样危险。Agent 应用最大的难点在于不确定性同一个问题今天跑和明天跑结果可能完全不同。所以验证技能工作流重点不是看一次输出对不对而是看输出的稳定性。我常用的手段是录制回放给 Agent 的运行过程开启 trace 记录把每次工具调用的输入输出、命中的技能名、推理摘要、耗时全部打点保存下来然后拿同一批测试样本反复跑对比前后差异。重点关注几个字段字段说明技能名实际触发命中了哪个技能工具调用序列技能内部按什么顺序调用了哪些工具输入摘要传入技能的核心参数输出校验结构是否符合约定 schema耗时该技能从触发到完成消耗的时间最值得警惕的是“调用路径漂移”同样一条用户请求昨天走的是 code-review 技能今天却绕到了别的地方。这通常不是模型变笨了而是某个技能的 description 被你调整之后语义空间发生了变化。录制回放能让你第一时间抓住这些变化。5.2 用自动化测试守护技能行为我现在每个技能包都配一个test_suite.py用 pytest 组织用例。测试内容分三层一层测路由是否正确触发目标技能一层测输出结构是否始终合规一层测边界情况——空输入、超长文本、恶意注入样本、极端表述看 Agent 会不会给出离谱的输出。测试脚本大概长这样import pytest from agent_runtime import load_skill, run_skill CASES [ (帮我看看这个模块的参数校验是否完整, code-review), (把这段逻辑改成异步实现注意兼容性, code-refactor), (这个提交准备上生产帮我走一遍检查, release-guard), ] pytest.mark.parametrize(query,expected_skill, CASES) def test_routing(query, expected_skill): skill route_skill(query) assert skill.name expected_skill, f{query} 路由失败 def test_output_schema(): result run_skill(code-review, sample_context) assert validate_output(result, code-review_schema.json)改过 SKILL.md 之后先跑一遍测试套件再考虑上线。不少团队会在调好一个技能后忘了回归测试其他技能结果“修复了一个技能的触发另外三个技能开始乱触发”这种连锁反应在语义路由机制里太常见了。我还坚持一个原则自动化校验不达标时让它继续迭代输出看着像省了人工实际上可能掩盖掉真正的问题环节。判定失败就明确失败让负责人去查原因这样才能倒逼每个技能包保持输出质量。6. 常见问题与避坑实录6.1 技能不触发 / 乱触发这是大家遇到最多的问题根本原因逃不出这几类description 写成了功能说明没有触发信号Agent 匹配不上多个技能的 description 语义过于相似互相抢活技能名带特殊字符或过长框架识别异常技能声明了 dependencies但依赖没被正确注册Agent 不敢调用修复手段中最有效的一招是给每个技能写三条以上的触发例句然后用向量检索实验验证例句和描述之间的召回效果。如果例句触发了两个技能说明这两个技能的边界描述还不够清晰需要把反例写得更具体。我做过的项目里经常出现“提交审查”和“代码重构”两个技能互相干扰的情况后来把时间边界写进描述比如“仅当用户提到‘提交’‘合并’‘上线’时使用”问题立刻缓解。6.2 输出格式失控同一技能跑十次输出格式出四种这是大家在纯 prompt 方案里最头疼的问题。解决思路不是靠模型自律而是靠外部约束。我的方案分两步第一明确给 Agent 指定输出结构该指定 JSON 就不要含糊地说“用结构化方式输出”第二使用两阶段输出Agent 先产出草稿然后调用validate_output.py做格式校验不合格就附上失败原因让模型重新输出最多重来两次。顺手补充一个约束技巧如果非要用 Markdown 输出一定要明确限定标题层级和字段名否则模型会自我发挥生成一个看起来工整但下游程序根本解析不了的格式。6.3 权限与工具冲突技能包一旦上线它覆盖的业务范围就固定了但 Agent 在运行时对工具的调用范围并不天然收敛。如果你不在allowed-tools里限制技能可用的工具模型有可能出于“完美主义”去读取它本不该读的文件。一个让我印象深刻的案例某团队给一个代码审查技能包开了过宽的 shell 权限模型在审查过程中把服务器上的日志目录整个扫了一遍虽然没有造成实际损失但暴露的是权限规划问题——技能权限必须跟随业务边界。工具冲突也常见尤其是两个技能同时写同一个文件时互相覆盖导致数据丢失。我的做法很朴素不同技能分配不同的临时工作目录通过环境变量注入路径。另外同一技能内部的工具调用也要注意并发安全我干脆禁止并发写同一个文件从根上规避这个问题。7. 最后几个实操心得整个迭代过程走下来有几个心得想单独分享给同行。不要一开始就设计宏大工作流。先把单个技能打磨到测试集上稳定通过再把技能串联起来每加一个环节就跑一轮全链路回归。我见过不少团队一上来就画了八个技能的大蓝图结果光路由就把项目拖垮了。技能包的粒度应该是“一次解决一个业务问题”而不是“把整个业务流程塞进一个文件”。技能包一定要版本化管理。version字段要维护仓库要用版本控制管理输入输出协议变更时要同步更新所有依赖它的技能。这样即使某一天线上行为异常你也能快速定位是哪个版本变更引入的。最后一条心得技能包的工程属性决定工作流的下限模型能力决定的是上限。如果你把技能包的目录、路由、校验都当成正经代码工程来对待那么无论底层模型换成什么系统都能保持稳定。反之再强的模型也无法在混乱、不可测、随改随崩的技能配置里发挥出真正价值。