这个标题我一看就来兴趣了。Agent Skills这个词，近一年在圈里讨论度确实高，但真正把它琢磨透、能在项目里用得顺手的人不算多。我个人理解，它就是大模型时代的“岗位技能手册”——你以为是在写Prompt，其实是在给AI Agent做标准化作业指导。今天不聊概念，直接拆开揉碎，讲讲它解决的问题、怎么从零搭建、怎么评估迭代，以及我踩过的那些坑。
1. 什么是Agent Skills：不是Prompt，是给Agent配的“岗位说明书”
1.1 从一句“帮我查一下”到一套完整作业流程
很多人习惯把大模型当成一个什么都能聊的“全科实习生”，你跟它说一句话，它就能给你一个像模像样的答案。但真到了生产环境，问题就来了：你说“帮我查一下某平台商品的库存和价格”，模型可能真的就只给你一段文字描述，不会去调用接口，不会去解析返回的JSON，更不会在超时的时候自动重试。
Agent Skills要解决的，正是这个“只有想法、没有动作”的问题。它不只是一个更长的Prompt，而是把“查库存”这个岗位动作，拆成一套完整作业流程：先识别商品ID，再选择正确的API接口，设置超时和重试策略，解析返回数据，最后按固定格式输出结构化结果。每一步都有明确的操作规范，模型只需按手册执行，就像新员工入职拿到一本SOP，照着做就不会跑偏。
1.2 Skills和普通Prompt的本质区别
拿写周报来类比。你给实习生一句“帮我写个周报”，他大概率给你写出一篇流水账。但你给他一份《周报作业手册》，里面写着：开头按“本周目标—完成情况—数据佐证—风险与问题—下周计划”五段式结构；完成情况必须附具体数据；风险问题不得少于两条；全文字数控制在800字以内。这样写出来的周报，质量就稳定得多。
Agent Skills就是这份手册。它和普通Prompt的区别主要体现在四个维度：
- 结构化程度不同：Prompt是一段自然语言描述，Skills是一份包含步骤定义、输入输出规范、异常处理策略的工程化文档。
- 稳定性不同：Prompt每次生成的结果方差很大，Skills通过拆解步骤、约束输出格式，把方差压到可控范围。
- 可复用性不同：Prompt换个场景基本就废了，Skills可以像积木一样在不同Agent任务里组合复用。
- 可评估性不同：Prompt好不好全凭感觉，Skills可以用测试集跑回归，用通过率衡量质量。
1.3 什么场景下你最需要它
我在实际项目里的感受是：如果你只是拿大模型做文本摘要、闲聊对话，那Skills确实有点杀鸡用牛刀。但凡是涉及工具调用、多步骤任务、数据格式要求严格的生产场景，Skills几乎是一个必需品。
举几个典型场景：电商运营需要Agent定时抓取竞品价格并生成对比报表；客服系统需要Agent先查订单状态、再查物流信息、最后根据组合结果生成话术；金融分析需要Agent调用多个数据源，把非结构化数据清洗成标准字段入库。这些任务有个共同特点：动作是固定的、流程是明确的、输出是要被下游系统消费的。这种情况下，你需要的不是一个聪明的模型，而是一套“照着做就不会错”的操作手册。
提示：判断你的场景需不需要Skills，就问自己一个问题——这个任务能不能写出一份让新人照着做就能完成80%工作的SOP？如果能，那它就适合做成Skill。
2. 为什么Agent必须有“技能”而非只能“对话”：三个绕不开的问题
2.1 问题一：大模型的“知识”和“动作”是脱节的
大模型最擅长的事情是“生成下一个词”，但真实世界的任务，不是靠生成词汇就能完成的。比如一个物流查询任务，模型需要知道物流公司的API格式、请求头的签名算法、不同响应码的含义，还得在遇到特定错误时切换备用查询渠道。
这些专业知识模型可能“知道”一些，但不可靠。它可能记混接口参数名，可能在解析响应时忽略错误码，可能在一个订单查询失败后直接放弃而不是换渠道重试。Skills机制解决的就是这个“知道但不会做”的鸿沟——把专家的真实作业经验固化下来，让模型不必依赖记忆，直接调用经过验证的动作序列。
2.2 问题二：生成结果不稳定，生产环境不接受“看运气”
同一个Prompt，同一个模型，温度设为0，连续调用三次，输出也可能不一样。做文本创作这是风格多样性，做数据清洗就是事故现场。我在一次数据抽取任务里就吃过亏：同样一段商品描述，模型第一次抽出了“品牌：某品牌”，第二次却漏了这个字段，第三次甚至把颜色填进了品牌字段。
生产系统需要的是确定性。Skills通过约束输出Schema、定义每个字段的提取规则、明确空值处理策略，把这种不确定性大幅压制。虽然不是100%确定，但足以从“不可用”提升到“可验收”的级别。对于强调稳定性的业务场景，这份确定性比模型本身的“聪明程度”更重要。
2.3 问题三：领域知识和私有经验无法通过通用训练内化到模型里
你所在团队积累的那些操作技巧、业务流程、踩坑经验，几乎没有可能通过微调模型来保留——成本高不说，更新频率也跟不上业务变化。但把这些经验写成Skill，就是一个普通配置文件，谁都能改，改完立即生效。
这一点在团队协作中价值尤其明显。老员工把“怎么处理某平台反爬签名”写成Skill，新来的同事不需要问人，Agent调这个Skill就能按老员工的标准干活。相当于把个人经验转化成了组织资产，人走了，经验还在系统里。
3. 手把手构建一个Agent Skill：以“电商商品信息抽取与归类”为例
3.1 定义目标与边界：这个Skill到底管什么、不管什么
开始动手前，第一件事不是写代码，而是把边界划清楚。我用的是“三个一”原则：一个明确的目标、一类处理对象、一套标准输出。
拿我项目里一个真实Skill举例。目标是从电商商品标题中抽取品牌、型号、规格、颜色、价格区间，并归类到预设的品类树下。处理对象是商品标题文本，不包含图片；输出是一份固定Schema的JSON，归类结果必须命中预设品类编码。
边界写清楚的好处是：模型不会把无关的能力混进来。比如商品标题里出现了“包邮”“秒杀”这类营销词，Skill的定义里就要写明“忽略营销词、只抽取实体属性”，这样模型就不会把它们当作品类或规格识别出来。
3.2 选择Skill格式：YAML声明式还是Python过程式
目前主流的Agent框架里，Skill通常有两种载体：YAML声明式和Python过程式。我的经验是：没有孰优孰劣，只有场景适配。
YAML声明式适合定义结构清晰、步骤相对固定的任务。它的好处是直观，整个作业手册一眼看全，方便非技术人员参与维护。一个典型的YAML Skill长这样：
name: product_info_extractor description: 从电商商品标题中抽取品牌、型号、规格等结构化信息，并完成品类归类。 version: 1.2.0 author: agent-team inputs: - name: product_title type: string description: 商品标题原文，例如"某品牌 Pro Max 256G 曜石黑 5G手机 官方标配" required: true outputs: - name: brand type: string description: 抽取出的品牌名称，若无法识别则置为"unknown" - name: model type: string description: 产品型号，保留字母数字与点号 - name: spec type: string description: 关键规格信息，如内存、容量、尺寸 - name: color type: string description: 颜色描述，去除"色"字后缀 - name: price_range type: object description: 预估价格区间 - name: category_code type: string description: 品类编码，必须命中预设品类字典，否则返回"unknown" steps: - step: 1 name: 意图识别与字段抽取 description: 逐一抽取brand/model/spec/color字段。品牌识别优先匹配预设品牌库，未命中时按规则推断。 - step: 2 name: 价格区间预估 description: 根据规格和型号匹配同款或近似款的历史价格区间，若无则根据品类基准价给出估算。 - step: 3 name: 品类归类 description: 结合品牌、型号文本匹配品类树，按最长匹配原则归类。 error_handling: - condition: 标题为空或长度低于5 action: 返回错误码EMPTY_TITLE，不执行后续步骤 - condition: 所有字段均无法抽取 action: 返回错误码EXTRACT_FAILED，附带原始标题用于人工复核Python过程式则适合逻辑复杂、需要循环和条件分支的任务。比如解析一份混合了PDF、表格、图片的多格式报表，你需要先判断格式、再走不同的解析分支，这种逻辑用YAML写会非常痛苦，直接用函数表达反而清晰。
3.3 编写高质量Skill描述的几个关键细节
Skill写得好不好，一半在格式，一半在描述文本的质量。这里有几个我总结出来的技巧。
描述要写“触发条件”和“不做什么”。很多人写description只写“抽取商品信息”，模型在无关场景里也容易误触发。我会写成“仅当输入文本是电商商品标题时执行；若输入是评论、问答或营销文案，直接返回NOT_APPLICABLE”。这个小小的补充，能把误调用率下降一半以上。
步骤之间要有输出传递的明确约定。比如第二步价格预估依赖第一步抽取的规格字段，描述里就要写明“spec为unknown时，价格区间按品类基准价×1.2的系数估算”。模型在推理时遵循的是文本里的显式指令，你写得越具体，它的表现越稳定。
输出Schema的每个字段都要给示例和边界规则。以品类编码为例，我给的规则是“必须命中品类字典，否则返回unknown”，而不是让模型“根据常识判断”。常识判断在训练数据覆盖不到的冷门品类上极容易翻车。
3.4 从粗糙到可用：一个Skill至少要迭代三轮
第一轮，按业务理解写完，拿20条典型样本跑一遍，基本能覆盖一半以上场景。第二轮，把失败的样本逐个分析，看是描述歧义、步骤缺失还是Schema不完整，然后针对性修改。第三轮，用新的测试集回归，确认修复没有引发新问题。
很多人在第一轮就停了，觉得“差不多能用”，结果线上各种边缘Case频出。我从经验里得到的教训是：Skill质量的瓶颈往往不是模型的聪明程度，而是定义者对异常情况的预判和覆盖。
注意：迭代时不建议只加样本，还要回看“描述是否模糊”。同一个问题，通过加样本修正三次，本质上是因为描述里有歧义，把描述改精确，一次就能解决。
4. Skills质量如何保障：测试、评估与版本管理
4.1 建一个“最小可用测试集”，而不是追求样本数量
评估Skill质量，不能靠感觉。我最常用的方法是建一个“最小可用测试集”，大概50到100条真实历史数据，覆盖典型场景、边界场景和异常场景三类。每条样本标注了期望输出，跑完用脚本批量比对。
典型场景占70%，保证日常能干活；边界场景占20%，比如超长文本、缺失字段、特殊字符、多品牌并列;异常场景占10%，比如空标题、纯营销文案、乱码输入。这样分配样本，比堆500条重复数据有效得多。
4.2 用“通过率+关键字段命中率”双指标评估
整体通过率是指全字段正确率，要求严格；但在迭代过程中，只看整体通过率容易打击信心，因为只要一个字段错了就归为失败。我会拆出“关键字段命中率”，比如brand和category_code是核心字段，单独统计；color和price_range是次要字段，允许一定容错。
这样做的好处是迭代时能明显看到“核心能力在提升、边缘字段暂时没跟上”的真实差距，而不是面对一个刺眼的整体通过率发呆。等核心字段稳定在95%以上，再去抠次要字段的精度。
4.3 版本管理：避免“改好了A却改坏了B”
Skill本质上是文本配置，但迭代多了之后，回退和对比就成了刚需。我把每个Skill都放进Git仓库，改名成了带语义后缀的配置包，比如“product_info_extractor_v1.2.0.yaml”。每次改动都带上commit message，写清楚“改了什么、为什么改、期望效果是什么”。
有一次我改了价格预估的基准系数，商品A的预估准确率提升了8个百分点，但商品B的准确率反而掉了12个百分点。幸好有版本管理，我直接diff了两个版本，发现是系数调整影响了对特殊品类价格敏感度的判断。没有版本历史，这种问题排查就只能靠猜。
4.4 灰度发布与人机协同兜底
质量做得再好的Skill，直接全量上线我都觉得心里没底。我的做法是先让Skill在“建议模式”下运行：Agent正常调用Skill并生成结果，但在写入数据库前先经过人工确认，抽样比例可以按30%起步，通过率达到预期后再逐步放量至自动模式。
如果业务允许，还可以做A/B对比——新旧Skill并行跑一周，统计关键指标差异，再决定是否切换。比“拍脑袋上线”稳妥得多。
5. 常见问题与排查技巧实录
5.1 模型不调用Skill，或者总在无关场景误触发
这个问题在早期几乎必现。我的排查路径是：先检查description里有没有写明触发条件和排除条件；再检查Skill的输入参数描述是否清晰；最后确认模型版本对这个类型指令的遵循能力。
试过最有效的一招，是在description开头加一句“仅当满足以下所有条件时才调用本技能：…”。比如商品抽取这个Skill，我会写“仅当输入为电商商品标题且包含品牌或规格信息时调用；若为评论、问答、营销文案，禁止调用”。这一句话，误触发率肉眼可见地下降。
5.2 输出永远不符合Schema，不是缺字段就是类型错
如果模型频繁输出不符合Schema的结果，先别急着骂模型，回到Skill定义里看outputs部分。类型定义是否明确？每个字段是否给了示例？是否说明了空值处理策略？
我之前遇到一个问题是模型总把price_range输出成字符串“2000-3000元”，而不是我定义的JSON对象。后来我在Schema里加了严格说明：“price_range必须为包含min、max、currency的JSON对象，不允许输出自然语言描述”，并在示例里给了正反两个用例。之后通过率从62%升到91%。
5.3 Skill之间互相干扰、上下文污染
在一个Agent里挂多个Skill时，偶尔会出现A任务错误调用了B技能的情况。这多半是多个Skill的description有语义重叠。我的排查方法是：把Agent挂载的所有Skill列表拉出来，逐个比对description，看有没有语义相近的表述。把重叠部分删掉，在各自description里补充“不适用场景”，问题基本能解决。
5.4 难以复现的“偶发性失败”，最终元凶是上下文长度
有一种最让人头疼的问题是：同一份输入，单测怎么跑都通过，一旦放回真实Agent流程里，偶发失败。排查到最后，往往是因为完整对话里塞了太多历史消息，模型在处理时“忽略”了Skill中靠后的步骤，或者直接短路输出了。
应对办法是把Skill的触发条件和核心步骤写在description和steps的开头，同时让Agent在调用Skill前做一次上文摘要，压缩不必要的历史信息。这里没有完美解法，只能靠架构优化降低发生概率。
6. 团队落地Agent Skills的一些非技术心得
6.1 把Skill当成“文档资产”管理，而不是“一次性脚本”
我在最早做Agent的时候，习惯把Skill当成“给模型临时加的规则”，写完就用，用坏了就改，完全没有文档化意识。后来团队扩大、Agent数量变多，才发现没有规格说明的Skill就是负债。
现在我把每个Skill都配一张一页纸的说明，包含：它解决什么问题、定义了哪些步骤、为什么这么定义、已知边界和失败场景。这件事看起来跟模型能力无关，但对团队协作和长期维护来说，价值甚至比Skill本身更大。
6.2 Skill的维护者必须是业务人员，而不是只靠工程师
Skill的质量上限，取决于你对业务的拆解深度。最懂“商品标题里信息怎么分布”的，是类目运营，不是算法工程师。所以我在团队里推动了一种模式：业务人员负责定义“做什么、按什么标准做”，工程师负责把规则翻译成Skill格式。
这个分工刚开始会有沟通成本，但跑顺之后，业务人员可以直接读YAML，自己提修改建议，通过Pull Request的流程更新Skill。老员工的经验沉淀效率，比纯靠代码实现高了不止一个量级。
6.3 从“做成一个Skill”到“建设一套Skill体系”
单个Skill做到90分，只是起步。长期来看，有价值的做法是把Skill体系化——按业务域分组、建立依赖关系、定义组合编排方式。
比如电商场景，我拆出了“商品属性抽取”“价格区间预估”“类目归并”“竞品监控”“报表生成”五个基础Skill，再通过一个“竞品周报”的复合Skill去编排它们。后续业务需要新的报表，不需要从头写，而是组合已有的Skill。这套思路，跟微服务化的演进路径差不多，本质都是“标准化能力沉淀+灵活组合复用”。
结尾：踩过这么多坑，剩下三句话最想分享
第一句：Skills的本质，不是让模型变聪明，而是让模型的输出变规范。你没法指望模型懂你业务里的每个潜规则，但你能把潜规则写成明规则。第二句：评估Skill质量之前，先确保你有足够多样、足够真实的测试数据，没有测试集，所有优化都只是自我安慰。第三句：Skill体系的建设是长期工程，越早开始分类沉淀和版本管理，后面越轻松。希望这篇分享，能让你在搭Agent的时候少走一些弯路。
