做 AI Agent 落地的这些日子我越来越觉得“agent-skills”这五个字才是真正卡脖子的地方。模型再聪明没有一套可靠的技能体系它也只能停留在“聊天”阶段干不了实事儿。今天不聊理论直接把我沉淀下来的技能体系设计思路、注册规范、踩坑记录和排查经验摊开讲希望能帮正在搭智能体的朋友少走几步冤枉路。1. 为什么 Agent 需要一套独立的技能体系1.1 从“能思考”到“能执行”中间隔着一层 Skills很多人刚接触 AI Agent 时会有一种错觉只要把模型接口一接什么活它都能干。实际跑通一个端到端任务之后才发现模型确实能推理但推理完往哪落地得有一个“手”去点按钮、调接口、写文件、发请求。如果这些动作全部靠模型内部想象那它永远只能在对话里给你“模拟执行”。所以技能体系的第一层意义就是把模型“想做的事”和“实际能做的事”之间建立一座桥。每个技能是一个可被模型发现、调用、验证的最小功能单元。模型负责决策要调用哪个技能技能负责执行并返回结果。这也是为什么我会专门把技能独立成一套工程体系而不是让 Agent 在代码里随意拼接逻辑。1.2 原生 Function Calling 够用但不够“体系化”现在各大模型厂商都提供了函数调用能力本身挺好用但在复杂业务场景里我遇到了三个具体痛点函数描述不可版本化。业务一迭代函数参数变了所有下游调用方跟着遭殃。函数归属混乱。十个 Agent 共用一套函数谁在改、改了什么、为什么改完全不可追踪。权限边界模糊。有些模块需要写文件有些只能读数据函数级权限很难精细控制。技能体系把这些痛点工程化掉了每个技能就是一个独立小目录自带描述文件、参数定义、执行脚本、依赖声明甚至还可以声明自己需要哪些权限。这样整个技能库可以被版本管理可以被审计也可以被跨 Agent 复用。这才是这套“agent-skills”结构真正的价值所在。1.3 哪些项目适合引入技能体系先说结论不是所有 Agent 项目都要上技能库。判断标准很简单如果 Agent 需要执行的外部动作超过三个且有明确的输入输出边界那就适合。我做过一个内部数据问答机器人最初只有两个查询函数直接用函数调用就行但后来加了报表生成、邮件发送、日程安排三个功能后代码就乱了。引入技能体系之后每个功能独立成技能Agent 只通过技能描述来决策维护成本降了一大截。反过来如果只是做一个纯文本问答、摘要生成没有外部动作那技能体系就是过度设计。这也是我特别想强调的一点技术选型永远服务于实际需求不是为了结构好看。2. 整体设计思路注册、发现、执行与闭环2.1 技能库的四层结构我的技能体系分四层每一层都有明确职责彼此之间不耦合技能注册表所有技能的名字、版本、入口文件、权限声明都登记在册。技能描述层用自然语言写清技能“什么时候用”“输入是什么”“输出是什么”这是给模型看的说明书。技能执行层真正的逻辑代码、脚本、依赖工具。技能结果层统一的返回格式包含状态码、数据、错误信息。四层结构的好处在于模型看到的“技能”和实际跑的“代码”是分离的。模型只需要读描述层执行层透明黑盒。这样即使内部逻辑优化只要描述不变模型侧就不受影响可以做到技能侧平滑升级。2.2 技能发现机制怎么让模型找到对的技能模型不可能在每次对话时都去读所有技能源码它只能依赖描述文件来判断该调用哪个。所以技能发现机制的核心就是描述文件要写得好、可检索。我给每个技能的描述设置几个标准块核心功能一句话说清这个技能干了什么。触发场景列出哪些场景一定用这个技能。边界条件什么情况下不要用避免模型乱调。参数说明每个参数的作用、格式、是否必填。返回说明模型拿到结果后如何解读。这套描述格式写多了之后模型基本不会选错技能。我在一次内测里同时注册了“查询用户订单”和“查询用户退款”两个技能语义本身很接近但靠边界条件描述模型的命中率能达到百分之九十以上。2.3 执行闭环感知、决策、执行、校验Agent 调用技能不是一个单向过程而是闭环。完整链路是Agent 从用户输入和上下文感知需求决策调用哪个技能并填充参数技能执行后返回结构化结果Agent 再校验结果是否符合预期。如果不符合它应该能主动修正参数并重新调用而不是直接把错误甩给用户。这个小闭环让我少了很多“假执行”的尴尬有些模型的返回看似合理但实际动作没有发生。有了校验环节这类问题基本能被即时拦截因为技能返回结果里带了执行状态码模型一眼就能判断有没有成功。3. 核心细节解析与实操要点3.1 skill.yaml 的字段定义与规范每个技能的元数据文件是 skill.yaml我把它当成技能的“身份证”。字段不算多但每个字段背后都有讲究字段必填作用与注意事项name是技能唯一标识建议用 snake_case不要用空格和连字符version是语义化版本号改动参数或逻辑时必须升版本description是给模型看的说明书内容要侧重“触发条件”和“边界”不要写实现细节parameters否声明输入参数类型、是否必填、取值范围、默认值capabilities否权限声明比如 network、file_write、admin用于安全控制entry_point是指定执行入口脚本比如 run.pytags否辅助分类的标签方便人工管理模型不需要读3.2 怎么让技能描述更靠谱这个坑我踩得很深。一开始我写 description 特别简单比如“查询订单信息”然后就发现模型经常把“查询退款订单”的需求也调到这个技能上。后来我把 description 重写为当用户询问订单状态、物流信息、订单详情时使用。只处理正向订单不处理退款订单、纠纷订单、评价订单。输入必须是订单ID。如果用户提供的是手机号需要使用“客户手机号查询”技能。改了之后误调用率立刻下降。核心原因在于模型不是通过理解代码意会能力而是通过描述文字来匹配用户意图。描述写得越接近真实自然语言场景模型选择就越准确。我再补一句description 里不要写“本技能用于”这种干巴巴的结构要模拟用户在真实场景下可能发出的多种表达方式这样模型的语义匹配能力才能发挥出来。3.3 输入参数的约束与校验参数设计直接影响 Agent 调用的成功率。我把参数规则总结成三条第一条类型约束尽量严格。整数就是整数字符串就是字符串布尔值只允许 true/false。不要出现“类型可以是数字或字符串”这种模糊定义模型一旦发现可选项多就容易出错。第二条必填参数必须有明确的来源说明。如果参数必须来自用户前文就写清“需要用户提供”如果可以从上下文推断也要写清推断逻辑。比如天气查询的城市参数如果用户只说了“今天出门要带伞吗”模型应该默认用用户定位城市这里如果不写清模型就会自己造一个城市名。第三条所有参数都要给一个默认值或空值策略。模型偶尔会漏填参数如果技能侧没有兜底逻辑一整套调用就会直接崩溃。3.4 技能的版本管理与权限控制版本管理这个点很多人会忽略但技能接口一变影响的是所有 Agent 装配线。我在体系里加了一个硬性规则skill.yaml 中 version 递增时必须有 changelog 文件记录变更。这样出现问题可以快速回滚也方便排查某个技能是哪次变更导致行为异常。权限控制上我按风险等级把技能分三类只读类只查询数据不允许任何写操作。写操作类允许创建、修改业务数据但要经过二次确认。高风险类涉及删除、批量操作、外部发送必须由管理员审批。这个设计让我在实际落地中避免了不少麻烦。有一次模型擅自调用了一个发送通知的技能因为权限配置里限制了写操作需要二次确认结果被及时拦截没有发给真实用户。4. 实操过程从零实现一个“竞品价格监控”技能4.1 技能骨架搭建我会用一个最常见的场景——“竞品价格监控”技能来走一遍完整开发流程。这个技能的目标是根据用户提供的商品页面链接定期抓取价格在降价超过阈值时给出提醒。目录结构如下price_monitor/ ├── env.json ├── skill.yaml ├── run.py └── utils/ └── fetcher.pyenv.json 用来声明依赖环境比如需要的 Python 包、运行超时时间、网络权限。这是一个很关键的工程化设计因为技能库一旦膨胀不同技能会依赖不同版本的库环境隔离做不好就是灾难。我每个技能都尽量用独立虚拟环境或容器来跑env.json 就相当于这个技能的环境快照。4.2 编写 skill.yamlname: price_monitor version: 1.2.0 description: 监控指定电商平台商品价格变化。当用户想了解某商品历史价格走势、 询问当前价格是否处于低位、希望设置降价提醒时使用。 输入必须为商品详情页完整链接。仅支持自营商品不支持第三方店铺商品。 产物是价格趋势摘要和降价提醒配置。 parameters: product_url: type: string required: true description: 商品详情页链接必须来自用户提供不可自行推断。 track_days: type: integer required: false default: 30 description: 追踪时间范围单位为天取值范围1到90。 notify_threshold: type: number required: false default: 5 description: 触发降价提醒的百分比阈值比如5代表下降5%时提醒。 capabilities: network: true file_write: false entry_point: run.py tags: - ecommerce - price_monitor这里有几个细节值得说capabilities 里我明确写了 file_write: false这表示这个技能只能访问网络不能写本地文件。就算模型误判要求技能保存结果执行层也会直接拒绝。4.3 编写执行脚本 run.py下面是我简化后的核心代码重点看参数接收和结果返回结构import json import sys from utils.fetcher import fetch_price_history def load_input() - dict: 从标准输入读取技能参数参数由调度层注入。 raw sys.stdin.read() if not raw: return {} try: return json.loads(raw) except json.JSONDecodeError: return {} def validate_params(params: dict) - list: 校验必填字段与取值范围返回错误列表空列表代表通过。 errors [] if not params.get(product_url): errors.append(缺少必须参数: product_url) if not str(params.get(product_url, )).startswith(https://): errors.append(product_url 必须是 https 链接) track_days params.get(track_days, 30) if not isinstance(track_days, int) or not (1 track_days 90): errors.append(track_days 必须是 1 到 90 之间的整数) return errors def main(): params load_input() errors validate_params(params) if errors: # 统一输出结构status error data print(json.dumps({ status: failed, error: errors, data: None }, ensure_asciiFalse)) sys.exit(1) product_url params[product_url] track_days params.get(track_days, 30) threshold params.get(notify_threshold, 5) # 调用工具函数拉取价格历史 try: history fetch_price_history(product_url, daystrack_days) except Exception as exc: print(json.dumps({ status: failed, error: [f抓取价格历史异常: {str(exc)}], data: None }, ensure_asciiFalse)) sys.exit(1) # 计算当前价格与历史最低价 current_price history[-1][price] min_price min(item[price] for item in history) drop_ratio (min_price - current_price) / min_price * 100 result { status: success, error: [], data: { current_price: current_price, min_price: min_price, drop_ratio: round(drop_ratio, 2), track_days: track_days, notify_threshold: threshold, history_sample: history[-7:], } } print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()输出故意做成统一的结构这就是我前面说的“技能结果层”。无论技能内部多复杂对外输出的格式完全一致Agent 解析结果时的代码只需要写一遍不需要为每个技能单独适配。4.4 集成到 Agent 调度循环写好了技能还要让 Agent 能发现它并调用它。调度层会维护一份技能目录目录里是每个技能的 name、description、parameters 摘要。每次 Agent 对话时调度层根据用户意图在技能目录里做检索把最相关的几个技能描述注入到模型上下文里。下面是简化后的关键逻辑skills_index load_skill_index() # 从所有 skill.yaml 解析而来 matched_skills semantic_search(user_message, skills_index, top_k5) # 将这5个技能的描述和参数拼接到系统提示词中 system_prompt build_prompt(matched_skills) # 模型返回调用意图后调度层负责实际执行 if should_call_skill(model_response): skill_name model_response[skill] params model_response[arguments] result execute_skill(skill_name, params) # 运行 run.py传入参数 JSON # 把 result 作为工具结果反馈给模型继续推理这里有个执行细节我给 execute_skill 设置了超时控制一般来说单技能执行时间超过 30 秒直接杀掉并返回超时错误避免模型等待太久或陷入死循环。还有并发控制同一技能同一时间只允许一个实例运行防止资源竞争。4.5 自测与验证技能写完必须先做自测再装进 Agent 里。我通常跑两步第一步手动给 run.py 喂一份参数 JSON验证输出格式第二步模拟模型调用确认描述文件的意图匹配是否准确。# 手动测试脚本 echo {product_url: https://example.com/item/12345, track_days: 30} | python run.py输出结果正常后再打开一个调试命令直接把技能描述和一段模拟用户请求发给模型看它能不能正确选中技能、填对参数。这一步非常重要因为这一步抓出的问题通常都是 description 描述不清晰导致的。5. 常见问题与排查技巧实录5.1 现象对照表我把过去项目里遇到的真实问题整理成了一张速查表每个问题后面都标注了我总结的定位方法现象可能原因排查思路模型经常跳过技能直接瞎编答案描述里没有写清触发场景检查 description 是否覆盖了用户多种表达参数被填错比如链接少了协议头参数说明没写格式要求在 parameters 描述中加正则约束和示例技能执行了但结果显示给用户很乱结果层没有统一 schema按统一 JSON 结构返回并加 human_readable 摘要多个技能语义相近模型总是调错描述缺少边界条件补上“什么时候不使用本技能”的说明技能偶尔卡死进程不退出脚本没有超时控制调度层强制超时并给技能侧加锁更新技能参数后旧 Agent 报错技能版本不兼容严格执行 version 变更记录和新参数兼容策略5.2 一个典型的排查过程有一次线上项目用户总是反馈“问价格Agent 总回答没查到”。我查了日志发现模型确实命中并调用了 price_monitor 技能但执行结果却是 failed错误信息是“缺少必须参数 product_url”。这很反常因为用户消息里明确带了一个商品链接字符串。继续翻日志之后我发现问题出在参数传递上。模型把用户消息里的链接放在 arguments 里的字段名是 product_link而技能侧要求的是 product_url两个名字不一致校验当然过不去。这类问题不属于代码 bug而是描述文件和模型生成之间的语义对齐问题。解决方式我给了一个双保险技能侧增加参数别名兼容也就是如果检测到常见别名就自动映射到标准字段同时我在 description 里明确加了“参数名必须是 product_url不接受任何别名”。双管齐下后续就很少再出现这种问题。5.3 调试三板斧第一板斧是技能自检命令。每个技能都提供一个skill_self_check脚本它会做四件事校验 skill.yaml 格式、检查依赖是否齐全、跑一次最小参数用例、确认输出符合 schema。我要求在提交技能代码之前必须过一遍百分之八十的基础问题都能在这里暴露。第二板斧是会话内调试日志。我让调度层支持一个 debug 开关打开后可以在日志里看到模型收到了哪些技能描述、它选择了哪个技能、它填了什么参数、技能返回了什么内容。这套日志帮我节省了大量定位时间每次调试只需要看这一条链路。第三板斧是结果等级确认。我会在技能里加一个“返回结果置信等级”字段让技能在执行完后对自己的结果做一个基本判断比如数据源是否完整、是否存在缺失字段。模型读到低置信度结果时会自动提示用户“本次查询数据有限仅作参考”这里其实就是一道人为设置的兜底逻辑有效避免模型拿残缺数据硬着头皮编结论。5.4 上下文膨胀问题技能库逐渐变大之后我遇到了一个新的性能瓶颈每次对话都注入所有技能的描述token 消耗大得吓人模型的选择注意力也被分散错误调用率不降反升。解决办法是把技能检索改成两段式。第一段用一个轻量级召回模型只根据用户输入和技能关键词列表快速缩小范围召回 5 到 10 个候选第二段才把这几个候选技能的完整描述拼进上下文交给大模型做精准选择。这套组合下来上下文基本能控制在合理范围技能再多也不怕。6. 关于技能体系设计的一些思考做 agent-skills 这段时间我最大的体悟是技能体系的核心不是“让模型多能干”而是“让我们能给模型的行为兜底”。模型负责发散技能体系负责收敛。每一次技能调用都是模型自由意志向工程规范的一次靠拢。这个中间层的设计很大程度上决定了一个 Agent 项目是活在 Demo 里还是活在真实业务里。如果要从零开始落地一套技能体系我的建议是小处着手。先选三五个真正被高频使用的动作把它们打磨成高质量技能跑通注册、发现、执行、反馈的完整闭环再逐步扩充。千万别一上来就想管理几百个技能那样只会陷入维护泥潭。技能描述的质量永远比技能的数量重要得多。还有一个小技巧给技能的 description 写完之后自己站在用户角度多读几遍“如果我是用户我会怎么自然地说出这个需求”然后把几种典型说法直接写进描述里。这么做了之后模型意图匹配的准确率比我预想中提升明显。技能这个活说到底就是一门把用户语言翻译成机器动作的手艺细心一点回报率很高。