这两年搞 AI Agent 的人越来越多了但大多数人其实都卡在同一步模型明明很聪明单独问什么都对一旦让它去干一件完整的事就开始自由发挥、跑偏、返工。我自己也是从这种每写一个 Agent 就要从头写一大段提示词的状态里爬出来的直到把思路从提示词换成技能skills整套玩法才真正顺起来。这篇东西就围绕 agent-skills 这个主题把我在实际项目中踩过的坑、验证过的方法一次讲清楚。先说清楚这篇文章是给谁看的你不是第一次接触 Agent 开发但你可能正在纠结怎么让 Agent 稳定地完成复杂任务怎么把一套能力复制到多个项目里怎么让团队其他人也能复用你的 Agent 能力。如果你只是随便玩玩的业余选手也建议坚持看完因为技能化这套思路会让你少走至少三个月的弯路。1. 为什么 Agent 必须拥有技能而不是提示词1.1 裸奔的 LLM 在真实任务面前有多脆弱很多人最开始写 Agent 就是一层壳包一个 LLM然后把所有要求都塞进 system prompt。说实话这种用法应付单轮问答没问题但一旦任务本身有步骤、有格式要求、有外部依赖系统立马暴露三个硬伤。第一提示词语义密度过高。你想让模型先抓数据、再清洗、再分析、再画图、最后写报告这些指令全部堆在一个 system prompt 里。模型不是按顺序执行的而是把所有内容当作一个整体去 predict步骤感非常弱。十次里有三次会跳过中间步骤直接给结论你很难控制它的执行过程。第二格式约定和业务逻辑互相污染。你要 JSON 输出、要指定字段名、要小数位保留两位这些细节跟任务定义混在一个文本里。改一个字段就得把一大段提示词全部重新调一遍而且改完经常引发其他部分的行为漂移。第三没有任何自我检查的钩子。提示词只是引导不是程序。模型输出完了就是完了没有输入校验、没有输出校验、没有重试机制。你只能在 Agent 调度层外面手工写一大堆 if-else 去补救最后 Agent 没多复杂外围代码倒写了两千行。我试过用一个裸模型直接去整理竞品动态并生成周报结果是它有时候输出 Markdown 表格有时候输出自然语言段落还有一次把竞品名字都编错了。问题不在于模型笨而在于它根本没有一套上下文约束好的执行协议可循。1.2 从一次性提示词到可复用技能核心转变是什么所以后来我把思路改成了技能把一次任务需要的提示词、参数定义、校验规则、执行步骤、甚至脚本打包成一个独立可复用的单元。Agent 运行的时候不是拿着一大段提示词硬跑而是先根据用户意图去检索应该调用的技能再像函数调用一样去执行这个技能。这个转变最本质的地方不是包了一层壳而是从告诉模型怎么做变成了给模型定义好能力的边界和接口。打个比方一个裸模型就像一个记忆力超群但毫无经验的新人你让他帮我办一场活动他能说出很多点子但真执行起来他不知道先订场地还是先定嘉宾。而技能化的 Agent 就像一个工具箱每个工具都有明确的把手、用法、适用场景和输出物。你说办活动它会先看技能库里有活动策划场地对接预算估算这些技能然后按顺序调用每调用一个技能输出一个结构化的中间结果最后汇总成你要的东西。这个思路的直接收益体现在三个地方稳定同一个技能的上下文是固定的输出协议是强制校验的不会因为对话历史变长而漂移。可复用同一个技能在这个 Agent 能用换一个 Agent 也能用这个项目用完了下一个项目直接装进去。可测试技能是独立单元可以离线跑基准用例可以单独迭代不用每次都在整个 Agent 里回归。1.3 技能与工具、角色、工作流边界到底在哪儿聊到这里就有一个绕不开的问题Skills、Tools、Persona、Workflow 到底是什么关系我在团队里经常看到有人混着用最后把系统设计得乱七八糟。我自己用下来更喜欢这么划定边界概念核心职责颗粒度示例工具Tool单点能力通常是函数/API 调用小查天气、发邮件、执行SQL技能Skill组合多步操作完成一类具体任务包含提示词逻辑与校验规则中竞品分析、会议纪要整理角色Persona定义风格、立场、回复语气贯穿层资深分析师、客服助手工作流Workflow编排多个技能与工具形成一条固定的业务流水线大线索清洗→客户画像→触达→复盘工具是手技能是一套完整的操作手法角色是说话的气质工作流是排班表。实际开发时技能里面会调用工具技能可以被工作流调度角色则是对技能输出的修饰层。这个分层想清楚之后做 Agent 的抽象一下子清爽了。很多人一开始就把技能边界划错了要么把 Skills 写得特别大相当于一个小型应用要么写得特别小只有一个工具调用。我的经验是一个技能理想的状态是刚好能完成一个可验收的交付物技能输入是明确的请求输出是一个可校验、可直接使用的产物。竞品周报、会议纪要、账单分析这些都是技能而生成 SQL调用某个 API只是技能里面的步骤不应该单独成为技能。2. 一个 Agent 技能从拆解到上线的完整开发流程这一节我用一个真实做过的技能——竞品动态监控与周报生成——带大家走一遍从零到一的全过程顺便把每个决策背后的原因讲透。2.1 需求拆解先别急着写提示词先画好边界做技能最大的忌讳就是一上来就写提示词。你得先像做产品需求一样拆清楚这个技能的输入是什么、输出是什么、处理过程要分几步、什么情况下算成功、什么情况下算失败。我当时拆出来的需求大概是这样的输入竞品名称列表允许 1-10 个、监控时间范围默认最近一周、关注维度产品动态、融资消息、舆情、招聘。处理搜索公开信息 → 按竞品分组 → 按维度归类 → 去重 → 提取关键变化 → 评估影响程度。输出结构化周报Markdown 格式每一条动态包含时间、来源、维度、摘要、影响评估最后汇总一个风险/机会提示。边界如果某个竞品完全搜不到近期信息输出中要明确标注无公开动态不能凭空编造如果输入列表为空直接拒绝执行并提示补参。这些内容全部明确之后才进入技能文件的实际编写。这一步最关键的点在于你定义好了失败的样子后面 Agent 运行的时候才不会在遇到异常数据的时候随机胡诌。2.2 技能文件结构与核心目录设计现在社区里对技能的文件结构基本形成了一个约定核心是SKILL.md加配套资源。我的项目里一般长这样skill_registry/ competitive_monitor/ SKILL.md schema.py # 输入输出校验 search_utils.py # 搜索聚合逻辑 templates/ report.md.j2 # 周报模板 examples/ sample_input.json sample_output.md tests/ test_basic.mdSKILL.md是技能的说明书也是 Agent 调用这个技能时最重要的一段上下文。它里面通常包含技能名称和简短描述用于 Agent 做技能检索时的匹配。适用场景和不适用场景的说明减少误调用。输入槽位的定义与限制。执行步骤的描述尽量具体到第 1 步做什么、第 2 步做什么。输出格式的明确约束包括字段名、格式、示例。错误处理约定什么情况属于调用失败失败后返回什么结构。这里我要特意强调一个很多人都忽略的点SKILL.md不是给人类看的文档是给模型看的高密度上下文。所以描述性废话必须少指令必须可执行。它的质量直接决定了 Agent 调用这个技能的成功率。2.3 输入槽位设计与输出协议把接口当作函数来设计输入输出的设计我直接把它当函数签名来做。SKILL.md里定义一个input_schema让调度层负责解析用户请求并填充参数。参数定义里除了字段名还要写清楚取值范围、必填还是选填、默认值、类型以及如果没有这个参数应该怎么办。一个典型的 schema 片段大概长这样{ skill_name: competitive_monitor, input_schema: { type: object, properties: { competitors: { type: array, items: { type: string }, minItems: 1, maxItems: 10, description: 竞品名称列表必须是公开可查的真实企业/产品名称 }, time_range: { type: string, enum: [1d, 7d, 30d], default: 7d, description: 监控时间范围 }, dimensions: { type: array, items: { type: string, enum: [product, finance, news, hiring] }, default: [product, news], description: 需要关注的维度 } }, required: [competitors] } }有个容易被忽略的细节描述字段要写反向约束。光说competitors 是竞品名称列表不够你还要说不能包含虚构名称如果无法确认存在必须尝试先做实体解析。因为模型在填空的时候如果遇到模糊输入它会倾向用上下文猜测而不是标记异常。加了反向约束它猜的概率就低很多。输出协议也一样别只写输出一份周报要把每个段落、每个字段、每个条件分支都定义清楚。竞品周报我当时的输出协议是{ report_title: 竞品动态周报2024-xx-xx, summary: { overall_trend: high-level trend description, risk_level: low|medium|high, top_actions: [1-3 条建议每条不超过 50 字] }, items: [ { competitor: , dimension: product|finance|news|hiring, headline: , source_url: , published_at: YYYY-MM-DD, impact_score: 1, summary: , action_suggestion: } ], silent_competitors: [一段时间内无公开动态的竞品] }输出协议一旦在SKILL.md里声明我在代码层还会写一个validate_output()函数做二次校验防止模型漏字段、格式错乱。这就是前面说的钩子——模型可以不完美但你必须在外围拦住不完美的东西。2.4 内置校验与自纠错模型会犯错技能必须会止血不要指望模型每次输出都完美符合 schema。我做过的实测即使SKILL.md里写得很清楚items字段的必填项漏掉source_url的概率仍然有 5% 到 10%如果SKILL.md写得含糊这个概率能飙到 30% 以上。所以良好的技能设计都带一个自纠错层。我的做法是三步走第一轮生成后跑 JSON schema 校验。通过就直接交付。校验不过把校验错误信息返回给模型让模型基于错误信息修补输出。注意这时候要给它一个错误信息 原输出 修正指令的封装不要简单地说重新生成那样大概率还会犯同样的错。如果修补两轮仍然失败就降级输出把有问题的字段标记为待确认同时向调用方返回一个可读性正常的报告而不是直接抛异常。很多人忽略第三步导致技能一失败整个 Agent 就崩了。但实际上对于竞品周报这种任务降级交付远比失败重试更符合用户期望——用户宁可看到一部分数据待确认也不想等半天什么也没拿到。在代码层面自纠错可以直接用函数调用或结构化生成来实现。我自己试验下来最稳定的组合是外层的序号化执行步骤step-by-step 编排 内层的自纠错循环。这样做即使模型单步表现不那么完美整体任务的失败率依然能控制在可接受范围内。3. 技能设计里最容易翻车的三个截点3.1 输出格式不稳定JSON 之外还有更稳的选择JSON 看似是结构化的万能解药但重点在于自由生成的 JSON 并不稳定。字段顺序颠倒、多余注释、中文逗号、字符串里嵌了换行符这些我都实际遇到过。为了保持稳定我通常做两道防护。第一道在SKILL.md里不只给 JSON 示意还给一个正例 反例。比如// 正例 {competitor: 某某科技, dimension: product, impact_score: 4} // 反例字段值带多余换行和编造的来源 {competitor: 某某科技, dimension: product, impact_score: 4, source_url: }模型对反例的敏感度其实比对规则描述更高这一点很多资料不会告诉你。第二道当输出协议特别复杂、字段特别多的时候我不再让模型直接生成最终 JSON而是让它分两次生成第一次生成信息提取文本可以是自由的自然语言第二次再用一个函数把这个文本转为结构化 JSON。第二阶段的转换非常稳定因为它的输入是结构化的自然语言而不是公海一样的完整对话历史。这个阶段性固化的思路是减少输出格式乱象最有效的投入产出比动作。3.2 上下文窗口被技能说明塞满了怎么办我一开始写SKILL.md有个倾向就是想把所有可能用到的情况全部写进去结果一份技能说明三四千字Agent 每次调用都要把这些内容全部塞进上下文。模型一执行长任务总上下文很快见顶反而影响主任务质量。后来我学到的做法是分层加载SKILL.md里只保留高频 必需的信息技能简介、输入输出 schema、执行步骤概要、主要禁忌。低频但必要的信息比如更长的处理细则、模板的替代版本、常见问题 FAQ放到单独的附加参数或额外文档里按需加载。Agent 在执行步骤 3 的时候如果需要看模板细节再去读取templates/report.md.j2而不是一开始全部塞进来。这样做最常见的收益就是处理超长内容时技能主体保持在 500 行以内模型执行力和稳定度明显上升。我用一个竞品监控技能做了对比测试整理 15 条动态时完整加载版耗时多 40% 且有两处字段错误分层加载版一次通过。很多人忽略了上下文窗口的管理一味怪模型不够聪明。实际上当你看现象发现模型开始忽略技能说明的细节的时候绝大多数情况不是模型能力问题而是它的注意力被技能自身的冗余内容稀释了。3.3 技能调用失败时Agent 会装糊涂第三个容易翻车的点很隐蔽你不给技能定义不知道/做不到的显式出口它就会用一套错误答案来填补。举例来说竞品动态监控里面搜索接口可能返回空结果或者内容质量差到没法提取。模型面对这种情况往往不会说没找到而是会利用训练记忆去编造几条看起来像真的信息。这种情况在技能化之后并不会自动消失因为技能只是把任务交给了模型并没有改变模型偏好产生流利文本的本能。我的解决方案是强制沉默条款。在SKILL.md里明确写如果在规定时间窗口内某个竞品没有找到任何公开动态必须在输出的silent_competitors数组中列出该竞品严禁生成无来源动态或推测性描述。同时在校验层加逻辑如果输出里出现source_url为空但summary非空的条目直接判定为可疑项要求模型重做或降级处理。这个校验规则做一次就能拦住大多数装糊涂的场景。这背后的道理其实很通用技能的能力边界写得越清楚模型幻想hallucination的空间就越小。边界即护栏。4. 跨框架技能迁移与生态选型4.1 技能热背后的生态差异现在做 agent-skills 已经不缺生态了。各家框架基本都开始支持技能这个概念核心的SKILL.md和配套脚本结构得到了很多团队的认可但又各有侧重。根据我的实践观察可以把它们大概分成三类第一类高度集成型。技能与框架本身深度绑定使用体验最顺技能可以直接被框架内部的规划器调用但迁移到其他框架需要做适配。第二类开放目录型。技能文件完全开放、跨平台共享任何框架都可以通过解析SKILL.md来加载兼容性最好但部分高级特性如特殊的数据加载器在不同框架里表现不一致。第三类市场/平台型。把技能托管到中心化的技能市场用户直接安装、评分、更新但这类生态通常依赖特定平台有锁定的风险。具体到技术人做技术选型我给的建议是如果你是个人项目或者小团队优先选生态成熟、技能文件可跨框架复用的方案如果你对大厂的平台生态没有特殊依赖尽量不要让自己被锁定在某个封闭格式里。因为技能的复用价值比那一点点框架的便利性重要得多。我在实际项目中维护了一个技能目录里面有十几个技能全部采用通用SKILL.md 轻量封装的方式组织。换框架时只需要写一个不到一百行的适配器把框架的输入解析到我的 schema再把我的输出映射回框架的消息格式剩下的技能核心逻辑一行不用改。4.2 一套技能库在三个框架间的迁移实操去年我做过一次实测把一套包含竞品竞对监控、会议纪要和周报分析的技能库从 A 框架迁移到 B 框架再迁移到一个自研调度环境。为了不让这篇文章变成某一框架的软文隐去具体名字直接讲迁移时遇到的两个关键阻力位。第一个阻力位是输入解析。不同框架给用户时对参数的提取机制不一样有的用自然语言解析有的要求严格 JSON Schema有的依赖 LLM 函数调用。解决办法是用一个标准化的 skill adapter它负责把框架的原始用户消息解析成技能的 JSON 输入。解析层只改一处所有技能跟着受益。第二个阻力位是错误处理语义。A 框架里技能抛异常就代表整轮对话失败B 框架里技能可以返回一个带错误码的结构化结果继续对话。我最终在技能内部彻底放弃了抛异常的做法统一改为返回结构化错误——因为 Agent 和用户都要能感知失败的原因而不是面对一个光秃秃的报错。迁移本身的工作量大概 80% 集中在上面两个适配器技能本体几乎零改动。这也是技能化设计真正省时间的地方。只要当初 schema 设计得足够干净换框架不用重新写符咒一样的提示词。4.3 技能库的版本管理与回滚技能是会持续迭代的但迭代不意味着每次都拿最新的版本去跑生产任务。我自己踩过一次大坑在一次竞品监控中优化后的技能把搜索关键词拼接逻辑改了结果导致所有竞品的关键词都匹配到了错误的结果整整一天没有发现。从那以后我给技能库引入了严格的三层版本策略层级环境版本策略dev开发环境可以随意改甚至推翻重来staging预发布环境跑固定基准集对比新旧版本的通过率和格式错误率prod生产环境锁定版本只在 staging 验证通过后升级每个技能目录下我都放一个CHANGELOG.md记录每次改动的原因、影响范围、验证结果。这份日志的价值会在三个月后完全体现出来——那时候你已经忘了当初为什么要定义某个怪异字段了能翻日志真的是救命。版本回滚也要快。我的做法是给技能目录打 git tag发布/回滚直接 checkout 到对应 tag不需要额外搞一套复杂的配置系统。技能本质上是代码和数据就该用代码工程的方式来管理。5. 团队化落地从技能能用到技能好用5.1 一个技能合入主库前我要求必须过这七关如果技能只是自己用怎么折腾都行。但一旦到了团队协作就必须有验收标准。我给我们团队日常技能入库设了七条评审项你也可以直接抄过去有明确且唯一的技能描述能被检索器稳定匹配。如果两个技能描述高度相似入库前就要解决冲突。输入 schema 完整必填项、默认值、反向约束都写了。输出协议包含结构定义和失败样例的说明。至少有 3 组基准样例能跑通覆盖正常、边界、异常三类场景。SKILL.md没有明显冗余总长度控制在可接受范围内。包含错误处理和降级方案不允许技能失败直接爆粗。有基本的 CHANGELOG 记录说明解决了什么需求或者修复了什么问题。七关看着多但设计好的技能过起来很快。反过来如果一个技能连这些基本项都过不了它进入 Agent 后大概率带来随机性故障到时候排查成本会远大于现在写这些说明的成本。5.2 用数据评估技能质量而不是感觉技能好不好用不能靠我觉得挺稳的。我在生产环境给每个技能挂了简单的埋点记录如下数据调用次数从调用到输出的耗时一次校验通过率经自纠错后的最终通过率降级输出的比例用户/上层任务对结果的负面反馈数这些数据出来之后技能的问题基本一目了然。比如某个技能降级输出比例从 3% 跳到 15%说明最近一次改动可能引入了问题哪怕当时测的 3 个样例都过了。因为生产环境的数据分布远比你手工构造的测试集复杂得多。有的团队喜欢搞大而全的评测平台我觉得在小团队阶段完全没必要。埋点日志 定期抽查 简单的统计脚本已经能解决 90% 的技能质量管理问题。5.3 踩坑实录一次技能复用事故的完整排查链路最后分享一个真实的事故排查过程正好可以拿来验证上面的体系有没有用。现象一个客服场景的 Agent从某天开始频繁给用户输出对不起我暂时无法处理你这个请求负面反馈率直线上升。第一阶段排查看 Agent 日志发现失败全部集中在订单查询技能。该技能原本能正常返回订单状态但改版后一直降级输出。第二阶段排查逐条回放技能调用过程发现输入解析正常、schema 校验正常但输出校验不过。再往里看原来是订单状态字段的枚举值改了从PENDING, PROCESSING, DONE增加了一个SHIPPED而技能模板用的是旧枚举导致校验永远无法通过。第三阶段确认回滚到上一版本技能库整体恢复。然后在 staging 环境跑完整基准集发现改版技能没有跑所有输出字段必须在新枚举范围内的用例所以直接漏过了。最后在评审清单里补了一条凡是 schema 或枚举变更必须连带更新模板和测试样例缺一不可。这个事故本身不复杂但排查链路非常典型。它说明一件事技能不是写完就固定的静态资产它会随着业务演进被改动。你要做的不只是维护一个技能文件而是维护一个技能相关的数据一致性闭环。模板、schema、校验器、测试样例任何一个单独改了其他三个不跟上就会出问题。我现在写任何新技能都遵守一条铁律schema 和模板必须同源生成能从一个地方生成就不要在两个地方手写。这样至少能避免一半以上的低级改动事故。到这里agent-skills 的核心玩法、开发流程、稳定性设计、跨生态迁移、团队治理几块都说完了。如果你现在正好在重构自己的 Agent建议别急着加更多花哨功能先把手头最常用的三件事技能化用一段时间对比一下稳定性和迭代速度你会有很直观的感受。技能够稳Agent 才敢去接更复杂的活。