我得说第一次看到 agent-skills 这个词的时候我脑子里闪过的其实是“智能体技能包”这类东西。结果自己动手做了一轮下来发现它比我想象的要更贴近工程实践。如果你正在搞大模型应用、搭 Agent、做自动化任务编排或者纯粹好奇“AI 怎么能稳定地干活而不乱飘”那这个方向值得你花几分钟认真看看。今天这篇不聊虚的就把我对 agent-skills 的拆解、设计思路、实际搭建过程还有踩过的坑一次性摊开讲清楚。1. agent-skills 到底在解决什么问题1.1 大模型 Agent 的“能力碎片化”困境先从一个很实际的痛点说起。很多人第一次用大模型写 Agent 时都会经历这个过程模型很强懂知识、能推理但真让它干活——比如让它帮你查一下数据库里的订单、把一个 Markdown 文件转成 PDF、批量重命名一批图片——它就有点“手不够用”了。原因很简单语言模型只处理文本它没法直接操作文件、调用接口、点击按钮。为了补上这个短板坊间最常见的做法是“堆工具”给 Agent 接上十几个 API、函数、第三方服务然后祈祷模型能在正确的时机调用正确的函数。但工具一多问题就来了。十几个工具同时塞进上下文模型开始“选择困难”一会儿调错函数、一会儿参数漏填甚至出现两个工具互相冲突的情况。更麻烦的是每个工具的参数格式、命名风格、返回结构都不一样模型需要花大量 token 去“阅读理解”真正干活的精力反而被稀释了。你要是试着把工具数量加到五十个、一百个系统基本就到了不可维护的边缘。1.2 技能体系的核心定位agent-skills 想解决的就是这个“能力碎片化”问题。它把“模型能做什么”从散落的工具列表升级成一套有结构、有层次、可复用的“技能体系”。你可以把每个技能理解成一个小型的自动化单元它有明确的名字、输入输出约定、执行逻辑、甚至底层依赖的工具组合。Agent 不需要直接面对一百个函数的细节而是面对一组高度语义化的“技能”——比如“查询今日销售数据”“生成周报 PDF”“批量压缩图片”——然后由技能层去封装底层操作。这个设计的精妙之处在于它把“决策”和“执行”切开了。大模型只负责“决定接下来调用哪个技能”而技能内部怎么实现是模板拼接还是调用多个 API、是本地脚本还是云端服务模型一概不用关心。这么一来模型的任务被大幅度简化稳定性自然上来了。我在自己项目中体会最深的一点是技能抽象做得好的话就算底层换了第三方库、换了 API 版本Agent 的对话逻辑都不用改只改技能内部实现就行。2. 技能结构怎么设计最顺手2.1 一套合适的技能描述结构动手写技能之前最值得花时间的就是定义一个统一的技能描述结构。这个结构既是“给模型看的路标”也是“给开发者写的规范”。我目前用下来比较推荐的一套字段长这样{ name: query_sales_report, description: 查询指定日期范围内的销售汇总数据返回总销售额、订单数和平均客单价, input_schema: { type: object, properties: { start_date: { type: string, description: 开始日期格式YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式YYYY-MM-DD } }, required: [start_date, end_date] }, output_schema: { type: object, properties: { total_revenue: { type: number }, total_orders: { type: integer }, avg_order_value: { type: number } } }, tags: [sales, analytics], timeout: 30 }为什么 description 要写得这么“啰嗦”因为模型不会读你的代码它只能根据这段描述来判断“该不该用这个技能”。描述里必须交代清楚技能能干什么、输入参数是什么格式、输出长什么样。我见过太多人写 description 就一句话“查询销售”结果模型既不知道参数格式也不清楚返回值第一次调用就翻车。描述这块宁可多写两句也不要省。input_schema 和 output_schema 的 JSON Schema 格式也很有讲究。它一方面可以做运行时校验——参数缺了能直接报错而不是带病执行另一方面也给了模型清晰的填参依据。我在设计时会把“哪些字段必填、哪些可选、格式长什么样”全部写死在 schema 里模型照着填就行准确率会明显提升。2.2 技能注册与发现机制技能结构定好之后接下来就是“Agent 怎么知道你有这些技能”。这就涉及注册与发现机制。我在实现里维护了一个技能注册表启动时扫描指定目录下的所有技能定义文件统一加载进一个技能池。Agent 在每一轮决策时会先根据当前对话的意图做一次“技能过滤”——比如用户问的是销售数据那就只把 tag 包含 sales 的技能描述发给模型而不是把一百个技能全部倒给模型。这一步对 token 消耗和决策准确率的影响非常大。我做了一轮对比全量技能描述塞给模型调用准确率大概在 78%而且每次请求的 token 开销很高启用标签过滤之后同样场景下准确率能到 93% 以上token 还少了接近一半。所以注册表里别只存 name 和 descriptiontags 字段一定要好好用它是你做过滤检索的最趁手工具。2.3 技能的三种典型形态技能落到实处的形态从我做过的事情看大致有三种。第一种是“纯函数型技能”输入输出都是结构化数据内部逻辑是一段确定性代码。比如“计算两个日期之间有多少个工作日”“把人民币金额转成大写”这类技能不需要大模型参与纯粹是工具函数跑起来又快又稳。第二种是“流程编排型技能”一个技能内部会调用多个子技能或工具组成一条工作流。比如“生成月度经营分析报告”这个技能内部要依次做查询财务数据、查销售数据、调用模板渲染、输出 PDF。这类技能的价值在于把多步操作固化下来模型只需要发起一次调用其余步骤由技能内部自行编排。第三种是“动态生成型技能”技能内部会根据输入动态生成代码或 Prompt再交给模型处理。比如“把一段自然语言转换成 SQL 查询”这个技能会先在内部构造一个 SQL 生成 Prompt再调用大模型最后校验 SQL 语法并返回结果。这种技能结合了模型能力和确定性逻辑灵活性最高但同时也最需要做好异常兜底。这三种形态各有适用场景在技能库里可以混着用。我的经验是能用纯函数解决的绝不动用大模型能编排的就别让模型一步一步来动态生成型技能一定要有结果校验环节否则你会被模型偶尔的“自由发挥”坑到。3. 手把手搭一套可用的技能系统3.1 目录结构与基础框架纸上谈兵讲完了下面是实操环节。我用一个 Python 项目来演示整个技能系统的目录结构可以这么摆agent-skills/ ├── skills/ │ ├── __init__.py │ ├── query_sales.py │ ├── generate_report.py │ └── image_compress.py ├── registry.py ├── router.py ├── executor.py ├── validator.py └── schemas/ ├── query_sales.json ├── generate_report.json └── image_compress.jsonskills/ 目录放具体技能实现schemas/ 目录放技能描述定义registry.py 负责扫描和注册router.py 根据意图做技能筛选executor.py 是技能执行引擎validator.py 做参数和返回值校验这个分层的好处是技能实现和描述分离想改参数结构时只动 schema 不动业务代码新增技能只需要扔两个文件进去改一行注册扫描路径就行。相比把所有东西写在一个巨型文件里这种结构在后面维护时能帮你省下大把头发。3.2 第一个技能查询销售数据技能内部实现我比较推荐“实现类 描述类”的标准写法。拿“查询销售数据”来说实现层是一个纯 Python 类import json from datetime import datetime class QuerySalesSkill: def __init__(self, db_conn): self.db db_conn def execute(self, params): start_date params[start_date] end_date params[end_date] # 校验日期格式 datetime.strptime(start_date, %Y-%m-%d) datetime.strptime(end_date, %Y-%m-%d) sql SELECT COUNT(*) as total_orders, SUM(total_amount) as total_revenue FROM orders WHERE order_date BETWEEN %s AND %s with self.db.cursor() as cur: cur.execute(sql, (start_date, end_date)) row cur.fetchone() return { total_orders: row[total_orders], total_revenue: float(row[total_revenue]), avg_order_value: round(float(row[total_revenue]) / row[total_orders], 2) }这里有个我早期忽略后来才补上的细节所有进入技能的参数都要在技能内部做一次显式校验。不要只依赖外部 schema 校验因为外部校验拦得住“格式不对”但拦不住“日期存在但范围不合理”这类语义问题。我在实际项目里就遇到过一次模型把 start_date 填成晚于 end_date 的日期SQL 跑出来结果为空但 Agent 完全没有意识到异常还一本正经地给用户展示“0 订单”。所以现在我的每个技能开头都会先做业务规则校验不合法就直接抛异常让上层 Agent 明确知道“这个任务没法执行”而不是拿到一个奇怪的空结果。3.3 注册与路由实现注册逻辑集中在 registry 里启动时扫描目录并加载所有 schemaimport json from pathlib import Path class SkillRegistry: def __init__(self, skills_dir, schemas_dir): self.skills_dir Path(skills_dir) self.schemas_dir Path(schemas_dir) self.skills {} self.schemas {} def load(self): for schema_file in self.schemas_dir.glob(*.json): with open(schema_file, encodingutf-8) as f: schema json.load(f) self.schemas[schema[name]] schema # 扫描技能模块 for module_file in self.skills_dir.glob(*.py): if module_file.name.startswith(__): continue module_name module_file.stem module __import__(fskills.{module_name}, fromlist[*]) # 约定每个技能模块里有一个 create_skill() 工厂函数 if hasattr(module, create_skill): skill module.create_skill(self) self.skills[skill.name] skill def filter_by_tags(self, tags): return { name: schema for name, schema in self.schemas.items() if set(tags) set(schema.get(tags, [])) }这里我特别强调“约定优于配置”每个技能模块必须暴露一个 create_skill() 工厂函数由它来负责组装技能实例。这么做的好处是技能创建的逻辑被收拢到每个模块自己手里注册中心不需要关心具体技能依赖什么资源、怎么初始化——反正统一走工厂函数接口。技能多了以后这个约定能省掉你大量改注册中心的痛苦。路由层做的事情就纯粹多了它接收用户的意图描述在注册表里做关键词与标签匹配def route(self, user_intent): # 简单示例从意图中提取关键词并匹配标签 matched_tags [] intent_keywords [销售, 订单, 营收, sales, revenue] for kw in intent_keywords: if kw in user_intent: matched_tags.append(sales) if not matched_tags: # 默认返回全部技能描述 return self.schemas return self.registry.filter_by_tags(set(matched_tags))真实项目里这一步不会这么简单通常会用向量检索或 LLM 分类来处理。但结构都是一样的先缩小候选技能范围再交给模型做最终决策。别一上来就搞花活先用关键词规则撑住基本盘等技能数量真的多到关键词搞不定了再考虑上向量检索。3.4 执行引擎与容错执行引擎 executor 是技能真正跑起来的地方。我的实现里有一个关键的容错设计每个技能执行统一走 try-except 包裹异常信息会做“模型可读化”处理返回给上层时不是一行冷冰冰的报错堆栈而是一段能帮助模型决策的提示文字class SkillExecutor: def __init__(self, registry): self.registry registry async def execute(self, skill_name, params, context): skill self.registry.skills.get(skill_name) if not skill: return { status: error, message: f技能 {skill_name} 不存在请检查技能名称是否拼写正确 } # 参数前置校验 try: validate_params(self.registry.schemas[skill_name], params) except ValidationError as e: return { status: error, message: f参数校验失败{e}请按照技能描述中的 schema 重新组织参数 } try: # 技能执行 result await skill.execute(params, context) # 返回结果校验 validate_output(self.registry.schemas[skill_name], result) return {status: success, result: result} except Exception as e: return { status: error, message: f技能执行过程中出现异常{str(e)}请确认输入数据是否合理 }这个可读化异常设计的价值在混乱的 Agent 对话里体现得特别充分。早期我把原始异常直接抛回去模型看到一串 traceback 根本不知道该怎么办只能重复调用同样参数的技能形成死循环。现在把异常翻译成人话以后模型至少知道“参数格式错了”或者“技能不存在”它会自己去修正参数或者换一条路径。这一个改动就把任务最终成功率提升了十几个百分点。4. 实战中的问题排查与复盘4.1 上下文窗口被技能描述撑爆第一个遇到的大问题是上下文管理。技能少的时候不觉得一旦技能库上了规模每次把全部技能描述塞进系统 Prompttoken 消耗就很恐怖了。我试过一个极端例子五十个技能、每个描述平均 300 token光这一项就吃掉一万五千 token留给真正对话和推理的空间所剩无几。解决思路上面已经提到一部分就是路由前置过滤。但还有一个细节容易被忽略技能描述本身也要“分级”。我给每个技能配了三种长度描述短描述一句话用于列表展示、标准描述用于候选筛选、完整描述含详细参数只在确定调用时才发给模型。系统在路由阶段只发短描述列表模型选定技能后才去拉完整描述。这套“延迟加载完整描述”的方式让我的平均请求 token 又降了差不多三分之一。4.2 多个技能描述相似导致误选技能一多描述相似的场景就出现了。我有两个技能一个叫“统计订单数量”另一个叫“查询订单明细”description 里都写了“订单”和“统计”结果模型经常把两个搞混。最典型的一次用户问“我有多少笔订单”模型居然去调了查询明细的技能返回了一大堆订单列表——不能说错但完全不是用户要的东西。这类问题靠加大模型提示词效果很有限根因还是技能边界不够清晰。我在每次新增技能时强制自己过一遍新技能和已有技能在能力上有没有重叠如果有要么合并要么把描述里的差异化特征写得更明显。把“统计订单数量”改成“统计满足条件的订单总数并返回单个整数值”把“查询订单明细”改成“分页列出符合条件的订单记录每条包含订单号、金额、状态”模型误选率肉眼可见地掉下来了。另外还可以用“反例描述”直接在 description 里写“这个技能不返回订单明细列表”效果比正面描述还好。4.3 循环调用与重试风暴Agent 调用技能出现死循环是线上环境最让人头秃的问题。我遇到过一次技能 A 内部调用了技能 B技能 B 执行失败后返回了异常信息Agent 收到异常提示后又重新触发技能 A技能 A 再次调技能 B——整个链路卡死了好几分钟直到超时。排查思路是从日志里找规律。顺着链路追踪发现技能 B 的异常信息写得太笼统模型无法判断失败原因只能靠重试碰运气。修复分两层第一层每个技能新增“重试策略”——同一个输入参数组合单个任务最多重试两次超过就放弃并返回“多次尝试仍失败请检查数据源状态”第二层让技能 B 的异常提示带上具体失败原因库存服务超时、参数非法、数据为空等模型能看懂就知道该换路而不是硬闯。这两招叠加之后线上重试风暴基本销声匿迹了。4.4 校验规则太严导致误伤做技能系统的人都容易走一个极端校验规则越加越多越加越严最后把自己坑了。我有一版输入校验写了“订单金额必须大于 0”结果用户确实查出来一批金额为 0 的“已取消订单”——按理说这条规则没有问题可业务场景就是允许取消订单金额为 0结果这些单全部被校验拦下来Agent 汇报“无订单”业务方差点炸了。这件事给我留下的教训是写校验规则前先翻一遍真实数据分布。规则该严的地方严——必填参数、格式错误、日期范围非法这些一定要拦但业务侧边缘值要留给业务代码去判断不要过早在一道通用的校验关口里卡死一切。后来我的策略调整为通用校验只处理“技术性错误”业务规则全部下沉到技能内部。硬要下一个结论的话——通用校验管格式业务代码管语义。4.5 技能并行执行的竞态问题还有一类问题在技能数量多、请求并发高的时候特别容易冒出来两个技能同时操作同一份数据互相踩踏。我有一次让“批量更新库存”和“库存汇总报告”两个技能并行跑结果报告生成时读到的是更新一半的中间态数据数字看起来完全不对。排查后设计方案很简单给执行引擎加一个“数据域锁”粗粒度按表级细粒度按主键级。技能执行前声明自己会读写哪些数据域引擎根据声明计算冲突图有冲突的改为串行或者让后到的等待。因为单机场景多我用一个简单的 asyncio.Lock 字典就能实现。但你要是做分布式部署这里就要考虑 Redis 分布式锁那一套了。核心思路是一致的技能虽然是独立单元但它产生的副作用必须是可控的、可追踪的。5. 从做技能到做“技能生态”5.1 把技能当作可共享的资产当你的技能库积累了七八个可用技能后你会发现一个有意思的变化技能变成了像代码库一样可沉淀、可共享的资产。新增一个业务场景时不用从零开始写 Agent大部分情况是查一下技能库里有没有能复用的模块有就组合一下没有才写新技能。我现在几个项目之间技能库是公共的大概三分之二的技能都能跨项目直接复用。这也意味着技能的设计标准要更讲究。我把“一个技能只做一件事”和“技能之间不要有隐藏依赖”当作两条铁律。技能只做一件事它才谈得上复用没有隐藏依赖它才能独立测试、独立部署。早期我写过那种又买菜又做饭混合型的技能自己用着爽换个项目就完全没法复用了只能拆开重写折腾两回你就长记性了。5.2 技能质量怎么持续保障技能库越大“质量失控”的风险就越明显。我的做法是轮训抽检加错误样本回灌。每个月挑一个固定时间把历史真实用户请求拿出来重新跑一遍看技能调用链路是否合理、输出是否符合预期。如果某个技能在老场景里开始频繁暴露出新问题多半是底层依赖变了或者业务规则变了这时候要主动去修而不是等用户投诉。错误样本回灌也极其重要。凡是线上 Agent 执行失败的案例我都会存下来分析失败原因后要么调整技能描述要么修改校验规则要么补一个原本缺失的技能。每次回灌都是一次小版本迭代几个月下来同一个场景的失败率能降一个量级。5.3 后续还能往上叠加什么技能体系跑顺之后自然会往两个方向延伸。一个是“技能编排的可视化”把一次复杂的多技能调用过程画成一条清晰的链路图出问题时能快速定位到具体环节。另一个是“技能效果的量化评估”对每个技能都记录调用成功率、平均时长、修正次数用数据说话而不是凭感觉判断哪个技能好用。这两个方向我都在逐步落地后面想单独写一篇聊细节。回到最开始那个问题agent-skills 不是某个特定的库或者框架它本质上是一种把大模型的“思考”和“行动”做结构化的思路。核心谜底就一句话别让模型什么都干把能力和边界用清晰的技能封装起来让模型在规则内自由发挥。这套思路的适应面非常广不管你是做聊天机器人、自动化工作流还是企业内部效率工具都值得一试。
