1. 为什么我会动手折腾 agent skills 这件事
1.1 所谓 Agent Skills，到底解决的是哪类问题
先说结论：agent-skills 这个词，最近在 AI 应用圈子里出现的频率越来越高，但你如果去翻那些项目仓库，会发现它并不是一个严格定义的学术概念，更多是大家在实战中沉淀出来的一种“给智能体封装能力”的工程范式。简单讲，它就是把一个智能体需要执行的某个具体任务——比如检索文件、运行 Python 脚本、调用外部 API、处理表格数据——抽成一个独立的、可注册、可调度、可复用的“技能单元”，然后让大模型在对话中动态选择合适技能来完成用户的真实需求。
我为什么要专门写一篇东西聊这个？因为过去半年我一直在做助手类产品的后端，最大的体会就是：直接让大模型裸奔式地回应用户请求，跟把各种能力封装成“技能”再交给模型调度，体验完全是两个量级。裸奔的时候，模型遇到稍微复杂一点的需求就会开始“胡编”——它不是不想做好，而是缺少一个明确的能力边界和调用路径。你问它“帮我把这份 CSV 按月份汇总一下”，它能给你写一段看起来很像样的 Python 代码，但代码跑不跑得通、数据格式对不对，它完全不负责。而当你把“CSV 汇总”封装成一个带参数约束、带执行逻辑、带结果回传的 skill 之后，模型只需要做它最擅长的事情：理解用户的意图、填好参数、触发执行，剩下的脏活累活交给技能去完成。
所以这个东西适合谁看？两类人。一类是正在做 AI 应用、但发现纯 prompt 工程已经顶不住复杂场景的开发者，另一类是想把团队里已经沉淀下来的各种脚本、API、工作流，统一接入到大模型对话体系里的技术负责人。这篇文章不聊那些花哨的 Agent 框架，也不炒概念，就把我实际搭建一套 agent-skills 系统时踩过的坑、验证过的方案、写过的核心代码，拿出来跟你一条条过一遍。
1.2 它跟普通 function calling 有什么区别
很多朋友一听到 agent skills，第一反应是：“这不就是 function calling（函数调用）吗？”确实有关系，但严格说，它是 function calling 的一种升级形态，或者说是站在函数调用之上的一层更完整的工程封装。
function calling 解决的是“让模型从一堆函数里选一个，并生成正确的参数”这件事。它给模型的是一个扁平的函数清单，每个函数有名字、有描述、有参数 schema。模型在每次对话时根据用户输入，决定“我要调用哪个函数、传什么参数”。这套机制本身非常成熟，OpenAI、Anthropic、Google 的模型都有原生支持，我早期也是这么干的。但用着用着你会发现几个痛点。
第一个痛点是函数数量一多，模型的选择准确率会明显下降。你挂 10 个函数的时候还好，挂到 30 个、50 个的时候，模型经常会在两个功能相似的函数之间犹豫，甚至干脆选错。第二个痛点是单个函数太“细”。真实的用户需求往往是“我要做数据分析”，拆开来看至少涉及读文件、清洗数据、聚合统计、生成图表四个步骤，你要是只给模型一个“执行 Python 代码”的函数，它倒是全能干了，但你根本没法控制它在代码里干了什么——安全性和稳定性都是大问题。第三个痛点是没有状态和上下文。function calling 是“无记忆”的，每次调用都像第一次见面，技能中途失败、重试、结果缓存这些事，全得自己另写一套逻辑。
Agent skills 的思路，本质上是在 function calling 之上加了一层“技能层”：每个技能不再是孤立的函数，而是一个自包含的执行单元，它既有模型的调用入口（名字、描述、参数 schema），也有自己的执行逻辑、前置条件、后续处理。整个系统分两层，外层是模型的“技能选择器”，内层是技能的“真正执行器”。模型只负责做路由决策，具体怎么干，由技能内部实现说了算。这样设计的好处非常直接：能力边界清晰了、单个技能可以做得足够复杂、而且多个技能之间可以通过编排组合出更大粒度的能力。我后面会拿完整代码演示这套结构。
2. Agent Skills 的核心设计与落地模型
2.1 技能描述：给模型一张“能看懂”的技能地图
如果你把所有技能都注册好之后，发现模型总是不调用你希望它调的技能，那问题大概率不是出在模型身上，而是出在你的技能描述写得太“程序员化”了。这一点我特别想先拎出来讲，因为它是整个 agent-skills 系统里投入产出比最高、却最容易被忽视的部分。
我在设计技能描述的时候，遵循一个很朴素的准则：假设对面坐的是一个刚入职的实习生，他手边有一堆工具，你需要让他光看工具标签就知道哪个工具对应哪类活儿。描述要回答三个问题：这个技能是干什么的、什么场景下应该用、什么情况下不应该用。举个实际例子。早期我把一个技能描述写成“execute_sql_query(query: string)”，结果模型在用户问“帮我看看上个月销售额是多少”的时候，经常不选它，反而去选一个叫“run_python_script”的技能。后来我把描述改成：“在用户需要查询数据库、分析表格数据、获取统计结果时使用。支持传入标准 SQL 语句。注意：如果用户只是问文本类问题，不要使用本技能。”效果立刻好了很多。不光是加了场景，还加了“什么时候不要用”的负向提示，模型在语义匹配上的困惑度会明显下降。
还有个细节是技能分类。当技能数量超过 15 个之后，建议在描述里带上明确的领域前缀，比如“数据处理 > 文件读取”“数据处理 > 聚合统计”“绘图 > 柱状图”。模型在路由时看到这种分类信息，会更容易锁定正确的技能组，然后在小范围内做精确选择。这跟你自己用搜索引擎时先限定分类目录再找具体页面是一样的逻辑。我实测下来，技能数量 20 个左右时，带分类前缀比不带分类前缀的选择准确率能差出 8 到 12 个百分点，这个提升在工程上是实打实的。
2.2 参数合约：把自由度控制在模型能搞定的范围
技能描述决定了模型选不选得对，参数合约决定了模型用不用得顺。这一块我踩的坑最多，也是我后来反复跟团队强调的“技能设计最核心的环节”。
所谓参数合约，就是每个技能暴露给模型的参数定义。很多人写这块的时候会犯一个毛病：参数定义得特别粗，全用 string 类型，描述写一句“用户的请求内容”。这种设计等于把自由裁量权全部交给了模型，结果就是模型传参随心所欲——同一个技能，这次传一个 JSON 字符串，下次传一个自然语言句子，下下次传一个数组，你的技能执行代码就得不停地做兼容处理，且每次都有可能解析失败。后来我定了一个硬性规则：所有参数必须用结构化 schema 定义，能枚举的字段绝不放任自由输入，能拆成多个参数的就不要塞成一个对象，每个参数必须写明格式要求、取值示例、常见错误。
举个例子。我有一个“生成月度报表”的技能，早期只有一个参数 payload，后来我拆成了 report_type、start_date、end_date、group_by 四个参数，每个参数都有明确的枚举或格式约束。模型需要做的工作变简单了，就是把用户自然语言里的信息映射到这四个字段上，剩下的组合、处理、生成全在技能内部完成。结果非常明显：参数解析失败率从最早的接近 30% 降到了 5% 以下。这里有个关键点你要明白——模型天然是一个“填空题选手”，你给它越清晰的空位，它填得越准；你给它一个空白作文纸，它就只能自由发挥，而自由发挥对稳定性来说往往是灾难。
2.3 状态与权限：技能不该是无限制的“万能遥控器”
技能系统上线跑了一段之后，我开始认真考虑两件容易被人忽略的事：状态管理和权限控制。这俩问题在最开始只有几个技能的时候完全不是问题，但技能一多、用户一多，瞬间就能变成事故现场。
先说状态管理。function calling 时代，函数是无状态的，每次调用一拍两散。但技能不一样，一个技能可能是一个多步骤的执行流程。比如“数据清洗”技能，它可能要经历读取文件、识别格式、处理缺失值、输出清洗报告四个阶段，其中任何一个阶段失败，都需要知道上下文从哪里恢复。我的做法是给技能调用引入一个 session 概念：每次技能执行都会生成一个 execution_id，技能内部的关键中间结果、状态快照都挂在这个 execution_id 下面。这样技能内部可以自愈，外部也能对执行过程做审计。
权限控制就更要命了。技能一旦能操作文件、能访问数据库、能调外部 API，它就是一个“有手有脚”的执行体，比单纯只会“说”的模型危险得多。我的原则是最小权限原则：每个技能声明自己需要访问的资源范围，调度内核在执行时强制校验。比如读取文件技能，只能访问指定工作目录下的文件；数据库查询技能，只能用一个只读账号连接。你可能觉得这些是老生常谈，但在我接触过的很多 agent 项目里，这部分往往是最薄弱的——大家光顾着让模型“能干”，没怎么考虑“哪些不能干”。等真的出现一次误删文件或者越权访问，再回头补就非常被动了。
3. 手写一套技能系统：从注册到调用的完整实现
3.1 技能注册与元数据组织
概念聊完了，上点干货。下面这套实现我尽量精简，保留核心骨架，但设计思路和线上版本一致。技术栈用的是 Python，模型接口我按 OpenAI 风格的 SDK 来写，你换成任意兼容的模型服务都可以。
技能系统的底层就是一张注册表。每个技能被一个装饰器标记，注册到全局字典里，字典的键是技能名，值是技能对象。技能对象包含五部分：name（技能名）、description（给模型看的技能描述，包含场景和反例）、parameters（参数 JSON Schema）、handler（真正的执行函数）、permissions（所需权限声明）。我直接贴代码。
# skills/registry.py from typing import Callable, Any, Dict, Optional import inspect SKILL_REGISTRY: Dict[str, "Skill"] = {} class Skill: def __init__( self, name: str, description: str, parameters: dict, handler: Callable[..., Any], permissions: Optional[list[str]] = None, ): self.name = name self.description = description self.parameters = parameters self.handler = handler self.permissions = permissions or [] def execute(self, arguments: dict) -> dict: # 参数校验、权限校验都放在这一层 try: result = self.handler(**arguments) return {"status": "success", "result": result} except Exception as e: return {"status": "error", "error": str(e)} def skill(name: str, description: str, parameters: dict, permissions: Optional[list[str]] = None): def decorator(func: Callable[..., Any]): s = Skill( name=name, description=description, parameters=parameters, handler=func, permissions=permissions, ) SKILL_REGISTRY[name] = s return func return decorator这里有一个我特别想强调的设计：执行函数 handler 和模型路由是解耦的。handler 就是一个普通 Python 函数，它不关心什么大模型、什么 token、什么 prompt，它只负责“收到结构化参数 -> 干活 -> 返回结果”。这个解耦带来的好处是，你的技能函数可以单独写、单独测、单独特调，完全不依赖整个 agent 系统，复用性也非常好。我团队里现在很多技能是数据分析同事写的，他们根本不关心模型怎么调用它。
3.2 调度内核：让模型“点单”而非“炒菜”
有了注册表，接下来就是核心的调度内核。所谓的调度内核，干的事情说起来非常简单：把系统提示词和可用技能列表交给模型，让模型决定调用哪个技能、传什么参数，然后执行技能、把结果返回给模型，模型再结合结果生成最终回答。这整条循环就是 agent 最经典的 ReAct 模式，但实现细节上有不少讲究。
# skills/agent.py from openai import OpenAI from .registry import SKILL_REGISTRY client = OpenAI() def build_system_prompt() -> str: lines = [ "你是一个能够调度技能完成任务的助手。", "当用户请求涉及具体操作时，你必须选择最合适的技能并传入正确的参数。", "技能执行结果会以工具消息的形式返回给你，请基于结果继续回答。", "如果你认为没有技能可处理该请求，请直接拒绝或告知用户调整需求。", ] return "\n".join(lines) def build_tools_payload(): tools = [] for name, skill in SKILL_REGISTRY.items(): tools.append( { "type": "function", "function": { "name": skill.name, "description": skill.description, "parameters": skill.parameters, }, } ) return tools def run_agent(user_message: str, max_rounds: int = 5): messages = [{"role": "system", "content": build_system_prompt()}] messages.append({"role": "user", "content": user_message}) for _ in range(max_rounds): resp = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=build_tools_payload(), tool_choice="auto", ) msg = resp.choices[0].message messages.append(msg) # 模型没有要求调用技能，说明对话可以结束 if not msg.tool_calls: return msg.content for tc in msg.tool_calls: skill = SKILL_REGISTRY.get(tc.function.name) if skill is None: messages.append({ "role": "tool", "tool_call_id": tc.id, "content": "技能不存在，请向用户说明。", }) continue import json args = json.loads(tc.function.arguments) exec_result = skill.execute(args) messages.append({ "role": "tool", "tool_call_id": tc.id, "content": json.dumps(exec_result, ensure_ascii=False), }) return "执行轮数超限，请稍后再试。"这套内核跑起来之后，整个交互就很像“点单制”：用户说需求，模型当服务员，技能当后厨。模型根据菜单（技能列表）判断用户要什么，然后把订单（参数）传给后厨，后厨做好菜端回去，服务员再把菜摆盘（组织语言）送到用户面前。模型从头到尾不需要自己动手“炒菜”，它只需要做决策和表达。这个模式的可控性，比让模型直接写代码执行高出一个层级。
3.3 技能执行与结果回传的细节处理
主循环跑通了，但真正决定上线体验的，往往是那些骨架之外的琐碎细节。我挑三个最影响稳定性的点详细说说。
第一个是结果截断。技能执行结果可能非常长——你让模型跑了一个数据分析技能，返回一个几千行的 CSV 或大段 JSON，如果你不做任何处理直接塞进 messages 里，下一轮请求的 token 量会飞速膨胀，很快就会超上下文窗口。我的做法是在 result 回传前做一个智能截断：默认只保留前 2000 个字符，同时把完整的执行报告单独存储，只在消息里附一个 report_id 方便后续追溯。为了让模型在信息不足时知道还有更多数据可看，我还加了一句话“完整结果过长已截断，如需查看特定部分请明确询问”。这样模型就会知道去向用户追问、或者去调用另一个查询技能，而不是对着截断的数据瞎猜。
第二个是异常信息要“翻译”成人话。技能执行抛异常的时候，如果你直接把 Python 的 traceback 原样丢给模型，模型倒是能看懂一部分，但生成给用户的回答通常很生硬，充满了“KeyError: 'month'”这种术语。我在 Skill.execute 里做了异常兜底，统一返回结构化错误，同时在描述里要求模型“必须用用户能理解的语言解释错误，说明可能的原因和下一步建议”。这样用户体验会好很多。经验之谈：agent 应用里，异常处理不只是给程序员看的，更是给模型看的“上下文材料”。
第三个是并发和超时。线上环境里，同一个技能可能被多个用户同时触发，如果技能里有共享资源（比如一个全局变量或文件句柄），并发问题就会找上门。我查过几次线上 bug，最后发现都是技能函数里用了模块级变量导致的。现在的规范是所有技能函数内部只使用局部变量，共享数据一律通过参数传入。超时方面，每个技能执行我都建议用 asyncio.wait_for 包一层，给一个合理的上限——数据分析类技能我给 60 秒，文件读取类技能 10 秒，比这更长的操作改成任务队列异步执行。这一步看着不起眼，但能救你很多次——模型是不等人的，技能卡死会直接把整个 agent 卡成呆滞状态。
4. 实操中踩过的坑与排查指南
4.1 模型老是选错技能怎么办
这个问题我收到的抱怨最多。技能一多，模型就开始“乱点鸳鸯谱”，明明有专门的技能不用，非要选一个效果相近的替代品。排查思路我一般分三步走。
第一步，看描述里有没有负向约束。我之前说过，描述里强调“什么情况下不要用”，是提升区分度的利器。比如“查询订单”和“查询用户”两个技能，如果都只写“查询数据”，模型区分不开很正常；但如果分别写明“订单查询技能：仅用于查询订单状态、金额、物流等信息。用户问题涉及个人资料如姓名、手机号时，请使用查询用户信息技能，不要使用本技能”，准确率立刻能上来。
第二步，看技能名称是否足够语义化。早期为了图省事，我用过 sort_data、cli_run 这种内部代号做技能名，结果模型完全抓瞎。后来统一改成“数据排序处理”“命令执行工具”这种可以直接从名字推断用途的风格，选择准确率又涨了一截。不要小看名字的作用，模型在路由时对名字和描述是同样看重的。
第三步，检查参数 schema 是否有歧义。有时候模型选错技能，不是因为技能本身分不清，而是因为它想传的参数在目标技能里找不到对应的字段，于是退而求其次选了一个参数“宽松”的技能。这种情况就回到参数合约的问题上了——把技能能处理的操作边界在描述里说清楚，参数字段宁可多定义几个必备项，也不要留一个万能的 options 字符串。
如果这三步都走完还是频繁选错，我才会考虑上更重的方案，比如给技能加一个“预路由”分类器，先用一个小模型或者规则引擎把用户请求分到大类，再在大类内部让大模型精确选择。但这是少数场景才需要的优化，大多数项目把前三点做好就够用了。
4.2 参数解析失败和幻觉参数
模型调用技能时传参不规范的频率，比你想象的高得多。我最早期上线第一天就遇到一个经典案例：用户说“查一下最近30天的数据”，技能参数定义是 start_date 和 end_date，模型老老实实传了两个日期字符串，但格式一个是“2024-05-01”，另一个是“5月30日”。这种“幻觉参数”不一定是模型凭空捏造，更多时候是它理解得不够精确就把语义直接塞了进去。
针对这个问题，我在技能参数处理上加了三道保险。第一道是强类型校验，每个参数进来先按 JSON Schema 校验类型，类型不对直接拒绝并返回明确错误提示。第二道是格式归一化，比如日期、百分比、金额这些常见格式，在技能内部做一层解析器，能兼容多种常见的自然语言写法，归一化为统一格式再往下传。第三道是缺省值兜底，有些参数是必填的、有些是可选的，我会在参数 schema 里把必填项标得非常清楚，并且用 required 字段约束模型；模型没传必填参数时，返回错误信息并模糊提醒“缺少必要参数：start_date”，让模型自己意识到问题后补充。
这里我特别想提醒一个容易踩的误区：不要为了让模型“少犯错”就无限放宽参数校验。有一段时间我把所有参数都设计成宽松可选，容错率确实高了，但带来的副作用是模型越发不认真读 schema，传参越来越随意，整个系统的可预测性大打折扣。后来我收回了一部分宽容度，对必填字段坚决要求格式合规，模型反而变得更“守规矩”了。这就像一个团队里如果永远没有硬性标准，大家做事就会越来越潦草。
4.3 上下文过长、执行超时与并发冲突
这三个问题几乎是 agent 应用上线后一定会遇到的“三座大山”。我分别讲一下我的应对办法，不一定最优雅，但都是在真实环境验证过的。
上下文过长是最快出现的。用户跟 agent 聊上十轮八轮，每轮都触发一两个技能，messages 里累积的工具执行结果可能比正文还长。我的处理方案是分层压缩：对历史对话做摘要，对工具结果做截断，对技能输出做统计摘要而非全文回传。核心原则是“模型需要的信息保留，用不到的彻底丢弃”。比如数据分析技能，我回传给模型的不是完整表格，而是“总行数、列名、前5行预览、缺失值统计”这一组摘要指标，模型基于这些足以回答大多数问题。等到用户真想看数据细节，再走下一个技能去拉。
执行超时的问题，本质上要区分“操作本身慢”和“系统卡死”。前者用异步化解决——技能一旦超过一定时间，立刻返回“任务已提交，正在后台处理”，轮询或者回调再更新结果；后者要靠超时和重试机制兜底，避免无限等下去。我见过不少项目没做超时控制，结果模型等技能等得都快把用户晾在那了，这种体验绝对不能接受。
并发冲突最经典的场景是多个用户同时触发“写文件”或“改配置”类技能，导致数据互相覆盖。我的方案是给这类技能加锁，同一时间内同一资源只允许一个技能执行；再往根上治理，就是技能设计时尽量避免共享可写状态，必要写入时用带唯一后缀的临时文件，处理完再原子替换。这套思路跟我维护普通后端服务时的一致，本质上没有区别，只是很多人写 agent 时下意识觉得“AI 应该有特权”，忘了它背后的执行代码跟普通程序没两样。
5. 快速验证技能效果的实测方法
5.1 用评测集代替“拍脑袋调优”
技能系统搭好之后，最忌“感觉挺好”就直接上线。我吃过亏。有一版技能系统改了几个描述，自己试了几轮感觉顺畅多了，结果上线后用户反馈“模型还是不怎么调用新技能”。后来我才发现，我自己测试时用的那几条 query 太典型、太容易匹配，根本覆盖不了真实用户千奇百怪的说法。
后来我养成了一个习惯：给技能系统维护一个评测集。每个技能下面挂至少 10 条真实用户可能说的话，包含标准表述、口语化表述、模糊表述、负向样本（不应该调用本技能的输入）四类。每次调整完技能描述或参数 schema，就把评测集完整跑一遍，统计技能选择准确率、参数解析成功率、任务完成率三个指标。这个做法看着笨，但它能让你在改了一个描述后，清楚地知道这次改动是变好了还是变差了，而不是靠感觉猜。我印象很深的一回：我把一个技能描述里增加了一句“如果用户只是询问数据是否存在，请直接回答，不要调用本技能”，结果这个技能的误触率从 18% 降到了 6%，同时其他技能的调用率几乎没受影响。这种优化没有评测集根本发现不了。
5.2 日志是最好的老师
就算你评测集做得再齐全，也不可能覆盖所有线上场景。所以日志系统必须从第一天就做好。我这里说的日志不是普通的 print 输出，而是结构化的技能调用日志，至少要记录：用户原始输入、模型选择了哪个技能、模型生成的参数原文、参数校验结果、技能执行耗时、执行返回结果摘要、最终用户看到什么。这些日志放在一起，你能非常清晰地观察到模型的决策链条。
排查实际问题的时候，我通常按这条路径走：先看用户输入和技能选择是否匹配，不匹配就回到技能描述上去找原因；匹配但参数解析失败，就去查参数 schema 的约束是不是不够明确；参数没问题但执行出错，再去查技能内部逻辑和外部依赖。这套排查路径基本能解决九成以上的线上问题。有一次用户反馈“查不到上周的报表”，日志一看，模型选择了“报表查询”技能，却把 start_date 传成了当前日期而不是上周日期——问题不在技能，在于用户输入里的“上周”模型没有换算成具体日期。这个问题的解决方案是在技能描述里特别标注：“涉及相对时间如今天、上周、本月时，请先换算为具体日期再传入参数。”
6. 最后分享一点我的选型与演进建议
很多人看完上面的实现，会问我要不要直接用现成的 agent 框架。我的观点是：如果你只是做 demo、验证想法，直接用 LangChain、LlamaIndex 或者各家平台自带的能力封装，省心省力；但如果你是做真正要上线的产品，我建议至少把技能注册、技能执行、技能日志这三层自己写一遍。不是因为框架不好，而是因为技能系统跟你的业务逻辑耦合太紧，通用框架往往会在你最需要定制的地方变成瓶颈，到那时候再改造的成本，远高于一开始就自己搭一个轻量的。
另外一个演进方向是把技能做成“可组合”的。我现在的系统里，技能分两层：原子技能是最基础的操作，比如读文件、跑查询、发请求；复合技能则是把多个原子技能按固定流程编排起来，形成更上层的业务能力。比如“生成竞品分析周报”这个复合技能，内部就是“抓取数据、清洗数据、聚合统计、生成文案、推送文档”五个原子技能的有序组合。模型只需要学会调用这一个复合技能，就能完成一串复杂的任务，这对用户来说体验是质的飞跃。而且复合技能可以由我们的业务团队自己配置，不需要每次改代码，整个系统的扩展性一下子打开了。
最后再说一句关于“技能数量”的经验。技能不是越多越好，每加一个技能，模型选择时面临的干扰就多一分。我个人的经验是：在模型能力没有特别强的情况下，一次暴露给模型做路由选择的技能数量控制在 20 个以内比较稳妥。如果确实技能太多，就上分组路由——先按领域分组，用分类模型或规则确定领域，再在对应组内做精确选择。与其让一个模型在 50 个技能里大海捞针，不如让它在 5 组 10 个技能里精准定位，效果和成本都更好控制。这套东西并不酷炫，但每一层都是我在真实项目里被磨出来的。希望这篇分享能让你在搭自己的 agent-skills 系统时，少走几步我已经走过的弯路。
