如果你玩过大模型 Agent大概率遇到过这个场景模型本身很聪明但让它去执行一个具体任务——比如查资料、整理文件、跑脚本——就各种翻车。不是它不会而是它不知道该怎么“动手”。agent-skills 这个标题我第一次看到时心里就两个字对味。它把问题往根源上带了——我们缺的不是更强的模型而是一套能把模型能力转化成稳定执行力的技能体系。这篇文章我想从工程落地的角度把 agent-skills 拆开聊透。它能做什么、解决什么问题、适合谁来看我用大白话讲清楚所谓 agent-skills本质上是给大模型配一套“工作技能库”让模型不再每次从头摸索而是像老员工一样知道什么场景调用什么方法、按什么步骤干活、碰到异常怎么处理。适合正在做 Agent 应用、被“模型很聪明但任务老跑偏”折磨的开发者也适合刚接触 Agent 只想搞明白“技能到底怎么设计”的入门者。1. 先搞清楚agent-skills 解决的是 Agent 的什么问题1.1 从“会聊天”到“会干活”Agent 缺的是技能栈很多团队做 Agent 踩的第一个大坑是把 Agent 当聊天机器人用。用户问一句模型回一段看起来挺智能但落到业务里根本不够——真正要的是一个能“把事办完”的系统。聊天和干活是两码事。聊天只需要生成文本干活需要模型具备两样东西一个是动作能力也就是能调用工具、读写文件、请求接口另一个是方法能力也就是知道先做什么后做什么遇到什么情况该切换策略。这两样合起来就是“技能”。我见过不少人以为只要给模型接上工具就能干活结果模型拿到一堆函数今天这个好用明天那个就乱调。问题就出在工具是散的而技能是组织起来的。技能把工具的调用方法、前置条件、输入输出约束、异常处理都封装在一起模型不需要靠“悟性”去理解工具只需要按技能说明来执行。所以 agent-skills 解决的最核心问题就是把“模型会说话”变成“模型能稳定干活”把不可控的临场发挥变成可复用的流程资产。1.2 技能库、插件、工具三个概念别搞混聊 agent-skills 之前有三个词必须先理清不然讨论起来全是鸡同鸭讲工具、插件和技能。工具Tool是最小动作单元通常一个函数对应一件事比如“发送 HTTP 请求”“读取某个文件”“执行一段 Python 代码”。插件Plugin是工具的打包形态解决的是“怎么接入”的问题比如一个浏览器插件把搜索、抓取、截图这些工具打包好。技能Skill则更进一层它面向的是一个完整目标里面可能包含多个工具调用、判断逻辑和兜底策略。举个例子搜索是一个工具把搜索集成好并提供额外接口是插件“根据用户问题先拆关键词再查多个来源最后整理成要点回答”就是技能。技能本身可以调用工具也可以调用其他技能它描述的是做事的方法而不是单一的接口。概念粒度核心关注点典型实例工具最细某个具体动作能干什么调用搜索 API、写文件插件中等工具怎么接入系统浏览器插件、数据库连接插件技能较粗一个目标怎么完成市场调研、竞品分析、资料整理把这三层拆清楚之后你再看任何 Agent 框架都会通透很多——很多所谓“Agent 效果不稳定”的问题其实不是模型不行而是技能层没做好。1.3 为什么说技能是 Agent 项目里的一等公民我早期做 Agent 项目的时候把大部分精力花在调 prompt 上想着“提示词写得够细模型自然就听话”。后来发现这是最不划算的路。同一个任务换一个模型要重调同一个模型换一种说法效果又变了prompt 修来修去始终在打补丁。后来我把思路改成prompt 只负责讲清楚目标和边界真正干活靠技能。技能一旦定义好就是可积累的资产。今天让模型学会“联网检索”明天所有需要检索的任务都能复用今天调通了“数据清洗”后天接新数据源直接拿来用。技能就像公司的知识库不随人员流动流失也不随模型升级失效。这也是 agent-skills 这个名字给我的感觉——它把 Agent 开发的重心从“写提示词”拉回到“建设技能体系”让每一次调试和优化都有沉淀。2. 技能体系的设计思路与核心拆解2.1 技能的最小单元输入输出之外还要定义什么一个技能要能被模型稳定使用光有函数签名远远不够。我总结下来一个完整技能至少要包含几个部分名称、描述、输入参数、输出格式、前置条件、副作用、失败兜底。名称和描述决定模型什么时候会想起来用这个技能。名称要短一眼能看懂描述要写清楚“什么时候用、用了能解决什么”。很多人不重视描述随手写一句“搜索信息”就完事结果模型在真正需要搜索的时候压根不触发它反而去编造答案。输入参数要遵循严格的 JSON Schema能枚举就枚举能设默认值就设默认值。模型的参数幻觉是 Agent 工程最大的痛点之一后面我会专门讲怎么排查。前置条件这块非常容易被忽略比如“写文件技能”需要先确认目录存在“发邮件技能”需要收件人邮箱格式合法。这些前置逻辑写进技能里比模型临场判断可靠得多。副作用描述的是这个技能会对外部环境产生什么影响。模型并不天然理解“删除文件”“提交订单”是高风险动作你要在技能设计时明确标注“确认后执行”之类的约束。很多安全事故追溯到最后都是技能副作用没有写清楚。2.2 技能编排串行、并行、条件分支怎么落地单个技能能解决简单任务但真实业务往往是复合的先搜索再筛选然后生成报告最后发送。这就涉及技能的编排问题。技能编排目前没有标准答案但大体分两种路线。一种是让模型自己编排把技能列表全塞给模型让它根据任务目标决定调用顺序。优点是灵活缺点是不可控复杂任务经常出现“绕远路”甚至“循环调用”。另一种是人为预定义流程用类似 DAG 的方式把技能连起来。这种方式稳定但灵活性差换个场景流程就得改。我的做法是折中把主干流程用代码固定分支节点放开让模型选择。举个例子一个“竞品分析”技能内部定义好了“数据收集—数据清洗—分析生成—报告输出”的骨架但数据收集环节具体调哪个源、生成报告用什么模板由模型根据输入动态决定。这样既保住了稳定性又留了弹性。实话说我不推荐把所有业务逻辑都压在模型编排上。模型做顺序决策还行但让它同时维护多个状态、处理复杂分支效果和稳定性都会明显下降。能用代码确定的流程就不要让模型去“悟”。2.3 上下文工程技能描述的措辞决定模型用不用一个技能写得再漂亮如果模型压根不理解它等于白写。这里我要专门讲讲技能描述怎么写。技能描述不是写文档是写给模型看的“使用说明”。重点不是它是什么而是它什么时候触发、怎么用。我常用的写法是四段式触发场景、执行动作、输出格式、失败处理。比如一个搜索技能我会写“当用户需要获取最新信息、查找特定数据、或回答需要外部知识的问题时使用此技能。先拆解查询关键词调用搜索引擎获取结果后提取核心信息按 JSON 格式返回包含来源链接。如果搜索失败尝试更换关键词重试一次。”这里面的关键是触发场景要写得足够具体不能含糊。如果你的技能描述写“用于搜索”模型会在很多不需要搜索的时候也去调它因为描述太宽泛了如果你写“仅当……时使用”模型反而能准确判断边界。另一个容易被忽略的点是上下文长度。技能列表不能无限膨胀塞太多技能进上下文不仅浪费 token还会稀释模型的注意力。建议给技能做摘要索引先让模型看技能名称和一句话摘要真正需要时再加载完整描述。这个机制就像人的“工作记忆”和“长期记忆”的分工agent-skills 如果要做大规模这一步躲不开。3. 实操过程从零到一撸一个可用技能3.1 先定义技能数据模型干活之前先定数据模型。我用 Pydantic 或 TypeScript interface 都行关键是结构要稳。下面我用 Python 示例展示一个技能的基本形态。from dataclasses import dataclass, field from typing import Any dataclass class Skill: name: str # 技能名短且唯一 description: str # 给模型看的触发说明 parameters: dict # JSON Schema 参数定义 required: list # 必填参数列表 execute: callable # 实际执行函数 timeout: int 30 # 超时时间秒 side_effects: list field(default_factorylist) # 副作用声明每个字段都有存在的理由。name 是模型用来识别的“函数名”description 是模型判断触发条件的依据parameters 约束输入execute 负责真正执行timeout 防止技能卡死拖垮整个 Agentside_effects 则用来标记危险动作。3.2 写一个真正能跑的超简单技能接下来我们写一个可用的小技能联网搜索并整理要点。这个技能很适合做第一个练手项目因为链路短、结果直观能快速验证整套技能机制是否通畅。import json import requests def search_and_summarize(query: str, max_results: int 5) - str: # 这里简化处理实际接入你的搜索服务 url https://api.example.com/search params {q: query, n: max_results} resp requests.get(url, paramsparams, timeout10) resp.raise_for_status() results resp.json() # 提取核心信息 summaries [] for item in results[items]: summaries.append({ title: item[title], source: item[url], snippet: item.get(snippet, )[:200] }) return json.dumps(summaries, ensure_asciiFalse, indent2) skill Skill( namesearch_and_summarize, description( 当用户需要获取最新信息、查询特定数据、或回答依赖外部实时知识的问题时 使用此技能。先拆解用户问题中的核心关键词再执行搜索最后提取关键信息 返回摘要列表。 ), parameters{ type: object, properties: { query: {type: string, description: 搜索关键词}, max_results: {type: integer, default: 5, minimum: 1, maximum: 10} } }, required[query], executesearch_and_summarize, timeout15, side_effects[外部网络请求] )这个例子里有几个细节值得注意。第一个是 timeout 设成了 15 秒搜索接口不可控给它 30 秒风险太大15 秒比较合理。第二个是 max_results 设置了上下限防止模型传一个 999 把服务打爆。第三个是 side_effects 标记了“外部网络请求”后续如果做权限审计这个字段能派上大用场。3.3 技能注册怎么让模型“看到”技能技能定义好了得让模型知道它的存在。调用链路一般分四步加载技能列表、拼进系统提示词、模型决定是否调用、执行技能返回结果。# 1. 注册所有技能到一个管理器 skill_registry { search_and_summarize: skill, } # 2. 构建给模型的技能描述 def build_function_schemas(registry): schemas [] for s in registry.values(): schemas.append({ type: function, function: { name: s.name, description: s.description, parameters: s.parameters, required: s.required } }) return schemas # 3. 模型返回要调用的技能后解析并执行 def run_skill_call(model_response, registry): for call in model_response.tool_calls: skill_name call.function.name args json.loads(call.function.arguments) if skill_name not in registry: return Error: unknown skill skill registry[skill_name] result skill.execute(**args) # 返回值可以回传给模型做二次生成 return result很多模型 API 都原生支持 function calling你不需要自己写模型侧的逻辑但要注意两点。第一参数解析一定要做防御模型生成的数据经常出现缺字段、类型错误、字符串不合法 JSON 的情况解析失败要兜底。第二执行结果要返回给模型继续推理技能通常只是中间步骤不是最终答案。我的习惯是始终保留一个“执行失败”的返回状态。技能出错了不要直接报异常给用户而是把错误信息作为文本返回给模型让它决定是换个参数重试还是换技能。这个机制简单但能显著提升任务完成率。3.4 实测对比技能描述写法真的影响触发率我分别用三种写法试过同一个搜索技能触发率的差别非常明显。当然这只是我的实测不同模型结果会有差异但方向基本一致。第一种写法是“搜索信息并返回结果”触发率只有四成左右。模型经常在需要外部知识的时候直接编造答案根本没想到调用搜索技能。第二种写法加上了触发条件“当问题涉及最新新闻、实时数据、具体数值或用户明确要求查询时使用此技能”触发率提升到六成。第三种写法把决策权直接交给模型并给了反例“如果问题内容无需外部知识即可回答或者仅涉及常识性知识则不使用此技能”触发率能到八成以上。描述风格触发率问题典型小毛病一句话概述偏低该用不用爱编造增加触发条件中等边界把握不准过度触发触发条件反例较高需要逐步调试描述略啰嗦这段实测的核心启发是技能描述决定模型多少个节点在用。别急着把代码写复杂先在描述上多花几轮效果好得多。4. 常见问题与排查技巧实录4.1 技能不生效多半是描述写得像科普文章你给模型配了技能它就是不调用这是最普遍的问题。我排查这类问题第一步不是改代码而是把技能描述拿出来读一遍看它像什么。如果描述读起来像“某某产品介绍”基本就废了。什么叫像科普文章比如“本技能用于提供天气信息支持城市查询、未来几小时预报、温湿度展示等功能”这种写法满篇都在讲我有什么能力没有告诉模型你该在什么时候用它。模型是没有常识的它不知道“用户问今天要不要带伞”等价于“查询当前天气”需要你显式写清楚。改成什么样子为好“当用户询问当前或未来的天气状况包括温度、降水、风力或者用户问要不要带伞、要不要晾衣服这类隐含天气需求的问题时使用此技能。”把触发场景列得越具体模型越不容易跑偏。4.2 参数幻觉模型自己发明参数怎么办参数幻觉是最让人头疼的问题之一。明明你的技能只需要两个参数模型非要传五个甚至编造一个你根本没定义过的参数名。这种情况在参数较少、描述不够严谨的时候尤其高发。我的应对策略是三道防线同时上。第一道是严格 JSON Schema能设 enum 就设 enum能设 format 就设 format让模型几乎没有自由发挥的空间。第二道是参数清洗模型传进来的参数过一层校验函数不认识的关键字直接丢掉缺失的必填参数用默认值补齐。第三道是执行失败容忍万一参数不合法也不要直接抛异常给模型回传一条错误提示让它重新生成参数。def safe_call_skill(skill, args): clean_args {} props skill.parameters.get(properties, {}) for key, meta in props.items(): if key in args: clean_args[key] args[key] elif key skill.required or key in skill.required: default meta.get(default) if default is not None: clean_args[key] default else: return Error: missing required param: key try: return skill.execute(**clean_args) except Exception as e: return fError: {str(e)}这道防线不是万能的但它能让你从“模型乱传参数导致系统崩溃”的坑里爬出来把问题收敛到可追踪的错误信息里。4.3 技能冲突与优先级多个技能同时触发怎么办技能数量一多新问题就来了模型看哪个描述都像一次调用好几个技能结果互相影响甚至死循环反复调用。这是技能体系设计避不开的一个坎。解法有两个维度。一是从源头控制保证技能之间的触发条件互斥比如“搜索信息”和“查询本地数据库”虽然都返回值但触发场景要明确区分开——前者面对未知外部信息后者面对已入库的内部数据。二是每次调用只允许模型选择最相关的技能不搞“同时执行一堆”的策略复杂的并发需求应放在技能内部实现而不是靠模型同时调多个技能。如果发现模型频繁在几个技能之间来回横跳比如先调 A 搜索、又调 B 总结、又回到 A 重新搜索大概率是技能职责划分不清。这时候我的建议是重新审视技能边界把重叠的逻辑合并成一个复合技能而不是靠模型自己收住。4.4 一套亲测有效的整链路自检清单排查 Agent 技能问题最忌讳的就是乱试。我给自己定的规矩是遇到问题先按清单逐项检查保证一套流程走下去能定位大部分问题。检查项对应问题验证方法技能描述是否有触发场景该用不用把描述喂给模型问它什么时候调用参数 Schema 是否足够严格参数幻觉随机生成 20 组参数测解析技能执行是否幂等重复调用有副作用同一参数跑两遍对比结果超时设置是否合理长时间卡死模拟慢接口压测返回值是否清晰模型二次推理失败查看模型收到结果后的生成质量技能之间是否有交叉多技能互相干扰画一个技能触发条件矩阵这套清单看起来简单但我每次做新技能上线前都会完整走一遍。尤其是前两条能挡掉 70% 以上的低级问题。5. 后面还能怎么玩agent-skills 的进阶方向5.1 让 Agent 自己写技能技能体系做到中期你会开始琢磨一个问题能不能让模型自己定义新技能答案是能而且这才是 agent-skills 的终极形态之一。我在实验里搭过一个闭环先给模型一个“创建技能”的元技能它负责根据用户任务描述生成新的技能代码、参数 Schema 和描述文本生成后立刻在一个沙箱环境跑一遍冒烟测试通过就注册进技能库失败就带着错误信息让模型迭代修改。这个模式下整个系统的技能库会随着任务使用而增长用越多越聪明。当然风险也很明显。自动生成技能如果控制不好代码注入、无限递归调用都出现过。我的建议是自动生成的技能必须单独标记不赋予高危权限而且先经过一轮人工或自动的代码审查再决定是否启用。你要是图省事直接放开迟早出事。5.2 技能评估与回归不能让 Agent 越用越笨技能只会加不会减最后一定是灾难。所以我强烈建议给技能库配一套回归评估机制每次模型升级、技能调整之后都能看到效果曲线。我自己的做法是维护一个任务用例集大概 100 个左右覆盖技能的典型场景、边界场景和异常场景。每次技能变更跑一遍用例集统计通过率、平均调用步数、平均耗时、失败原因分布。通过率下降了就说明这次改动引入了回归需要回滚或修 bug。这套机制不复杂但能让技能体系的迭代走上正轨而不是靠感觉东改一下西改一下。5.3 跟现有工具链怎么结合最后说说和现有系统的关系。agent-skills 从来不是一个孤立的东西它必须跟你的日常开发工具链嵌在一起才有价值。常见搭配是把命令执行能力封装成技能Agent 就能操作开发环境里的脚本把函数接口封装成技能Agent 就能编排业务流程把文件读写、数据查询封装成技能Agent 就能做数据分析。核心原则是技能对外暴露的接口要稳定内部实现可以随版本迭代频繁替换。我在实际项目里习惯把一个技能对应的实现代码和测试用例放在同一个目录下技能描述里自动附带版本号。这样技能变更时可以追溯到具体版本出问题了也能快速定位是模型的问题还是技能代码的问题。最后说几句实在话做 agent-skills 这么久我的核心体会其实一句话Agent 的智能化程度不取决于你用了多大的模型而取决于你给它沉淀了多少可复用的高质量技能。模型负责聪明技能负责靠谱两者缺一不可。如果你现在正在做 Agent 相关的东西我的建议是可以从一个最小可用的技能开始不用上来就搭完整平台。先把一个技能做扎实跑通注册、调用、结果回传、异常兜底的整条链路再慢慢往里面加技能。最后再送一个小技巧每次新增技能之前先反问自己三遍“模型真的需要这个技能吗”能砍掉的技能越多你的 Agent 反而越稳定。