最近在折腾Agent相关项目时我把每天在群里被问得最多的问题整理了一遍发现十个里有七个都绕不开同一个概念agent-skills。这个词在AI Agent圈子里已经热了很久但真正说清楚它是什么、怎么用、怎么设计的人其实不多。不少朋友把Agent接上了大模型API也跑通了Function Calling但一遇到复杂任务就露怯——要么Agent死活不干活要么干到一半就断。说白了就是技能没做对。这篇文章我想用自己在实际项目里的经验聊聊Agent Skills到底是什么为什么值得把它当成一套独立的工程来设计以及怎么从零把一个可复用的Skill写出来、挂进去、调好。整个过程会非常具体涉及改代码、调参数、看日志也有我踩过的坑和排查思路。不管你是刚入门Agent开发还是已经在做多Agent编排这部分内容应该都能直接拿去做参考。1. 先搞清楚Agent Skills到底是什么1.1 它不是“给Agent加工具”这么简单很多人把Agent Skills和Tool、Function Calling混在一起觉得给Agent挂几个API就是有技能了。这个理解在实际开发里会出大问题。Tool只是函数的壳子它告诉Agent“你有这个函数可以调用”但Skill更像是把完整的做事流程、约束条件、输入输出约定、异常处理都打包成一个模块让Agent能理解“我应该在什么场景下用这套流程以及怎么用”。我举一个直观的例子。假设你给Agent接了一个“发送邮件”的API那只是一个Tool。但如果你的任务是“帮用户起草一封项目周报邮件并发送给团队”这就不是单纯调用一次函数能解决的。它需要判断周报要包含哪些模块数据从哪里来邮件语气应该怎么定收件人列表怎么解析发之前是否需要用户确认。把这些能力组装进一个SkillAgent拿到的是一整套可执行的行为模板而不是一个孤立的函数。这么做最大的好处是可控性。直接让Agent自由调用一堆Tool它可能在多步任务中迷失方向但Skill把流程封装好之后Agent的决策空间被收窄到一个合理的范围内输出质量就有了基础保障。1.2 技能、工具、工作流之间的边界在哪里我自己做项目时习惯用三条标准来区分工具解决“怎么做”技能解决“做什么”工作流解决“按什么顺序做”。工具是最小粒度通常对应一个具体的函数调用比如查询天气、发一条消息、解析一份PDF。技能是把多个工具调用、决策逻辑、中间校验步骤组合起来形成一个完整的解决方案。工作流则更进一步它通常是长期运行的、带状态管理的流程编排可能包含人工审批、多阶段推进、跨系统协调。用生活里的例子来说螺丝刀是工具会维修的人会根据不同螺丝选择合适的螺丝刀并完成拆卸这是一种技能。而“把一台电脑从拆解到清洁再到重新组装”就是工作流因为它的每一步有明确的前后依赖关系、可能需要停下来检查状态。实际开发时我倾向于小任务用Tool中等复杂度的任务沉淀成Skill真正跨系统、长时间运行的任务再引入Workflow。如果一开始就上Workflow引擎反而会过度设计给项目带来不少维护成本。1.3 一个完整的Skill里到底装了什么规格设计上我一般会把Skill拆成五个组成部分身份信息、能力描述、执行逻辑、参数范式、边界约束。身份信息包括Skill的名称、用途、适用场景。能力描述是给Agent看的一段文字用来告诉模型“你什么时候应该调用这个技能”。执行逻辑是具体的代码、函数调用序列、Prompt模板或者它们的组合。参数范式定义了调用这个Skill需要传入哪些字段、字段类型、必选还是可选。边界约束则说明这个Skill不适合处理什么、有哪些限制条件。这五个部分缺一不可。特别是边界约束很多团队会忽略。没有约束的Skill会被Agent在错误场景里强行调用就像拿菜刀开罐头虽然也能打开但一定会出各种问题。2. 设计一个Skill最关键的其实是“描述”2.1 好的命名能决定Agent会不会用它在Agent开发里有一个非常容易被忽略的经验Agent对Skill的调用决策很大程度取决于它对Skill名字和描述的理解。如果你的Skill叫“process_data”大模型根本猜不出这个函数是干什么用的、什么时候该调用。但如果你叫它“extract_structured_info_from_webpage”模型一看就知道是专门做网页信息提取的在用户问“帮我整理一下这篇文章的要点”时就会优先调用它。所以命名时要遵循一条原则名字里必须包含“动作”和“对象”。动作是这个技能做什么比如extract、summarize、search、validate对象是它作用在什么东西上比如webpage、order、email、log。一个名字就把这两个要素说清楚Agent的命中率会提升非常多。我早期踩过这类坑曾经把一个技能命名为“helper”结果Agent几乎从不主动调用它。后来改成“concat_multiple_documents_to_one_pdf”调用率立刻上来了。听起来很玄学但本质是大模型在理解函数意图时对语义相关度的评价名字越具体匹配度越高。2.2 description才是Agent的“使用说明书”相比名字description更需要花心思。很多开发者在写description的时候只写一句“这是一个网页提取工具”这几乎等于没写。要让Agent正确使用Skilldescription应该包含三个信息适合使用这个Skill的场景、预期能达到的效果、使用时需要注意的限制。我举个例子一个优秀的description长这样“当用户需要从单个网页URL中提取文章标题、正文、发布时间、作者等信息并以结构化JSON字段返回时使用此技能。如果用户需要提取多个页面或需要动态渲染页面中的图片请优先使用其他技能。如果URL无效或页面返回404不要调用此技能请直接告知用户链接无法访问。”这段描述其实做了几件事明确了触发条件用户需要提取信息、以JSON返回、圈定了适用范围单页面静态数据、屏蔽了错误场景动态渲染、无效URL。Agent在读到这段描述后会大幅减少误调用和乱传参数的概率。根据我的实测经验给description增加“什么时候不要用”这类负向描述对准确率的提升非常明显。因为大模型的指令遵循能力有限你越明确告诉它“不要做什么”它在边界处就越谨慎。2.3 参数设计的三个常见坑参数设计直接决定Skill的鲁棒性。我用表格整理一下最常见的三个坑和我觉得比较稳妥的做法常见坑具体表现推荐做法参数过于宽松允许Agent自由传入任意JSON结构代码端解析时崩溃每个参数必须有明确的类型、枚举值或格式约束代码端做防御性校验参数依赖隐式上下文要求Agent自行“理解”某个字段的含义比如传一个“最近的日期”把隐式规则显式化为参数或要求Agent调用另一个Skill来获取具体值可选参数没给默认值Agent不传某个参数就导致流程中断所有可选参数必须有兜底默认值并写明默认行为参数这块宁可多花时间也不能偷懒。做过一段时间你一定会发现Agent传参的随意程度远超你想象。它可能把一个期待number类型的数据传成字符串也可能在枚举值里自由发挥出一个你从没见过的选项。所以代码端千万不能假设输入永远合法每一步都要做校验。3. 实战写一个网页结构化信息提取Skill3.1 需求拆解与功能边界说得再多也不如直接动手。我拿“网页结构化信息提取”这个常见场景来完整走一遍流程这个Skill在我的项目里用了很久稳定性和复用性都很不错可以作为一个入门模板。首先明确需求用户给一个URLAgent需要访问该网页提取其中的标题、正文段落、发布日期、作者、标签等信息并以JSON格式返回。难点在于网页结构千差万别同一个模板可以适配新闻、博客、技术文档但很难适配所有网站。所以我把这个Skill分成两条路径如果能识别出主流页面结构就走模板解析如果识别不了就退回到通用提取逻辑抓取大段文本并用大模型做后处理。功能边界这里必须写清楚这个Skill只处理公开可访问的HTTP/HTTPS页面不处理需要登录认证的站点不做JS动态渲染页面的提取单次只处理一个URL。把这些边界写进description避免Agent把它用在错误场景里。3.2 核心代码与调用约定代码层面我采用Python实现核心逻辑使用Jina Reader或类似服务获取干净的Markdown格式文本再用正则和模板提取关键字段。伪代码如下def extract_webpage_info(url): if not is_valid_url(url): raise SkillParameterError(URL格式非法) raw_text fetch_readable_text(url) # 内置超时和重试机制 if raw_text is None: raise SkillExecutionError(无法获取页面内容可能链接已失效或有访问限制) title normalize_field( extract_by_pattern(raw_text, [title, # 标题, og:title]) ) date normalize_field( extract_by_pattern(raw_text, [datePublished, 发布时间, date]) ) content clean_noise_blocks(raw_text) tags extract_tags(content) return { title: title, publish_date: date, author: author_regex_match, content: content[:MAX_CONTENT_LENGTH], tags: tags, source_url: url }除了主函数我还定义了调用约定所有入参统一以字典方式传入键名固定为url超时时间10秒失败时抛出的异常类型必须区分是参数错误还是执行错误这样Agent在收到异常后才知道应该调整参数还是直接将错误返回给用户。3.3 把它挂进Agent框架并跑通Skill写好后要注册到Agent框架的Skills仓库中。我比较常用的方式是写一个注册表每个Skill对应一份JSON配置内容包含名字、描述、参数schema以及对应的处理函数路径。{ name: extract_structured_info_from_webpage, description: 当用户需要从单个网页URL中提取文章标题、正文、发布时间、作者等信息并以结构化JSON字段返回时使用……, parameters: { url: {type: string, required: true, description: 需要提取的网页完整URL} }, handler: skills.web_extract.handler }注册完成之后先跑一个简单的调用链用户输入“帮我提取这个网页的标题和正文https://example.com/article” → 大模型判断应该调用哪个Skill → 触发对应handler → 返回JSON → 大模型组织成自然语言回答。这个链路能整体跑通Skill就已经具备了可用基础。在真实项目里我还会加一个日志环节把每次调用Skill时的模型决策理由、入参、出参、耗时都记录下来。这些日志在做后续优化时极为重要。3.4 实测效果与调优记录上线之后我会用一批真实网页做验证。我通常选择三类样本新闻网站文章、个人博客、企业官网新闻稿。第一轮测试最容易发现的问题是date字段提取失败率很高因为各个网站表示日期的方式太不同了内容区域混入导航栏和底部版权文本清理逻辑要单独调。我的调优思路是在提取结果后面加一个轻量级大模型后处理步骤把第一轮提取出的原始文本片段交给大模型让它“从以下内容中提炼标题、发布时间、作者、正文核心段落返回JSON”。这个步骤虽然引入了一点额外成本但对最终输出质量的提升是颠覆性的。特别是混合型页面正则能力达不到要求时大模型的后处理几乎是唯一可靠的出路。最终的稳定流程变成了获取文本 → 规则粗提取 → 大模型细加工 → JSON输出。规则负责快和大模型负责精和准两者配合起来效果非常理想。4. Skill的投放与复用单技能到技能库4.1 多Skill场景下的组织方式项目做到一定规模后Skill会越来越多。你不可能让Agent在每次对话时都读完所有Skill的描述一方面是token开销大另一方面是选择噪音会让调用准确率下降。比较好的做法是做分类和分层投放。我的组织方式是建一个Skills分类树按照“领域 动词”来划分。举例来说底层分组包括内容处理提取、转换、翻译、数据分析统计、对比、可视化、系统集成邮件、数据库、文件管理等。每个Skill都挂在对应的分类节点下。然后依据任务属性来决定启用哪些分组。比如用户进行了一个“提取网页内容并保存为PDF”的多步任务那就同时启用网页解析、文件生成两个分类下的Skill如果只是做数据统计就只启用数据分析分组。这种按需求动态组合的方式能有效控制决策空间。4.2 动态加载与按需装配Skill多了之后另一个关键问题是内存管理。把所有Skill常驻内存显然不现实尤其当大项目包含几十个甚至上百个Skill时。我的做法是做一个基于关键词的Skill预加载器它会在用户任务进来时先做一轮轻量级意图识别再根据意图把相关Skill加载进上下文无关Skill直接不参与。这个预加载器本身也是一个轻量级的分类模型或规则匹配器。它的作用是缩小候选集让最终的大模型决策更聚焦。以我当前的项目来说30多个Skill里一次任务真正会参与决策的通常只有3到5个Agent的选择准确率明显比一次性给30个Skill要高。装配这一步其实还有一层更细的心智模型把Skill按“能力”和“场景”两个维度来索引。能力维度描述的是这个技能本身能完成哪些动作场景维度描述的是在什么业务场景下会被需要。两条索引同时命中才把这个Skill纳入候选。4.3 Skill的版本管理思路Skill一旦被多个业务线复用版本管理就成了硬需求。我的建议是每个Skill至少包含version字段并在代码里做好向后兼容。版本升级时最忌讳的是直接覆盖旧Skill。因为其它Agent可能还在用旧版本一旦你改了输入输出结构它们的调用链会直接断掉。我会采用“旧版保留、新版新增、灰度切换”的策略新版本Skill以新的namespace注册旧版本继续保留一段时间等所有调用方确认无依赖后再下线。灰度切换的方法也很简单在线上的Agent配置里按用户或业务线维度区分调用版本先让5%的流量走新版本观察一段时间错误率和效果指标如果稳定再逐步放量到100%。这套方法在传统后端里很常见但放到Agent开发里很多人会忽略导致一个小修改引发全网事故。5. 常见问题与排查技巧实录5.1 Agent死活不调用某个Skill这是我最常被问的问题。你写好了Skill逻辑完整、描述清晰、代码也测过但Agent就是不调用它宁可自己硬编一个错误答案。排查步骤我总结为四步走。第一步检查Skill名和描述是否与任务语义词面相关。如果你写的描述全是“用于处理事务”但用户问题是“帮我提取标题”相关性就太弱模型自然会跳过。第二步检查候选集是否过大。如果一次会话同时注入了几十个Skill模型的选择注意力会被稀释命中的几率明显下降。第三步检查是否有更高优先级的Skill覆盖了它的职责。比如你同时添加了一个“通用网页信息分析”和“提取网页标题”在大多数场景下Agent会选更通用的那个你需要给细分Skill增加更强的触发信号或把通用Skill按领域禁用。第四步检查模型本身的决策配置。部分训练模型的Function Calling表现并不稳定如果系统使用了低参数模型建议优先升级到更强模型来验证技能调用逻辑而不是先怀疑Skill写错了。5.2 参数传错、格式混乱Agent传入的参数经常出现类型不匹配、字段名拼写变体、多余字段、缺失字段等问题。这类问题不能指望改Prompt就能彻底解决要用流程来控制。我写了一套参数清洗三原则。第一条是“宽进严出”入参阶段尽量容忍各种变体代码里面做同名映射、类型强制转换但进入业务逻辑之前统一转成内部标准结构。第二条是“缺省兜底”缺失的必填参数尝试从上下文补全补不齐就明确返回错误码而不是静默失败。第三条是“枚举收敛”凡是允许值可枚举的参数在解析阶段就做一次合法性校验非法值按默认值处理并记录日志。这套方案落地之后我因为参数问题导致的链路失败率从20%降到了不到2%。核心思路就是别信任模型输出把容错逻辑写在代码里。5.3 Skill跑到一半失败的恢复策略多步骤Skill执行到第5步时突然失败怎么处理最常见的错误是直接向用户报错这体验太差了。我采用的策略是“错误类型 重试策略 降级路径”三位一体的恢复机制。先把错误分成三类参数类错误P0、环境类错误P1、业务类错误P2。P0类说明调用方传了脏数据不需要重试直接返回修正建议。P1类指网络超时、依赖服务503这类临时性故障可以重试1到2次每次间隔递增。P2类指业务逻辑层面发现数据不符合预期比如解析出的日期跑到2030年去了这时启动降级路径比如跳过该字段、用默认值替代、或者改为交给用户手动确认。在代码层面我的做法是把Skill的每一个步骤包上可观测的上下文记录步骤名、入参快照、出参快照、耗时。出了问题可以直接回溯到具体是哪个子流程产生了脏数据而不需要从头去翻日志。我个人在这些年的Agent项目里最深的一个体会是Skill本质上不是“写代码”而是在“做约定”。你和Agent之间约定的质量直接决定了最后交付的系统靠不靠谱。与其一上来就堆砌各种复杂能力不如先把一两个核心Skill打磨打磨把命名、描述、参数边界、异常恢复这些东西统统想透。你后面加技能、加业务、加复杂场景的时候会发现地基打得稳是一个多么省心的事。这个扩展的方向可以从单Agent一直延伸到多Agent协作每一个Agent手里攥着几个高质量Skill整个系统的可用性自然就上来了。