我最早被“agent-skills”这个词吸引是在一个很具体的场景里手里的Agent已经能答问题、能调接口、能按用户指令跑脚本但每一次新的任务都要重新写一遍流程提示词把同一段逻辑复制到不同会话里。一旦任务变复杂回复质量立刻下降还经常出现“Agent以为自己会了、实际根本没执行”的状态。后来试着把能力拆成带描述、带参数、带校验逻辑的技能单元再交给Agent统一调度整个系统一下从“会聊天的demo”变成了“能干活的系统”。这篇内容就是想聊聊这个技术思路agent-skills 到底解决什么问题、一个技能单元该怎么设计、怎么从零搭一套可用的技能调度系统以及我在这条路上踩过的几个典型坑。1. 先搞清楚agent-skills 到底在解决什么问题1.1 对话式Agent的能力瓶颈大多数Agent应用刚做出来时本质上都是“带工具的聊天机器人”。用户提一句需求模型判断该调用哪个工具然后把工具结果塞回上下文继续生成。这个模式在小需求下没问题但一旦需求涉及多个步骤、多种数据源、多种输出格式问题就来了第一提示词膨胀。一个功能模块的描述可能需要几百字为了覆盖各种边界情况系统提示词越堆越长模型越往后越容易“选择性遗忘”中间段落。第二功能复用困难。同一个“查询订单状态”的逻辑在这个流程里能用换了会话就失效因为提示词和上下文是绑定的。你想把能力抽出去给别的Agent用几乎等于重写一遍。第三验证缺失。纯提示词方案没有天然的校验机制模型说“已完成”和真正完成之间往往隔着一条鸿沟。技能化的思路就是把这个痛点转过来不把能力当作“一段提示词”而是把它当作“一个可注册、可复用、可验证的单元”也就是skill。1.2 Skills、Tools与Prompt的边界我刚接触这个方向的第一个困惑是Skill和Tool到底有什么区别这么说吧Tool是能力的最小执行单元比如“读取文件”“发送HTTP请求”“查询数据库”。它通常是一个函数有明确的输入输出但本身不含任何业务判断。Skill则完成了一次语义封装它不仅知道“怎么执行”还知道“什么时候该用、执行前要准备什么、执行后怎么校验”。举个例子单纯的“调用天气API”是一个Tool。一个完整的“获取城市天气并生成出行建议”的Skill可能需要两个Tools天气API、地图API一段指令文本告诉Agent流程拿到城市→请求天气→拼接建议→处理异常还要内置一套输出格式校验。Prompt就更底层了它只是给模型的一段指令。Skill可以用Prompt、Tools、示例、校验逻辑共同组成但反过来一段Prompt不能称得上是一个Skill。1.3 什么样的团队/项目适合引入技能体系不是所有项目都急着建技能库。如果你目前只是做一个单会话的问答Bot用户问题和答案之间没有明显的多步骤逻辑那先把对话体验做好就行。但一旦出现这些信号就该动手了多个业务流程共享同一批“能力片段”比如不同业务线都要用“用户身份校验”和“数据脱敏”。Agent经常在同一类任务上重蹈覆辙做错的方式高度一致。你需要给非技术人员授权让他们也能扩展Agent能力而不是每次改逻辑都发版。你对执行质量有要求希望每次Agent调用能力前后都有日志、有检查点。这类场景下skill不是“锦上添花”而是让Agent系统从demo跨向生产环境的必需品。2. agent-skills 的核心抽象一份技能文件到底怎么设计2.1 技能元信息的字段拆解一个成熟的技能单元第一步是把自己的“身份”说清楚。我习惯用一份Manifest来承载这些元信息一般长这样{ skill_id: order_query_v3, name: 订单状态查询, version: 3.2.0, description: 根据订单号查询订单状态、物流信息和最近更新记录。适用于用户咨询订单进度、催发货、查询物流异常等场景。, author: team-commerce, tags: [order, logistics, read-only], entry: skill_main.py, requirements: [], inputs: [ {name: order_id, type: string, required: true, description: 完整订单号通常为20位数字} ], outputs: [ {name: status, type: string, enum: [CREATED, SHIPPED, DELIVERED, REFUNDED]}, {name: tracking, type: object} ], allowed_tools: [commerce.query_order, commerce.query_tracking] }这里有几点容易被忽略description不只是给人类看的它会作为模型挑选技能时的主要依据。写得模糊Agent就可能在“查询库存”和“查询订单”之间犹豫。写得太长又浪费宝贵的上下文窗口。好的描述控制在50到80字之间包含“适用场景”和“不适用场景”。allowed_tools必须显式声明不能给技能无限的工具权限。这是安全边界的第一层。2.2 指令文本的写作策略技能内部的Instruction很容易被写成“操作手册”但模型真正喜欢的是“带分支的决策规则”。我的经验是一份指令文本至少要包含三块第一块是触发条件。明确写清楚什么情况进入这个技能什么情况不进入。比如“仅当用户提供完整订单号时使用本技能若订单号缺失先询问用户补全”。第二块是执行顺序。把正常路径拆成3到5步每步都有可验证的中间结果。不要写“处理好异常”要写“若接口返回超时重新请求最多2次间隔3秒若仍失败返回错误码并附带HTTP状态码”。第三块是终止条件。告诉模型什么时候算“完成”。比如“必须拿到非空的tracking对象才可向用户展示物流信息”。把这三块写清楚模型出错概率会急剧下降。这背后其实就是控制论里的反馈回路给出明确的期望状态Agent才知道该往哪收敛。2.3 依赖管理与技能原子性一个技能可以依赖另一个技能吗可以但这引入了一个非常现实的问题依赖版本冲突。我在项目里见过最典型的场景是技能A依赖“数据脱敏工具v1.0”技能B依赖“数据脱敏工具v1.2”两个技能如果运行在同一个Agent进程里orm的API变了A就崩了。我的建议是两条路二选一轻量方案要求所有底层工具接口保持向后兼容skill层只允许依赖“长期稳定版本”。严格方案每个技能放进独立进程或者独立沙箱通过IPC做进程间通信。后面这条方案虽然重但在多团队协作时能省下大量“你的版本把我顶了”的吵架时间。2.4 技能版本的演进机制技能和代码一样必须能演进。否则修一个bug就要把整个Agent重启太折腾。版本策略上我倾向于模仿语义化版本主版本号变更代表行为不兼容例如输出字段改名次版本号代表新增可选项不影响原有路径补丁版本只修内部逻辑。线上排列时同一时间只允许一个主版本生效其他版本作为“影子版本”用来跑离线评估。等到指标平滑之后再把新版本提升为默认。3. 一套技能从定义到上线的完整链路3.1 技能注册中心给Agent一份“能力地图”技能建好了第一步是注册。注册中心解决的核心问题是“Agent怎么知道有这个技能”以及“在众多技能里选谁”。注册中心至少需要提供两类接口一类面向人用来录入、修改、下架技能另一类面向Agent通过检索接口回答“当前可用技能有哪些”。这里有个经验不要让Agent在推理时遍历全部技能。当技能数超过20个时把全部Manifest塞进上下文既浪费token又会造成选择困难。更好做法是搞两级检索先用关键词/向量检索召回候选技能5到10个再把候选技能的description拼进上下文让模型做最终选择。这种“粗筛精排”的结构参考了搜索引擎的思路跑下来的准确率比直接全量塞入高不少。3.2 执行引擎的调度策略当Agent决定调用某个技能之后执行引擎要做的事情远不止是“run一下脚本”。调度环节必须处理的几个问题包括技能执行超时。有些技能涉及外部API完全不可控。我会给每个技能设一个默认超时时间和可重试标志重试采用指数退避第1次等3秒第2次9秒第3次27秒不再多试。参数校验。输入参数在交给技能之前应先用JSON Schema做一次静态校验。比如订单号必须是20位数字若用户给的是“订单号是123”Agent需要先抽取、清洗、再校验而不是硬着脸皮传给后端。并发隔离。Agent可能同时触发多个技能比如“查询订单状态”和“查询同地址的历史订单”。建议每个技能在独立线程或进程中运行互不干扰。3.3 技能的组合编排从单技能到工作流单个技能做不了复杂业务但技能组合起来就能覆盖完整流程。比如一个“客服查单并处理退货”的流程可以编排成先调用订单查询技能判断订单状态是否满足退货条件若不满足直接返回解释若满足再调用退货登记技能最后调用通知技能生成退货单号并通知仓储。组合编排方式有两种常见做法一种是用代码写死流程也就是传统的DAG工作流。优点是稳定、可控缺点是每条新流程都要开发。另一种是让Agent动态编排把候选技能列表交给Agent由它根据用户意图决定顺序。优点是灵活缺点是结果不稳定可能拿两个技能组合出意外行为。我的实践经验是“混合编排”把流程主干用代码固定把分支节点上的技能选择交给Agent。这样既保证了关键路径不出错又保留了处理长尾问题的灵活性。3.4 可观测性日志、链路与成本技能系统上线之后有一件事绝对不能省全链路可观测。我一般会在技能执行前生成一个traceId贯穿Agent决策、技能调用、工具请求、结果校验四个环节。日志格式建议统一成JSON至少包含以下字段traceId、skillId、version调用时间、耗时、响应码输入参数的脱敏后摘要校验结果是否符合预期有了这些日志你才能回答几个核心问题哪个技能最常用哪个技能总在半夜超时哪个技能被模型选中但最后执行失败没有数据支撑的优化全是拍脑袋。另外技能执行的价格也要记录。LLM的token开销不可忽视尤其是在技能描述文本反复拼接的情况下。建议每周统计一次“技能级token消耗排行”揪出那些又贵又没用的技能果断优化或下架。4. 实操让Agent通过技能库完成一次完整任务4.1 最小技能仓库的结构设计下面我用一个最小化的示例来讲讲怎么落地。假设我们做一个“会议纪要助手”它至少需要两个技能一个是“从录音转文字”另一个是“提取待办项并分配负责人”。技能仓库目录大致长这样skills/ meeting_transcript/ manifest.json skill_main.py instructions.md examples/ example_1.json todo_extractor/ manifest.json skill_main.py instructions.md其中instructions.md是给模型看的指令文本skill_main.py是真正的执行脚本examples/里存几个“输入-期望输出”的示例对。4.2 注册与调用一段可运行的主流程代码核心调度代码不长思路是“加载Manifest → 向量召回 → Agent选定 → 参数校验 → 执行 → 校验输出”。import json from pathlib import Path from pydantic import BaseModel, ValidationError class Skill: def __init__(self, manifest_path: Path): with open(manifest_path) as f: self.manifest json.load(f) self.entry self.manifest[entry] def execute(self, args: dict): # 这里是简单示例实际会放到子进程/沙箱执行 import importlib mod importlib.import_module(self.entry) return mod.run(args) class SkillRegistry: def __init__(self, skill_dir: Path): self.skills {} for manifest_path in skill_dir.glob(*/manifest.json): skill Skill(manifest_path) self.skills[skill.manifest[skill_id]] skill def retrieve(self, query: str, top_k: int 5): # 简化的召回按描述关键词打分实际可用embedding scored [] for skill in self.skills.values(): desc skill.manifest[description] hit sum(kw in desc for kw in query.split()) scored.append((hit, skill)) scored.sort(keylambda x: x[0], reverseTrue) return [s for _, s in scored[:top_k]]实际运行时Agent拿到召回结果把候选技能的description和instructions拼进上下文让模型输出结构化的调用指令{ skill_id: todo_extractor, args: {passage: 下周交付测试报告李工负责环境搭建} }然后再用pydantic校验参数最后执行并校验输出。4.3 一次完整的执行链路用户发来一句话“帮我整理一下昨天周会的录音顺便把待办列出来发给项目群。”系统收到后主控Agent判断需要两个能力于是先检索技能库。第一个候选是meeting_transcript第二个是todo_extractor两者都被召回。随后Agent按流程执行调用meeting_transcript传入录音文件路径得到转写文本校验返回的文本非空并记录token消耗基于转写文本内容调用todo_extractor抽取待办项todo_extractor返回一个结构化的待办列表每一项包含责任人、截止时间、任务描述主控Agent把待办列表整理成群里可读的消息格式发送出去。整个过程有两次技能调用三次模型决策选技能、抽摘要、润色输出。关键路径上如果用代码写死就没有自由度但如果全部让Agent自由发挥第二次调用很可能会选错技能。所以这里用混合编排整合与发送由代码控制技能选择交给Agent。4.4 关于这套Demo的改进建议上面的Demo只是一个走通链路的版本真正生产化还需要补几块召回用向量数据库替换关键词打分否则描述性语言稍有差异就召回不到。技能执行放在沙箱里不能用importlib直接导入。至少用subprocess隔离进程并限制文件系统访问范围。为每个技能的输入输出补充JSON Schema替换掉简单的字典透传。增加缓存比如“会议转录”技能对同一个文件的调用结果可以缓存一天避免重复烧钱。5. 我踩过的坑与技能系统的边界5.1 权限沙箱最不能省的一层保护我第一次上线技能系统时只做了“接口级权限控制”没有做进程级隔离。结果一个测试技能在调用文件读取工具时参数传了个相对路径直接把工作目录下的敏感配置文件给读出来了。从那以后我对所有Engineer技能执行都默认采用“最小权限沙箱”独立操作系统用户运行技能挂载只读根文件系统只开放明确指定的输出路径网络访问默认为disabled只有白名单域名才放行CPU和内存使用上限直接写死在cgroup配置里。这个配置看着重但带来的好处是决定性的即使技能代码写出安全事故影响面也是可控的不会拖垮宿主Agent。5.2 上下文膨胀与技能误调用技能描述写得越多模型选错的概率反而越高这有点反直觉。我试过在description里把所有细节都写全结果Agent经常被无关语句误导。比如“订单状态查询”的代码里为了解释“不适用于售后争议”写了一句“如果用户提到退款请转给售后技能”。结果用户单纯说“我要退款”Agent就跳过了正确的售后技能反而先调用了订单查询。这个教训让我明白description里不要写“不属于你的场景”而是要把每个技能的场景边界放在它自己的instructions里。描述保持精简只说三件事解决什么问题、使用它的前置条件、典型输出是什么。多一句废话都可能成为误导。5.3 版本不兼容带来的连环事故skill升级比普通服务升级更难的地方在于技能的调用方是Agent模型它不会像代码编译器一样在类型不匹配时报警。我经历过一次破坏性变更把某个技能输出字段从customer_name改成了user_name但没有同步修改instructions。结果Agent在执行后续逻辑时找不到预期字段只能自己“推测”数据最终生成了一堆编造的客户名。从那次之后我强制要求所有技能在输出层做“格式契约校验”。每个技能返回给Agent之前先经过一个ts-marshaller类型转换器把内部字段名映射到约定好的schema上。没通过校验的输出宁可报错也不要让模型自行发挥。5.4 怎么给技能做回归测试传统后端测试思路移植到技能系统时有一个核心难点技能的行为受模型影响存在不确定性。直接断言“输出必须等于xxx”基本必挂。我的做法是建一个“黄金样例集”每个样例包含输入、期望约束条件和可接受范围。断言不是查相等而是检查约束是否包含必填字段字段类型是否符合schema是否触发了不该调用的工具返回状态码是否为200或业务成功码。每一个技能变更后都用这批样例跑一遍回归。虽然做不到100%保证线上良好但能把回归风险压到很低。另外我还会定期抽看线上trace尤其是那些“模型选了但是我没想到会选”的技能调用记录。这类记录往往能暴露出技能描述里的潜在歧义是持续打磨技能库最真实的输入。写在最后的一点体会做技能系统这件事最大的收获不是技术上的多复杂而是思维方式的转变从“教模型每一步怎么做”变成了“把能力单元设计好让模型自己来挑选和组合”。我一开始也陷入过过度设计的泥潭恨不得给每个动作都做一个skill结果技能之间的边界越来越模糊模型选起来反而更纠结。后来我把技能库削减到原本的三分之一只保留“业务上高频的、独立的、可验证的”能力整个系统反而稳定了不少。如果你也正准备给Agent加一套技能体系我的建议很简单先用代码写死一个最小可用链路跑通后观察一周看看Agent在哪个环节最容易被“卡住”再把那个环节拆成技能。技能库的成长节奏应该由真实使用中的痛苦驱动而不是由“想做一个完整平台”的冲动驱动。