1. 从“agent-skills”这个命名说起：它到底在解决什么问题
第一次看到“agent-skills”这个词，很多人会下意识把它当成某个具体框架或者库的名字。但如果你真的去翻一圈，会发现它更像是一个概念容器——用来描述“智能体（Agent）具备哪些可被调用的能力”这件事本身。换句话说，它不是一个能直接pip install的包，而是一套关于“怎么把大模型从聊天框里拽出来、让它真正干活”的方法论和工程实践集合。
我在过去一年里陆续接触过十几个不同形态的智能体项目，从最简单的“查天气+发邮件”脚本，到需要多轮工具调用、状态管理的复杂工作流，踩过的坑基本能写满一个笔记本。而“agent-skills”这个标题之所以值得单独拿出来聊，是因为它精准地戳中了当前智能体落地时最核心的矛盾：模型本身很聪明，但它不知道怎么用你的工具。
举个最直观的例子。你问一个通用大模型“帮我看看服务器上那个日志文件里有没有报错”，它会很礼貌地告诉你它无法访问你的服务器。但如果你给它配上一个“读取文件”的 skill，再配上“执行 shell 命令”的 skill，它就能自己组合出一条路径：先ls找到日志目录，再tail看最后几行，最后把报错信息摘出来给你。这个从“不能”到“能”的跨越，靠的不是换一个更强的模型，而是给模型装上了可调用的技能。
所以这篇内容适合谁看？如果你是刚接触智能体开发、被各种“Agent框架”搞得眼花缭乱的新手，我会帮你把“skill”这个概念从抽象拉回到具体；如果你已经在写工具调用逻辑，但总觉得自己的智能体“不够聪明”或者“老是调错工具”，那下面关于技能描述、参数设计和错误处理的细节，应该能帮你省下不少调试时间。整篇内容不绑定任何特定平台，讲的是通用思路，你用什么语言、什么框架都能套进去。
2. 拆解一个skill的完整生命周期：从注册到被调用
2.1 技能注册：模型怎么知道“你会什么”
很多人以为给智能体加技能就是写个函数然后告诉模型“你可以用这个”。但实际跑起来会发现，模型经常“看不见”你的函数，或者看见了也不用。问题出在注册环节的信息密度上。
一个能被模型稳定识别的 skill，至少需要包含四个要素：名称、功能描述、参数 schema、返回值说明。名称要短且语义明确，比如read_file就比file_operation好，因为模型在生成调用时是逐 token 预测的，越具体的名字越容易命中。功能描述不能只写“读取文件”，要写清楚“读取指定路径的文本文件内容，支持 UTF-8 编码，返回字符串”。参数 schema 最好用 JSON Schema 的格式写死，包括类型、是否必填、默认值。返回值说明则决定了模型拿到结果后能不能正确解读。
我见过一个典型的反面案例：某开发者写了一个query_db的 skill，描述只写了“查询数据库”，参数只给了一个sql字符串。结果模型每次调用都传SELECT * FROM users这种全表查询，既慢又容易超时。后来他把描述改成“根据用户 ID 查询用户基本信息，返回姓名、邮箱、注册时间三个字段”，参数改成user_id: integer，模型立刻就学会了精准调用。描述里的每一个字都在告诉模型“什么时候该用你”，这一点怎么强调都不为过。
2.2 调用触发：模型在什么情况下会“想起”这个技能
技能注册好了，不代表模型就会用。触发时机的判断，取决于模型对当前对话上下文和技能描述的匹配程度。这里有个很微妙的平衡：描述写得太窄，模型遇到稍微变形的需求就不敢调用；写得太宽，模型又会滥用。
我的经验是，在描述里加入典型的用户问法示例。比如一个“发送邮件”的 skill，描述里可以写“当用户说‘发邮件给某人’、‘通知一下某人’、‘把这份内容邮件发给某人’时使用”。这些示例不需要多，两三个就够，但能显著提升触发准确率。另外，如果多个 skill 的功能有重叠，一定要在描述里写清楚边界。比如同时有read_file和read_csv，就要在read_csv的描述里强调“仅用于读取 CSV 格式的结构化数据，返回表格”，避免模型在读取普通文本时误调。
还有一个容易被忽略的点：技能的数量不是越多越好。当可用技能超过 15 到 20 个时，模型的选择准确率会明显下降。这时候需要做分层，或者用路由机制先判断“这次请求属于哪个大类”，再在那个大类里选具体技能。我一般会把技能控制在 10 个以内，超过就拆成多个子智能体，每个子智能体只负责一个领域。
2.3 参数填充：模型怎么把自然语言变成结构化输入
这是整个链路里最容易出 bug 的地方。用户说“帮我查一下张三的订单”，模型需要把它变成{"user_name": "张三"}。听起来简单，但实际会遇到各种边界情况：用户说“查一下老张的”，模型可能填{"user_name": "老张"}，但数据库里存的是“张三”；用户说“查一下张三最近的订单”，模型可能只填了user_name，漏掉了limit参数。
解决思路有两个方向。一是在参数 schema 里给默认值，比如limit默认 10，order_by默认create_time desc，这样模型不填也不会出错。二是在描述里明确参数之间的依赖关系，比如“如果用户提到了时间范围，必须同时填写 start_date 和 end_date”。我还会在系统提示词里加一句“调用工具前先确认所有必填参数是否已从用户输入中提取，缺失时先向用户询问”，这样能减少很多“参数不全就硬调”的情况。
另外，参数类型尽量用基础类型。我试过用嵌套对象作为参数，模型填充的准确率直接掉了一半。如果确实需要复杂结构，拆成多个平铺参数，或者让模型分多次调用，每次只传一层。
2.4 结果回传与二次决策：拿到数据之后怎么办
技能执行完，结果回传给模型，模型需要判断“这个结果够不够回答用户的问题”。如果不够，它应该继续调用其他技能；如果够了，就组织语言回复。这里的关键是返回值的格式要稳定且可读。
我习惯把返回值统一成 JSON 字符串，里面包含status、data、error三个字段。status用success或error，data放实际内容，error放错误信息。这样模型看到status: error就知道这次调用失败了，可以选择重试或者换一个技能。如果直接返回一个裸的字符串，模型有时候会分不清这是成功结果还是错误提示。
还有一个细节：返回内容不要太长。如果技能返回了几千行的日志，模型的处理会变慢，而且容易在长文本里迷失重点。我一般会在技能内部做一层截断或摘要，比如只返回最后 50 行，或者用正则提取关键行。如果确实需要全量数据，就返回一个文件路径，让模型决定要不要再调一个read_file去读。
3. 技能描述怎么写才“抗造”：几个实测有效的原则
3.1 用“动词+名词”开头，别用“这是一个……”
描述的第一句话决定了模型对技能的第一印象。我对比过两种写法，效果差距很明显。写法 A：“这是一个用于读取文件的工具。”写法 B：“读取指定路径的文本文件，返回文件内容字符串。”实测下来，写法 B 的调用准确率比写法 A 高出不少。原因在于，模型在匹配时更关注动作和对象的对应关系，而不是“这是一个什么”的元描述。
所以我的建议是，描述的第一句直接用祈使句或者动宾结构。比如“发送邮件给指定收件人”、“查询数据库中的用户记录”、“将文本翻译成目标语言”。这样模型在扫描技能列表时，能快速建立“用户想做的动作”和“技能能做的动作”之间的映射。
3.2 把“什么时候不用”也写进去
大部分人在写描述时只写“这个技能能做什么”，但很少写“这个技能不做什么”。这在技能数量多的时候会出问题。比如你有一个search_web和一个search_local_db，如果search_web的描述只写“搜索信息”，模型可能会在查内部数据时也调它。
我的做法是在描述末尾加一句边界说明：“本技能仅用于搜索公开网络信息，不用于查询内部数据库或本地文件。”这句话不会增加多少 token，但能显著减少误调用。类似的，对于有副作用的技能（比如发邮件、删文件），一定要在描述里强调“此操作不可逆，调用前需确认用户意图”，这样模型在调用前会更谨慎。
3.3 参数描述要“防呆”
参数描述里最容易犯的错是只写类型不写含义。比如date: string，模型不知道格式是2024-01-01还是01/01/2024。我一般会写成date: string, 格式为 YYYY-MM-DD，例如 2024-01-01。对于枚举类型的参数，把所有可选值列出来，比如format: string, 可选值：json, csv, text。
还有一个技巧是在参数描述里写清楚单位。比如timeout: integer, 单位秒，size: integer, 单位字节。这些细节看起来琐碎，但能避免很多“传了 1000 以为是秒结果被当成毫秒”的低级错误。
3.4 给每个技能配一个“最小可用示例”
如果框架支持，在技能定义里加一个example字段，写一个完整的调用示例，包括输入参数和预期返回。这个示例不会直接影响模型的调用逻辑，但会在调试时帮你快速验证技能本身是否正常工作。我通常会把示例写成单元测试的形式，每次改完技能逻辑就跑一遍，确保没有回归。
4. 多技能协作时的状态管理：别让智能体“失忆”
4.1 为什么多轮调用容易乱
单个技能调用相对简单，但当一个任务需要连续调用多个技能时，问题就来了。比如用户说“帮我整理一下上个月的销售数据，生成报表发给我”。这个任务至少涉及三个技能：查询数据库、生成报表文件、发送邮件。模型需要记住“上个月”是哪个月、查询结果放在哪里、报表文件叫什么名字。
如果每一轮都把完整的历史对话塞给模型，token 消耗会很大，而且模型容易被无关信息干扰。如果只给最近几轮，模型又可能忘记早期的关键信息。我的做法是维护一个显式的状态对象，里面只放当前任务相关的变量，比如current_task、intermediate_results、pending_actions。每次调用技能前，把这个状态对象序列化后放在系统提示里，调用完再更新。
4.2 用“任务清单”代替“自由发挥”
对于步骤超过三步的任务，我会在系统提示里给模型一个任务清单模板，让它先规划再执行。比如：
任务：生成销售报表并发送 步骤： 1. 确定时间范围（上个月） 2. 调用 query_sales 获取数据 3. 调用 generate_report 生成文件 4. 调用 send_email 发送 当前进度：第 1 步这样做的好处是，模型每完成一步都会更新进度，即使中间某一步失败，也能从断点继续，而不是从头再来。实测下来，这种“清单式”的引导能把多步任务的成功率提升不少，尤其是当任务涉及条件分支时（比如“如果数据为空就发提醒邮件”）。
4.3 错误恢复：技能调用失败之后怎么接
技能调用失败是常态，网络超时、参数错误、权限不足都会导致失败。关键不是避免失败，而是失败之后智能体能不能自己恢复。我一般会在技能返回值里区分错误类型：retryable（可重试，比如超时）和non_retryable（不可重试，比如参数格式错误）。对于可重试的错误，模型可以自动重试一到两次；对于不可重试的错误，模型应该向用户说明原因并请求修正。
还有一个技巧是给每个技能配一个 fallback 技能。比如query_db失败时，可以尝试query_cache。在系统提示里写清楚“如果 query_db 返回超时错误，尝试调用 query_cache”，模型就能在失败时自动切换。这比让模型自己“想办法”要可靠得多。
5. 实测中遇到的几个典型坑与排查思路
5.1 模型“假装”调用了技能
这是最隐蔽的坑。模型在回复里写了“我已经帮你查到了，结果是……”，但实际上它根本没有发起技能调用，而是自己编了一个结果。这种情况通常发生在技能描述不够明确，或者模型认为“这个问题我知道答案”的时候。
排查方法很简单：在技能调用的日志里看有没有实际的调用记录。如果没有，但模型声称调用了，那就是“幻觉调用”。解决办法是在系统提示里加一句“所有事实性信息必须通过技能调用获取，禁止凭记忆回答”，并且在技能返回值里加一个不可预测的随机 ID，模型如果没拿到这个 ID 就说明没真正调用。
5.2 参数类型不匹配导致的静默失败
模型传了一个字符串"10"，但技能期望的是整数10。有些框架会自动转换，有些不会，结果就是技能内部报错但模型不知道。我的做法是在技能入口处做一层参数校验和类型转换，把字符串数字转成整数，把单元素列表转成标量。同时，在返回值里明确写“参数类型错误：limit 应为整数，收到字符串”，这样模型下次就会注意。
5.3 技能之间的“抢活”
当两个技能功能相近时，模型可能会随机选一个。比如search_web和search_news，如果描述里都写了“搜索信息”，模型就分不清。解决办法是在描述里加优先级标记，比如“当用户明确提到‘新闻’时使用本技能，否则使用 search_web”。或者在系统提示里写一个路由规则：“如果查询涉及时效性内容，优先使用 search_news”。
5.4 长对话中的技能遗忘
对话轮次多了之后，模型可能会忘记某些技能的存在。尤其是当技能列表很长时，靠后的技能被调用的概率明显降低。我的应对策略是动态加载技能：根据当前对话的主题，只把相关的技能放进提示里。比如用户一直在聊数据分析，就只加载查询和报表相关的技能，把邮件、日历等技能暂时移除。这样既减少了 token 消耗，也提高了调用准确率。
6. 从“能用”到“好用”：几个提升体验的细节
6.1 给技能加“确认”机制
对于有副作用的操作，比如发送邮件、删除文件、提交表单，我习惯在技能执行前加一道确认。具体做法是技能返回一个need_confirm: true和一段确认话术，模型把话术展示给用户，用户确认后再真正执行。这虽然多了一轮交互，但能避免很多误操作。尤其是当模型对用户意图理解有偏差时，确认机制是最后一道防线。
6.2 记录技能调用链路
每次技能调用都记一条日志，包括时间、技能名、参数、返回值摘要、耗时。这些日志在排查问题时非常有用。我遇到过一种情况：用户说“结果不对”，但模型坚持说“我查到了”。翻日志才发现，模型调用了正确的技能，但传了一个错误的参数（比如把“上个月”理解成了“上上个月”）。如果没有日志，这种问题很难定位。
6.3 定期回归测试技能描述
技能描述不是写完就一劳永逸的。模型版本更新、技能列表变化、用户问法演变，都会影响调用准确率。我一般每两周跑一次回归测试，用一组固定的用户问法去测每个技能的触发情况，发现准确率下降就调整描述。这个习惯帮我提前发现了好几次“模型升级后某个技能突然不被调用了”的问题。
6.4 控制单次返回的信息量
前面提过返回值不要太长，这里再展开说一下。我一般会把单次返回的内容控制在 2000 字符以内。如果原始数据超过这个量，就在技能内部做摘要或分页。比如查询数据库返回 100 条记录，技能只返回前 10 条和总条数，并告诉模型“还有 90 条，如需更多请调整 limit 参数”。这样模型既能给出初步回答，又不会因为信息过载而卡住。
7. 关于“agent-skills”后续可以怎么扩展
如果你已经把基本的技能调用跑通了，下一步可以考虑几个方向。一是技能的组合封装，把常用的多步操作打包成一个复合技能，比如“生成周报”这个技能内部自动完成查询、汇总、格式化三步，对外只暴露一个入口。这样模型不需要知道内部细节，调用成功率更高。二是技能的市场化，把通用技能（比如发邮件、查天气、翻译）做成可复用的模块，不同项目直接引入，减少重复开发。三是基于反馈的技能优化，记录用户对技能调用结果的满意度，自动调整技能描述和参数默认值。
我在实际项目里体会最深的一点是：技能的质量不取决于代码写得多漂亮，而取决于模型能不能稳定地理解和使用它。一个逻辑简单但描述清晰的技能，往往比一个功能强大但描述模糊的技能更有价值。所以每次写完技能，我都会让模型自己“读”一遍描述，然后问它“你在什么情况下会调用这个技能”，如果它的回答和我的预期一致，这个技能才算过关。这个自检方法虽然土，但确实管用。
