1. 为什么Agent开发绕不开“技能”这个话题1.1 从“会聊天”到“会干活”最近大半年我一直在做AI Agent相关的应用开发链接各种模型、框架和业务系统。项目里反复高频出现的一个词就是agent-skills。说白了你光有一个能对话的大模型它再聪明也只是“嘴上功夫”——让它帮你查一下数据库、改个配置文件、调一下API它就傻了因为模型本身没有动手能力。agent-skills解决的正是这个问题**把模型和外部工具、操作流程之间的耦合关系用一套清晰、可复用、可组合的方式固化下来。**它本来就是一个能力包本质上是“给智能体预先写好的一系列操作方法”。这些方法可以是调用外部API、执行Python函数、读写文件、操作数据库、调用另一个模型甚至是编译好的命令行工具。只要注册成SkillAgent就能在对话或任务执行中被自动调度。我在这个方向上的经验是任何一个Agent要做成“生产力工具”而不是“聊天玩具”90%的工作量最后都落在Skills的设计和实现上。所以如果你正在做Agent应用或者想提升自己的Agent开发能力学会设计、组织、调试这些技能是绕不开的基本功。1.2 Skill和Plugin、Workflow到底有什么区别很多刚开始接触的朋友喜欢把Skill和Plugin、Workflow混为一谈。我最早也踩了这个坑后来在真正落地项目时才算彻底分清楚。**Plugin插件**是一个更宽泛的概念泛指为某个宿主程序增加功能的扩展模块。在Agent框架里插件可能是完整封装好的工具组带GUI配置界面面向终端用户强调“开箱即用”。**Workflow工作流**强调的是“流程编排”。它定义了多个步骤之间的顺序、分支和依赖关系你画一个流程Agent照着走侧重的是“按剧本执行”特点是固定、确定性强。**Skill技能**则处于两者之间更侧重“能力的原子化封装”。一个Skill可以很小比如“把一段文本翻译成英文”也可以很大比如“分析一份财务报表并生成摘要”。Skill贴近的是大模型的行为逻辑通常包含了模型需要感知的元信息这个技能是干什么的、什么时候用以及模型可以调用的动作函数。我自己的理解是Skill是“组装”的基础单元Plugin是“组装的产物”Workflow是“组装的蓝图”。Agent开发里你把基础技能搭好再通过Workflow把它们串起来最后发布成Plugin给用户用这条链路非常清晰。1.3 什么场景下最需要Skills不是所有Agent都要引入Skills。比如你只是做一个客服闲聊模型原生能力就够。但以下几个场景Skills的收益极大企业私有数据查询让Agent能自己查ERP、CRM、内部知识库需要写数据查询技能。自动化办公生成报表、批量处理文档、定时发送消息每个动作就是一个技能。开发辅助自动跑测试、做代码审查、执行爬虫任务这些也全是技能。多模型协作一个Agent调用另一个模型做专项分析在Skills里封装一个“调用专家模型”的接口。在项目里你可以用一套统一的模式来定义这些技能不用管底层是HTTP调用、Python脚本还是数据库操作Agent的世界里它们都叫“一个能做的事”。2. 一个Skill的内部结构从声明到执行2.1 定睛一看Skill的描述文件到底长什么样如果你用过Claude的Agent Skills、OpenAI的Actions或者其他Agent框架会发现一个规律**Skill的核心是一份让大模型“看懂”的声明文件再加上若干可执行的代码。**声明文件通常用YAML或JSON格式内容大致包括名称、描述、参数Schema、使用说明等。我以前开发过一个用于内部数据分析的Agent其中“查询销售趋势”这个Skill的描述文件简化出来大致长这样name: sales_trend_query description: | 查询指定时间范围内的销售趋势数据支持按区域、产品线、渠道进行过滤。 当用户询问销售额变化、销售走势、同比环比增长时使用该技能。 如果用户没有给定时间范围默认查询最近30天。 parameters: type: object properties: start_date: type: string format: date description: 查询开始日期格式为YYYY-MM-DD end_date: type: string format: date description: 查询结束日期格式为YYYY-MM-DD region: type: string enum: [华北, 华东, 华南, 西部] description: 区域筛选条件可选 channel: type: string enum: [线上, 线下, 代理商] description: 渠道筛选条件可选 required: - start_date - end_date看到这个结构你应该能明白这份YAML并不仅仅是给开发者看的注释它是喂给大模型的“使用说明书”。模型根据这份说明书判断什么时候该调用这个技能、怎么填参数、填错了怎么办。写Agent的过程某种意义上就是在给模型写一份“人类也能读懂的API文档”。我在真实项目中有一个体会描述文本的质量直接决定了模型能否自动调用Skill比代码本身的优先级还高。描述写得含混不清大模型就会犹豫描述里明确给了触发条件和默认值模型的调度成功率会肉眼可见地提升。2.2 动作与工具的映射技能里的“手”怎么伸出去光有描述文件不够还得有真正的执行代码。Agent框架通常允许你在Skill里定义一个或多个函数这些函数就是技能底层真实执行的逻辑。还是拿“销售趋势查询”来说它底层的执行逻辑可能是接收模型根据用户对话解析出的参数start_date、end_date等。连接公司内部的ClickHouse数据库执行一段聚合SQL。把查询结果整理成结构化数据返回给模型由模型组织语言回复用户。用Python示意一下import clickhouse_connect def run(start_date: str, end_date: str, region: str None, channel: str None): client clickhouse_connect.get_client(hostyour_host, databaseanalytics) filters [] if region: filters.append(fregion {region}) if channel: filters.append(fchannel {channel}) where_clause AND .join(filters) if filters else 11 query f SELECT toDate(order_time) AS day, sum(amount) AS total_amount, count() AS order_cnt FROM sales_orders WHERE order_time {start_date} AND order_time {end_date} AND {where_clause} GROUP BY day ORDER BY day result client.query(query) return [{day: row[0], amount: row[1], orders: row[2]} for row in result.result_rows]这个函数你可以起任意名字关键是框架里有约定**函数的签名、参数名要和YAML中的parameters一致返回的数据要尽量结构化。**返回的数据越规整模型越容易理解并组织成自然语言回复。如果返回全是一段长文本或者报错信息模型就容易答非所问。2.3 上下文压缩与输入输出设计我在多个项目中反复琢磨的一件事是Skill的输出如何不影响Agent的“主线思考”。因为大模型的上下文窗口有限如果Skill返回了几百行原始数据Agent的主对话就容易被淹没了。我常用的策略是**在Skill内部先做一次数据压缩或摘要只把重要结论返回给模型。**例如上面的销售趋势查询底层SQL已经做了日期粒度聚合返回结果通常是几十行如果数据量再大我还会在Skill内部预聚合出“总销售额、环比变化、最大增长日”等摘要字段只让模型拿到这些精选信息。另一个设计原则是**输入参数尽量用枚举和默认值限定模型的选择空间。**模型填格式自由的长字符串很容易出错而给它列好的枚举值比如区域、渠道、时间粒度模型的准确率会大幅提升。你可以把这一点理解为“用清单代替自由发挥”对机器和模型都好。3. 手写一个可复用的Agent技能完整实操3.1 从需求拆解开始先想清楚“什么时候用”讲再多理论不如实际动手写一个技能。我以“发送定时提醒邮件”为例完整走一遍因为这个技能足够小、逻辑清晰但又能体现Skill设计的核心环节。需求描述是用户想要Agent在指定时间给指定邮箱发送一封内容提醒的邮件。第一件事不是写代码而是想清楚这个技能的触发边界。什么时候模型应该调用它用户说“明天早上9点提醒我给张三发周报”的时候就该调用户说“帮我写一封邮件草稿我待会自己发”就不该调用——因为用户没要求“发送”。这种边界如果不写在描述里模型会做出过度反应。所以我在描述文件里特别注明name: schedule_reminder_email description: | 用于在指定时间发送提醒邮件。当用户明确要求定时发送提醒发送到点 发邮件时使用。如果用户只是让AI写邮件草稿没有定时发送意图不要调用。3.2 编写参数Schema给模型一个“填表模板”接着定义参数。这一步我建议大家贴近用户的自然表达去设计字段而不是按系统内部命名parameters: type: object properties: recipient_email: type: string format: email description: 收件人邮箱地址必填 subject: type: string description: 邮件主题尽量简洁默认“提醒通知” body: type: string description: 邮件正文内容可包含换行符 send_at: type: string format: date-time description: 发送时间ISO 8601格式例如2024-06-01T09:00:00 required: - recipient_email - body - send_at这里有个细节我吃过亏**日期格式务必写明格式示例。**很多模型对时间格式的理解有偏差你写“format: date-time”它可能理解为“2024-06-01 09:00”但Python的datetime库又需要点号或其他分隔符于是报错。你在description里给出一个具体的示例串“2024-06-01T09:00:00”模型的复现准确率会显著提高。3.3 实现执行逻辑把“定时”和“发送”分开底层执行函数我拆成两个模块一个是邮件发送函数一个是调度函数。import smtplib from email.mime.text import MIMEText from datetime import datetime import threading import time def send_email(recipient: str, subject: str, body: str): 真正的发邮件逻辑只负责发送不负责定时 msg MIMEText(body, plain, utf-8) msg[Subject] subject msg[From] agentyourcompany.com msg[To] recipient with smtplib.SMTP(smtp.yourcompany.com, 587) as server: server.starttls() server.login(agentyourcompany.com, your_password) server.sendmail(agentyourcompany.com, [recipient], msg.as_string()) def schedule_email(recipient_email: str, subject: str, body: str, send_at: str): 发布定时任务返回一个任务标识 send_time datetime.fromisoformat(send_at) delay (send_time - datetime.now()).total_seconds() if delay 0: # 如果用户要求的时间已经过了直接改成立即发送 send_email(recipient_email, subject, body) return {status: sent_now, message: 时间已过已立即发送} def _task(): time.sleep(delay) send_email(recipient_email, subject, body) thread threading.Thread(target_task, daemonTrue) thread.start() return {status: scheduled, send_at: send_at, task_id: id(thread)}这里有意做了一个容错如果用户给定的时间已经过去Skill不会报错而是降级为“立即发送”同时在返回信息里标注“已立即发送”。这个效果比直接抛异常友好得多模型拿到这种返回结果后会自然地向用户解释发生了什么。这也体现了一个技巧Skill的返回信息要设计成“模型可以直接引用的话术”模型的回答质量会更高。当然真实环境里我不会用线程做定时任务而是把任务写入Redis延迟队列或者使用Celery但原理一模一样。小Demo用线程演示最直观能让读者看清流程。3.4 注册进Agent主程序让模型能“看到”这个技能写完代码和描述文件还差最后一步把Skill注册进Agent主程序。不同框架注册方式不同但核心逻辑都是“把描述文件加载进来把执行函数挂上去”。以下是一个通用伪代码结构from agent_sdk import Agent, Skill skill Skill( nameschedule_reminder_email, yaml_path./skills/schedule_reminder_email/skill.yaml, entrypointschedule_email ) agent Agent.from_config(your_model_config.json) agent.register_skill(skill) agent.run(明天早上9点提醒我给zhangsanexample.com发周报)一旦注册完成当用户发起对话时模型就会根据对话内容自主决定是否调用这个技能。你可以在Agent的日志里看到模型内部的“意图识别—参数抽取—调用函数—返回总结”全过程。3.5 一次真实调用看完整链路咱们设想这样一个对话场景用户“明天早上9点提醒我给李四发一封邮件内容是提醒他提交季度总结。”Agent拿到的输入是这句话模型会做以下几件事判断是否需要调用Skill——发现了“提醒”“发邮件”等关键词决定调用schedule_reminder_email。抽取参数——将“李四”映射为收件人地址如果系统里配置了通讯录主题自动生成为“提醒通知”内容就是“提醒他提交季度总结”发送时间解析为“明天的9点”。填充参数并调用底层函数。函数返回{status: scheduled, send_at: 2024-06-02T09:00:00, task_id: 123456}。模型把返回结果转化为自然语言“好的已定于明天上午9:00给李四发送提醒邮件内容是提醒他提交季度总结。”这一步步看下来你会发现Agent和Skill边界非常清晰模型负责“理解与决策”Skill负责“执行与落地”两边通过一份描述文件“对齐认知”。4. 我在落地过程中踩过的坑和排查技巧4.1 描述写得像说明书模型根本不调用先说一个最常见的坑**Skill的描述写得太偏功能没有写触发条件或者写得太业务化模型在相似场景下会拿不准调不调。**我有一次给一个客户做合同管理系统写了一个“自动提取合同摘要”的技能描述写的是“提取合同文件的关键信息并生成摘要”。上线后用户反馈模型几乎从不调用这个功能。我排查后发现问题出在描述里没有说明“什么时候用”和“什么时候不用”。比如“用户上传了合同文件并要求分析时使用如果只是聊天提到合同二字不要使用”。我把这些边界条件补进去之后调用准确率马上从不到20%提到了80%以上。记住Skill描述的作用是帮模型做判断题不是写功能简介。4.2 结构化输出与函数卡死参数校验是第一道防线另一个高频问题是大模型传参不规矩。你明明定义了枚举值模型还是给你传一个不在枚举范围内的参数你定义了日期格式它给你传“明天上午”。这个问题的根源在于模型是按概率生成文本的生成参数的“正确率”再高也不是100%。我的做法是双保险一是在描述里写清楚示例二是在函数入口处做防御性校验和纠正。就拿时间解析来说我会写一个兼容多种表达的小工具函数专门把“明天上午9点”“2024-06-01 09:00:00”“6月1日早上9点”都解析成标准时间格式。即使模型抽出来的参数不标准底层也能正确执行。不要指望模型永远传对做工程的思路是让系统对“错误输入”也有兜底反应。4.3 多技能之间出现“抢活”怎么办当你的Agent注册了5个以上的技能时新的问题就出现了**多个技能的描述在模型眼中高度相似模型会选错。**比如我有“查询销售趋势”和“生成销售报表”两个技能它们的触发条件都有“销售数据”这几个字模型就容易混淆。解决办法是在描述里把技能的边界写得互斥。比如查询趋势技能明确写“只返回数据趋势不生成图表”生成报表技能明确写“负责生成可视化报表文件需要调用查询接口获取原始数据不直接返回趋势分析”。两个描述在功能边界上做互相补充、互相排除模型的判别准确率就能上来。我在实际项目里还给技能的描述预设了“优先级提示”。比如某技能描述里写“在用户意图偏向深度分析时优先使用”另一个写“在用户意图偏向快速数据报告时优先使用”。这种带有决策偏好的话语模型是能读懂的这让技能调度不再是“看谁关键词命中多”而是真正贴近业务场景。4.4 安全边界别让Agent乱“动手”最后一个严重的问题技能越强大被滥用的风险也越高。如果你的Skill里有“执行Shell命令”“修改数据库”“发送邮件”这类高权限动作一定要做权限控制。我一般使用两层机制一层在描述文件里注明“该技能需要管理员权限普通用户请求时请拒绝并提示联系管理员”另一层在代码入口处做身份校验。举个例子我在邮件技能里加了一个白名单校验只有收件人邮箱在系统通讯录里才允许发送否则返回“收件人不在通讯录中请先添加联系人”。这样做既有业务合理性也防止Agent被脏数据诱导去给任意地址发垃圾邮件。Agent Skills不是越大胆越好边界感才是工程成熟的标志。5. 再往前走一步如何把散落的Skill沉淀成体系5.1 做好技能目录让你的Agent“心中有数”当技能数量超过几十个时它们之间会形成依赖关系。有些技能可以独立用有些则必须依赖另一些技能提供的工具函数。我养成一个习惯每个Skill的目录都保持固定的项目结构里面包含描述文件、源码、单元测试和使用示例。skills/ ├── sales_trend_query/ │ ├── skill.yaml │ ├── main.py │ ├── tests/ │ └── examples/ │ └── demo_usage.md ├── schedule_reminder_email/ │ ├── skill.yaml │ ├── main.py │ └── tests/这个结构的价值在于任何新成员接手项目时不需要靠口口相传去理解每个技能的含义打开描述文件和示例就能快速上手。不要小看这步Agent项目做到后面最大的成本不是写代码而是“维护模型的理解材料”。5.2 用单元测试锁住技能质量代码质量容易被忽略但我要单独强调**模型会以各种奇奇怪怪的方式调用你的Skill你的代码必须比普通代码更健壮。**我给每个Skill写单元测试时不仅测正常的输入还会测“模型可能给出来的脏参数”。比如时间解析我写一个测试用例输入“后天下午三点”预期输出一个标准日期对象输入“2024-6-1 09:00:00”也要输出标准日期对象。这种测试越充分线上出故障的概率越低。有人觉得Agent开发的难点在于模型推理但我的经验是工程问题才是真正消耗时间的地方扎实的单元测试能把这些工程问题提前暴露。5.3 评估和版本管理让技能持续进化最后一个经验点是引入“评估集”。我在每个技能的关键路径上维护一组“输入—期望输出”的测试对话每次迭代模型参数或改写Skill描述后我都用这组评估集跑一遍回归测试。如果某个能力的正确率下降了我能马上定位到是参数变了还是Skill描述变了。这也给了你做版本管理的抓手。给Skill加上一个简单的版本号比如skill.schema_version: 1.2.0把兼容性、历史描述都记录下来。将来如果你要切换底层模型或者升级Agent框架这些版本信息能帮你快速筛出哪些技能需要重新测试。把Skill当成正经代码产品来管它才能支撑起正经的生产级Agent。5.4 一个重要的个人技巧写到最后想分享一个我自己的实操心得**调试Agent Skills时一定要同时看“模型日志”和“函数日志”两个日志你都得追。**很多时候你以为技能坏了翻函数日志发现执行正常结果其实是模型的调度策略有问题压根没调用技能反过来也常见函数报错但你在对话层根本看不到异常因为模型把错误吞了只回复一句“暂时无法完成”。所以我会在Skill入口加一行简单的打印日志输出“接收到参数xxx”在出口也打印“返回结果xxx”。这些小逻辑写代码时多花一分钟排查问题能省一小时。Agent项目可观测性跟不上后面你会寸步难行。Agent Skills这个方向我做了大半年最大的感受是它的价值不只在“让模型能调用工具”这一个技术动作而在于你开始用工程化的方式去组织AI的能力边界。把一段能力封成Skill只是开始如何设计描述、如何编排边界、如何测试回归、如何沉淀成体系才是真正考验功底的地方。希望这篇内容能给你一个相对完整的入手地图你可以先挑一个高频场景写一个最小的Skill跑通全流程再去扩展技能库。试几次之后你会有自己的心得。