“agent-skills”这个标题我在技术社区看到时第一反应是又有团队把 Agent 玩明白了。这两年我一直在做 AI Agent 方向的工程化落地接触了各种各样的智能体项目最大的体会是——模型能力决定了下限但技能Skills的工程化程度决定了上限。很多团队花大力气把 Agent 框架搭起来跑通了一个 Demo结果一上真实业务就露馅Agent 只会“聊天”不会“干活”或者技能写了一堆却经常选错工具、输出格式混乱、内部报错无人处理。这些问题的根子几乎都出在“技能”这一层没设计好。所以今天这篇文章我就围绕 agent-skills 这个话题把我踩过的坑、总结的设计方法和可以直接照着抄的实操流程一次性讲透。不管你是刚接触 Agent 的初学者还是已经在业务中上线了智能体的开发者这篇文章都比较适合你通读一遍。文章里不会有那种“定义一个工具函数让模型去调”的敷衍讲解而是从技能的本质讲起逐步拆解如何设计、实现、测试和维护一套真正可用的技能体系。1. Agent Skills 到底是什么从会聊天到能干活1.1 技能不是工具函数这么简单很多教程把 Agent 技能等同于“把一个 Python 函数暴露给模型调用”这个说法不能算错但它严重低估了技能设计的复杂度。我见过太多团队代码里定义了几十个函数模型也能通过 Function Calling 机制去调用但实际效果却一塌糊涂。原因就在于他们只是把函数“挂”上去了却没有把它当作一个独立的“技能”来设计。我习惯用一个更严格的定义一个 Agent 技能是“意图识别 执行逻辑 输出契约”三位一体的能力单元。意图识别靠的是技能描述Description执行逻辑是真正跑的业务代码输出契约则是返回给模型的结构化格式。这三者缺一不可。只看执行逻辑那不叫技能那叫函数只看意图识别那叫 Prompt只有把三者完整地封装起来模型才能在面对用户请求时准确判断“该用哪个技能”以及“怎么用”。我举一个实际例子。假设你要做一个订单管理 Agent需要让它具备“查询订单状态”的能力。简单做法是写一个函数def get_order_status(order_id: str) - dict: # 查询数据库逻辑 return {order_id: order_id, status: shipped}然后把这个函数配一个描述注册到模型调用列表里。看起来没问题对吧但上线后发现用户说“我的东西怎么还没到”模型不知道要调用这个函数用户说“帮我查一下快递”模型调用了却把 order_id 参数传成了一个空字符串。为什么因为技能描述里没写清楚“这个技能负责什么场景、需要什么参数、参数从哪里获取”。这就是我把技能描述看得比代码本身还重要的原因。1.2 技能、工具、插件、工作流的关系在深入设计之前先理清楚几个容易混淆的概念。技能Skill、工具Tool、插件Plugin和工作流Workflow这四个词在很多文章里被混着用但它们的定位其实有明显区别。概念粒度核心特点典型用途工具Tool最小单一功能无状态查询天气、发送邮件、执行计算技能Skill中等意图识别 执行逻辑 输出契约订单处理、文本摘要、数据可视化插件Plugin较大多个技能或工具的打包发布企业办公套件打包文档处理、日历、邮件等工作流Workflow灵活预定义的流程编排先查询订单再推送通知再生成回执我的理解是技能是介于工具和工作流之间的关键抽象层。工具更像“积木块”技能是“带说明书的积木组合”工作流则是“照着图纸搭好的成品”。如果你的技能设计得足够好工作流的搭建会非常轻松因为每个技能都已经封装了清晰的边界反过来如果技能一团模糊那工作流怎么编排都会出问题。为什么这个区分很重要因为它直接影响你的系统架构。把工具直接暴露给 Agent 会导致两个问题一是模型面对太多原子操作时选择困难二是每次调用都缺少上下文约束容易用错参数。而技能层的作用就是把多个工具操作和必要的校验逻辑收纳到一个有明确“使用意图”的单元里。比如“下单”这个技能内部可能调用库存工具、支付工具、通知工具但暴露给模型的只有一个统一入口。2. 设计一套可复用的技能体系核心原则与方法2.1 技能的原子性一个技能只做一件事技能设计的第一原则是原子性但这跟“函数尽量小”不是一回事。函数追求代码层面的单一职责技能追求的是“意图层面的单一职责”。也就是说一个技能应该对应一类完整的用户意图而不是一个函数级别的操作。我举个反例。之前有个项目一开始为了省事把“查天气”和“查空气质量”合成了一个技能。结果发现用户说“今天适合跑步吗”的时候模型不知道该调用这个技能还是让用户明确一下要查哪个参数。后来拆成两个技能配合一条路由逻辑效果立刻好了很多。为什么因为用户表达意图时脑子里通常只有一个核心需求技能边界模糊模型就难做选择。那是不是技能拆得越细越好也不是。拆到极端每个技能就退化成工具了模型反复编排多个技能容易造成上下文混乱。我在实操中建议遵循一个判断标准如果一个技能内部需要两个以上“独立决策点”就应该拆如果一个技能执行完还要经常被人为检查“结果是否满足上一个意图”那说明粒度太小应该合并。简单说技能的边界应该对齐用户的业务意图而不是对齐代码函数。2.2 描述即接口为什么技能描述决定 Agent 智商这是我最想强调的一点。在传统软件开发中接口靠的是函数签名、类型定义和文档在 Agent 开发中模型看得懂接口但它选择接口的唯一依据是你写的自然语言描述。技能描述写得好不好直接决定 Agent 是“聪明”还是“智障”。我总结了一个技能描述模板包含四个必备部分技能名称简短且语义唯一不要用缩写或生僻词。适用场景清晰说明“什么类型的请求应该使用本技能”最好包含正反例。参数说明每个参数的用途、类型、必填性和取值示例。返回值说明返回给模型的数据结构长什么样以及对后续流程的提示。这里我用“查订单状态”的技能来做示范这是一个可以直接参考的描述写法技能名称: query_order_status 适用场景: 当用户询问订单的当前状态如待支付、已发货、已签收时使用。 不适用的场景: 用户询问物流轨迹明细时请使用 query_logistics_detail 技能。 参数: - order_id (string, 必填): 订单号通常为纯数字或英文字母组合可在订单列表中找到。 - customer_query (string, 选填): 用户的原话用于补充上下文如包含时间信息可帮助过滤。 返回值: - status (string): 订单状态枚举值取值 pending / paid / shipped / completed / canceled。 - detail (string): 面向用户的可读描述。 - updated_at (string): 订单状态最后更新时间ISO8601 格式。你注意看这个描述里的几个细节。我不仅写了“适用场景”还写了“不适用场景”——这一条很关键它告诉模型不要把物流明细的请求导到这个技能来参数说明里给了类型、必填性和来源提示返回值说明里用了枚举值。这样一套描述写下来模型基本不可能选错入口。2.3 技能的分类组织从信息获取到动作执行技能设计还有一个容易被忽略的维度分类。技能多了以后如果没有分类体系模型就像在一个堆满杂物的大仓库里找东西翻半天也找不到要用的那把螺丝刀。我的做法是按“能力域”划分层级每个技能在加载时带上元标签Tags并在注册表里维护一层索引。常见的分类我有四类感知类技能负责获取信息包括查询数据库、调用外部 API、读取文件等。这类技能只读不产生副作用适合放在高频调用区。操作类技能负责执行业务动作比如创建订单、发送消息、修改配置。这类技能通常有副作用必须设计严格的入参校验和幂等保护。推理类技能负责处理数据、执行算法和生成分析结论比如文本摘要、数据计算、报表生成。这类技能内部可能调用模型也可能用纯代码逻辑需要关注性能和超时问题。记忆类技能负责读写 Agent 的外部记忆向量库、KV 存储。这类技能比较特殊因为它不是面向业务用户的而是面向 Agent 自身状态管理的。我建议在注册表里给每个技能打上这四类标签并且在技能描述的起始位置明确标识类别。这样做的好处是当技能数量达到几十个甚至上百个时模型可以通过标签初步筛选再结合语义描述做精确匹配选择准确率会提高不少。3. 实操笔记从零实现一个 Agent Skill 全流程3.1 定义技能接口与输入输出契约我直接结合自己项目里的代码演示如何从零实现一套技能体系。先说明技术选型我用的是 Python加载方式采用的是“装饰器注册 模块扫描”这样新增技能只需要放一个文件就能自动加载不需要频繁修改主程序。先定义一个基础的技能基类统一接口。from abc import ABC, abstractmethod from typing import Any, Dict, Optional class BaseSkill(ABC): # 技能元信息也就是前文提到的描述字段 name: str description: str tags: list [] abstractmethod def execute(self, params: Dict[str, Any], context: Optional[Dict[str, Any]] None) - Dict[str, Any]: 执行技能核心逻辑 raise NotImplementedError def validate(self, params: Dict[str, Any]) - Dict[str, Any]: 参数校验默认不做额外处理可在子类覆写 return params这里我做了一个有意思的设计把 execute 和 validate 分开。很多项目把校验逻辑堆在 execute 开头模型调用频繁时报错率很高因为参数问题会在执行中途才暴露。拆开之后技能框架可以在调用 execute 之前统一执行 validate提前拦截非法参数。接下来是具体的技能实现。我要实现一个“当日订单汇总分析”的技能它的作用是读取订单数据汇总金额和数量并按商品类目做聚合。这个技能是典型的“推理类技能”。import json from datetime import date class SummarizeDailyOrdersSkill(BaseSkill): name summarize_daily_orders description 按日期汇总订单金额、订单数量并按商品类目输出聚合结果。 tags [inference, orders, analytics] def validate(self, params): if date not in params: raise ValueError(缺少必填参数: date) return params def execute(self, params, contextNone): target_date params.get(date, str(date.today())) # 这里假设从数据仓库读取数据实际项目中可替换为SQL查询 orders load_orders_from_warehouse(target_date) total_amount 0.0 total_count len(orders) category_agg {} for order in orders: total_amount order[amount] cat order[category] category_agg[cat] category_agg.get(cat, 0) order[amount] return { date: target_date, total_count: total_count, total_amount: round(total_amount, 2), category_amount: {k: round(v, 2) for k, v in category_agg.items()}, }你可能会说这不就是一个普通类吗关键在后面——我需要一个装饰器让这个类能被框架自动收集和注册。3.2 准备工作技能注册与加载机制技能的注册和加载是整条链路里决定“扩展性”和“系统复杂度”的分水岭。我采用的方案很简单先用一个装饰器把类注册进一个全局注册表再通过文件扫描自动导入所有技能模块。先看装饰器和注册表# skill_registry.py _SKILL_REGISTRY: Dict[str, BaseSkill] {} def register_skill(cls): instance cls() _SKILL_REGISTRY[cls.name] instance return cls def get_skill(name: str) - BaseSkill: return _SKILL_REGISTRY.get(name) def list_skills() - list: return list(_SKILL_REGISTRY.keys())然后在技能文件里给类打上注册标记from skill_registry import register_skill register_skill class SummarizeDailyOrdersSkill(BaseSkill): ...最后做一个扫描加载器在项目启动时自动扫描指定目录下的所有技能模块import importlib import pkgutil import skills_package def load_all_skills(): for module_info in pkgutil.iter_modules(skills_package.__path__): importlib.import_module(fskills_package.{module_info.name})这套结构的价值在于新增一个技能时只需要新写一个文件、放一个类、打一个注册标记不需要改动任何路由代码或者模型调用代码。我之前在项目里从 10 个技能扩展到 60 个技能全靠这套机制撑着没有产生“改一处崩一片”的情况。3.3 关键一步技能描述与模型的对接方式技能注册表准备好了接下来最关键的就是把技能列表以模型能理解的方式对接过去。对接方式因模型而异大致有两种主流形式我都实际落地过。第一种是 Function Calling / Tool Use 形态。这种模式下模型在对话过程中自己判断是否需要调用技能、调哪个、传什么参数。你需要把技能信息转换成模型要求的 JSON Schema 格式。我通常写一个适配器函数从注册表里的技能对象动态生成 Schemadef build_tool_schema(skill: BaseSkill) - dict: # description 就是技能描述导入时从技能的 description 字段读取 return { type: function, function: { name: skill.name, description: skill.description, parameters: { type: object, properties: get_skill_parameters(skill), required: get_skill_required_fields(skill), }, }, }这里要特别注意description 字段必须完整因为我之前测试过很多模型的 Tool Choice 准确性高度依赖 description 的措辞。我会避免在描述里写过于模糊的词语比如“处理订单”因为“处理”这个动词太宽泛——到底是查询、修改还是取消模型无法判断。写清楚“当用户要求查看现有订单的当前状态时”就比“处理订单”好很多。第二种是纯 Prompt 注入形态。当模型不支持 Function Calling 时我会把所有技能的名称和适用场景压缩成一个表格放进 System Prompt。这种方案的 token 消耗比较大技能太多时不推荐。我一般只在技能数少于 20 个且模型不支持工具调用的时候使用。我的建议是尽量优先选用第一种形态。它更节省 token因为只有模型判断需要调用时才会产生额外的工具调用消息同时它的结构化程度更高参数传递不容易出错。3.4 全链路测试与回归模拟模型级调用写完技能和对接层之后很多团队就直接上线了这是一个大坑。我强烈建议先做一轮“模型级”的集成测试也就是模拟真实对话流程看模型是否能在多技能场景中作出正确选择。这里分享一个我经常用的测试脚本使用 pytest 风格# test_skills_llm.py import pytest from runner import run_conversation pytest.mark.parametrize(user_message, expect_skill_name, [ (帮我汇总一下昨天各品类的订单金额, summarize_daily_orders), (今天天气怎么样, query_weather), (我要把订单 A20240001 改为已发货, update_order_status), ]) def test_skill_route(user_message, expect_skill_name): result run_conversation(user_message) assert result[selected_skill] expect_skill_name, ( f期望调用 {expect_skill_name}实际调用 {result[selected_skill]} )除了路由测试我还会做“参数正确性测试”。比如测试“帮我查一下昨天的订单汇总”模型如果正确解析出 date 参数为昨天的日期测试通过如果传了个空字符串或解析错误测试失败。这一步非常必要因为很多时候技能选对了参数却传错了最后整个流程还是崩。另外我还强烈建议把测试数据“沉淀”下来。每次发现模型选错技能把对话样本连同“正确期望”一起加入回归测试集。技能描述或者业务逻辑改动后跑一遍回归能大幅减少“修好一个 bug 又引入另一个 bug”的问题。我在团队里把这件事固化成了流程每个迭代必须过一遍回归集宁可慢一点也不能让线上 Agent 开倒车。4. 实战中踩过的坑常见问题与排查技巧4.1 Agent 频繁选错技能怎么定位原因这是被问得最多的问题也是最难排查的问题。技能很多时模型偶尔选错技能原因往往不是单一维度。我总结了一套排查清单。第一步确认技能描述是否覆盖了用户的真实表达。用户不会按你的术语说他会说“帮我看看那单到哪了”不会说“查询物流轨迹”。如果描述里的关键词跟用户口语化表达不匹配模型就容易答非所问。我通常会把真实用户语料导入找出那些“引发误选”的句子然后优化对应的技能描述。第二步检查技能之间是否存在边界重叠。比如“查询订单状态”和“查询物流轨迹”这俩边界如果含混模型就会在两者之间摇摆。我的做法是给它们各写一段“不适用场景”并在描述里互相指向对方技能等于给模型一条路标。第三步检查技能数量是否过多。当技能超过一定量级在我经验里大约是 30 个以上模型的选择准确率会明显下降。这时候单靠优化描述已经不够需要增加一个“技能路由层”比如用一个轻量分类模型先把请求分配到某个技能域再让大模型在域内做精确选择。不要指望单一大模型在几百个选项里能稳定找出最优项。4.2 技能内部出错导致整个对话崩溃这是一类非常隐蔽的问题。Agent 调用技能出错本身不可怕可怕的是错误信息没有被“兜住”导致整个对话进程崩溃或者把内部堆栈直接暴露给用户。我处理这类问题的方案是在技能框架层加统一的异常捕获和错误格式化。任何技能抛出的异常都会被包装成一个标准错误结构包含错误码、可读的信息和建议的下一步动作。来看一个我项目里的实际实现def safe_execute(skill: BaseSkill, params: dict, context: dict None) - dict: try: validated_params skill.validate(params) result skill.execute(validated_params, context) return {ok: True, skill: skill.name, data: result} except SkillParameterError as e: return {ok: False, error_code: PARAM_ERROR, message: str(e), suggestion: 请根据参数说明补充完整信息。} except ExternalServiceError as e: return {ok: False, error_code: SERVICE_UNAVAILABLE, message: 外部服务暂不可用, suggestion: 请稍后重试或联系客服。} except Exception as e: # 兜底分支避免未知异常炸掉整个对话 return {ok: False, error_code: INTERNAL_ERROR, message: 系统内部错误已记录日志。, suggestion: 请重新描述您的需求。}你在实际项目中这样的错误结构还应该加上日志追踪 ID方便排查。别小看这层包装它是 Agent 在生产环境“活下来”的根基。如果没有统一兜底技能一异常用户的对话就会卡死而且你完全不知道问题出在哪。4.3 技能内部错误码设计不统一我合作过的一些团队技能越写越多但错误码特别乱有的返回字符串有的返回 int有的甚至只返回裸异常。这给排查和后续的自动恢复机制带来了很大的负担。我的建议是尽早定义一套错误码规范哪怕一开始简单点也没关系。可以在项目里约定一个枚举类把常用错误码统一定义from enum import Enum class SkillErrorCode(str, Enum): PARAM_ERROR E1001 SERVICE_UNAVAILABLE E2001 DATA_NOT_FOUND E3001 PERMISSION_DENIED E4001 UNKNOWN_ERROR E9999这套错误码的核心价值不是给用户看而是给上游的 Agent 决策机制用的。当技能返回一个明确的错误码时Agent 可以依据错误码执行对应的恢复动作参数错误就让模型重新问用户服务不可用就换备用方案权限不足就转人工。把这种“错误码驱动的恢复逻辑”做出来Agent 的鲁棒性就上了一个台阶。我举一个真实场景Agent 调用“发送邮件”技能返回了 ERR_PERMISSION_DENIED。如果只有一句“发送失败”模型无法判断下一步但如果带上错误码模型可以回复“抱歉当前账号没有发送邮件的权限我可以帮你生成一封待发送的草稿请您确认后手动发送”。这就是错误码设计的价值。4.4 技能数量膨胀后的性能优化技能超过一定数量后性能问题会浮现。主要体现在两处一是每次对话都要向模型发送全部技能描述token 消耗高、响应变慢二是模型在大量技能里做选择决策质量下降。我常用的优化手段是“技能检索 粗排精排”。具体来说不再把所有技能塞进上下文而是先根据用户问题做一个召回Retrieval选出候选技能再把候选技能的完整描述交给模型。召回方式可以用关键词、向量检索或一个小的分类模型。我当时在项目里试过的方案是把技能描述向量化后存入向量库用户问题到来时做 TopK 检索把 TopK 技能的描述灌给模型。效果上技能数量从 60 个压缩到每个请求只带 5 个候选费用降了约 70%决策准确率反而更高了。还有一个被忽略的优化点技能描述的“长短分层”。给技能的描述写一个短版本一句话和一个长版本完整接口契约。召回阶段只看短版本精排阶段再把长版本提供给模型。这样既保证了上下文精简又确保了决策时的信息充分。我用了这套方案后原先困扰我的“上下文超限”问题基本没有再出现过。4.5 安全与权限技能不是谁都能调最后来讲安全。Agent 技能通常涉及真实的业务操作如果不做权限控制相当于一个不设防的管理员后台。现实中我见过一个案例Agent 的技能列表里有“删除用户”技能且没有任何权限校验测试同事随便说了一句“把张三删了”结果真的删掉了。这种事一旦发生在生产环境就是重大事故。我给技能体系加了三层权限控制技能级权限某些技能只有特定角色如管理员的会话才可调用。参数级权限同一技能对不同角色可传参数范围不一样比如普通用户只能查自己的订单管理员可以查全部订单。操作级审核有副作用的操作类技能删除、修改、转账执行前必须经过二次确认或人工审批流程。实现上我通常会在技能的 validate 环节注入用户上下文让技能自己能判断当前请求是否有权限。这个看似简单的设计能在很大程度上防止 Agent 被恶意 Prompt 诱导执行危险操作。记住一点Agent 技能本质上是对外暴露的执行接口权限边界永远要在代码层保证不能只依赖模型“按规矩办事”。5. 技能体系的进阶扩展方向5.1 用 LLM 辅助生成技能从人工到半自动技能体系跑通后工作量最大的环节其实是“编写和维护技能描述”。后来我尝试用 LLM 来辅助生成技能文件尤其是生成描述和参数 Schema 这部分效果不错。方法是先给大模型提供一个“技能需求模板”让它根据函数实现或 API 文档生成标准化的技能描述。比如说我有一个现成的 REST API文档已经写好。我把 API 文档喂给模型再加上我之前定义的描述模板模型能输出一份符合规范的技术描述草稿。我再人工审一遍补上边界场景和反例就能直接进入测试流程。这个方法能节省不少时间尤其适合批量为存量接口生成技能。但是有一点要特别注意LLM 生成的技能描述千万不要直接上线必须经过人工审查。因为它可能计算出不存在的参数、忽略边界条件还可能沿用文档里的含糊措辞。我的流程是“LLM 生成草稿 - 工程师补充边界 - 回归测试验证”三步缺一不可。5.2 技能版本管理与灰度发布技能不是一次性写死的业务规则一变技能逻辑和描述都要跟着改。但技能改起来有个特别容易出问题的地方描述和实现必须同步更新否则模型看的是新描述实际跑的还是旧代码。我在项目里遇到过描述说支持“批量查询”代码却只处理单个 ID用户请求批量查询时 Agent 传了列表参数代码直接报错。为此我把技能引入了版本概念。每个技能在注册表里除了名字还带一个版本号。技能描述、代码、参数 Schema 一起作为版本内容打包。发布新版本时先在灰度会话里使用新版本技能观察选择准确率和执行成功率确认没问题再全量切流。如果新版本有问题可以一键回滚到旧版本。这套机制投入不高但线上稳定性提升非常显著。另外一个细节技能版本管理不是只在“发布时”有价值平时的系统诊断里也很有用。每次调用日志我都会记录技能名和版本号出问题时能快速定位是哪个版本的技能引入了回归。没有版本信息排查起来只能盲猜。5.3 技能的可观测性建设谈到诊断就不得不提技能的可观测性。这是一个常被忽略、却又极其重要的话题。每一个技能调用都应该有完整的链路追踪至少记录以下字段技能名称、版本号、入参摘要、出参摘要、执行耗时、错误码、用户 ID、关联的对话 ID。我之前踩过一个大坑Agent 在半夜连续报错但因为日志里只有一句“技能执行失败”根本没有上下文。后来花了整整一天才把日志链路补全查出来是上游接口的限流策略改了导致夜间批量任务全部超时。有了这次的教训我建议把技能调用日志当作一等公民来对待。一个设计良好的技能体系执行一次调用必须留下清晰的“脚印”这样出了问题才能快速定位。对于调用量和并发要求高的场景我还会给技能执行增加耗时分布统计比如 P50、P95 耗时监控。当技能 P95 耗时明显上涨时意味着上游服务可能正在劣化可以提前预警而不是等到用户投诉了才去排查。最后的小建议我最后想结合个人经验说一点Agent 技能体系的建设有点像当年 RESTful API 规范的普及过程。早期大家写接口很随意后来有了统一规范的接口设计前后端协作的效率才真正上来。技能层也一样如果你从一开始就坚持“接口契约 描述规范 权限边界 全链路可观测”这套标准后续不管是扩展技能还是接入新模型都会从容很多。我这套方法在实际项目里经历过从 10 个技能到 60 个技能的规模增长也扛过了多次线上灰度发布。我不敢说它是最优解但至少帮你把该踩的坑大部分都提前踩掉了。如果你正在设计自己的 agent-skills 体系希望能给你一点有价值的参考。