1. 从agent-skills这个命名说起它到底指什么第一次看到agent-skills这个词很多人会下意识地把它理解成某个具体的库或者框架。但如果你在工程一线待过一段时间就会发现这类命名往往指向的是一类能力组织方式而不是某一个可以pip install的包。它描述的是一种思路把智能体agent需要具备的各种能力拆解成一个个独立、可复用、可组合的技能单元然后让智能体在运行时按需调用。这个思路听起来简单但它解决的是一个非常现实的问题。早期做智能体的时候大家习惯把所有逻辑塞进一个巨大的提示词里——角色设定、工具说明、流程约束、输出格式全堆在一起。结果就是提示词越写越长改一处牵动全身调试基本靠猜复用更是无从谈起。agent-skills 这类模式的出现本质上是对这种一锅炖做法的反思和重构。它适合谁来了解如果你正在做对话系统、自动化流程、任务编排或者任何需要让模型自己决定下一步做什么的场景这套思路都值得花时间吃透。哪怕你只是想让模型稳定地完成查资料—整理—输出这种三步任务理解技能化的组织方式也能让你的系统健壮不少。下面我会从设计动机、技能拆解、调度机制、落地踩坑几个角度把这件事讲透。2. 为什么要把能力拆成技能而不是写进一个大提示词2.1 单体提示词的三个致命伤先说清楚问题才能理解方案的价值。把全部能力写进一个提示词短期看省事长期看会积累三类问题。第一类是可维护性崩塌。当提示词超过两三千字任何一次修改都可能产生意料之外的连锁反应。你只是想调整输出格式结果模型对某个工具的描述理解变了调用时机也跟着漂移。这种耦合在工程上是灾难。第二类是上下文浪费。一个智能体可能具备二十种能力但单次任务往往只用到其中两三种。如果全部塞进上下文不仅消耗 token还会稀释模型的注意力——无关信息越多模型抓重点的能力越弱这在长上下文场景里尤其明显。第三类是无法独立验证。整体提示词是一个黑盒你很难单独测试查天气这个能力是否可靠。而拆成技能之后每个技能可以有自己的输入输出契约、自己的测试用例、自己的失败重试策略。2.2 技能化带来的组合自由度拆成技能之后最大的收益是组合。一个写周报的任务可以被拆成拉取本周提交记录汇总关键进展按模板生成文本三个技能。这三个技能单独看都很简单但组合起来就能完成一个复杂任务。更重要的是这些技能可以被别的任务复用——拉取提交记录这个技能在生成发布说明的任务里同样能用。这种思路和传统软件工程里的函数抽象是一回事。你不会把所有逻辑写进 main 函数同样也不该把所有能力写进一个提示词。技能就是智能体世界里的函数有明确的输入、输出和职责边界。2.3 一个具体的对比假设你要做一个能回答帮我看看这周项目进展的助手。单体做法是把项目数据格式、汇总规则、输出模板全写进提示词。技能化做法是拆成三个技能维度单体提示词技能化组织修改汇总规则需通读全文风险高只改对应技能单次 token 消耗全量加载偏高按需加载可控独立测试几乎不可能每个技能单独测跨任务复用复制粘贴直接引用失败定位靠猜定位到具体技能这张表不是理论推演是我在实际项目里反复验证过的。技能化之后调试时间通常能压缩一半以上因为问题范围被限定住了。3. 一个技能应该包含哪些要素3.1 技能描述让模型知道什么时候用我技能描述是整个机制里最容易被低估的部分。很多人写技能描述时只写这个技能做什么但真正关键的是什么时候该用它。模型选择技能的依据几乎完全来自这段描述。一个好的技能描述应该包含三部分能力边界能做什么、不能做什么、触发条件什么情况下该调用、以及必要的输入说明。举个例子查询订单状态这个技能描述里要明确当用户询问订单进度、物流位置、预计到达时间时使用而不是笼统地写查询订单。提示技能描述里如果缺少什么时候用模型很容易在无关场景下误调用或者在该用的时候视而不见。这是新手最常踩的坑。3.2 输入输出契约技能之间的接口技能要被组合就必须有稳定的接口。输入是什么格式、输出是什么格式必须写死。我见过太多项目因为输出格式不统一导致上游技能的输出没法直接喂给下游技能中间还得加一层转换白白增加复杂度。实践中比较稳妥的做法是所有技能的输出都用结构化格式比如 JSON字段名保持一致的命名风格。这样组合的时候不需要额外适配。如果某个技能的输出是自然语言那也要约定好它包含哪些必要信息方便下游解析。3.3 执行逻辑技能内部怎么干活技能内部可以是纯提示词驱动也可以是代码加提示词的混合。简单的技能比如把一段文字翻译成英文纯提示词就够了。复杂的技能比如从数据库拉数据并做聚合就需要代码参与。这里有个经验能用确定性代码解决的就不要交给模型。模型擅长的是理解意图、处理模糊输入、生成自然语言不擅长精确计算和确定性操作。把该用代码的部分用代码写模型只负责它真正擅长的环节整个系统的稳定性会高很多。3.4 失败处理技能出错了怎么办技能化之后失败是局部的这是好事。但前提是你得为每个技能设计好失败处理。常见的策略有三种重试适合网络抖动这类临时故障、降级返回一个兜底结果、以及上报把失败信息传给调度层让它决定下一步。我个人的习惯是给每个技能都配一个明确的失败返回格式而不是让它抛异常或者返回空。这样调度层能统一处理不会因为某个技能静默失败导致整个任务卡住。4. 技能调度模型怎么知道该调用哪个技能4.1 基于描述的语义匹配最直接的方式是把所有技能的描述提供给模型让它根据当前任务选择。这种方式灵活但有个前提技能数量不能太多。技能一多描述本身就占满上下文模型的选择准确率也会下降。实测下来技能数量在十个以内时纯语义匹配的效果还不错。超过这个数量就需要引入分类或者分组机制先缩小候选范围再做精确选择。4.2 分层调度先选类别再选技能分层调度是我比较推荐的做法。把所有技能按领域分成若干组比如数据处理组文本生成组外部查询组。调度时先让模型判断任务属于哪个组再在组内选具体技能。这样每次需要模型处理的候选数量就控制住了。这个思路和现实中的组织架构很像你不会让一个人记住公司所有同事的名字而是先找对部门再找对人。分层之后技能库可以扩展到几十上百个而调度准确率不会明显下降。4.3 显式编排与隐式选择的取舍还有一种做法是显式编排不依赖模型选择而是由开发者预先定义好技能的执行顺序。比如先查数据再汇总最后生成报告这个流程写死在代码里。显式编排的优点是稳定、可预测缺点是灵活性差遇到计划外的输入就抓瞎。隐式选择让模型决定灵活但稳定性差一些。实际项目里我通常采用混合策略主流程用显式编排保证稳定分支和异常处理交给模型隐式选择。这样既有骨架的确定性又有应对变化的弹性。5. 落地时最容易踩的几个坑5.1 技能粒度过细或过粗粒度是技能化设计里最难拿捏的东西。拆得太细技能之间调用次数暴增每次调用都有开销和出错概率整体反而更慢更不稳。拆得太粗又回到了单体提示词的老路失去了拆分的意义。我的判断标准是一个技能应该对应一个语义上完整、不可再分的动作。查询订单是完整的拼接查询参数就太细了它应该是查询订单内部的事。生成完整报告又太粗它明显包含多个可独立验证的步骤。5.2 技能之间的隐式依赖技能 A 的输出被技能 B 使用但 B 并不知道 A 的存在这种隐式依赖是维护的噩梦。一旦 A 改了输出格式B 就悄悄坏掉而且往往要到线上才暴露。解决办法是让依赖显式化。要么在技能定义里声明它依赖哪些上游技能的输出要么通过统一的中间数据结构来传递信息让每个技能只依赖这个结构而不依赖具体某个技能。后者更灵活也是我更常用的方式。5.3 忽略技能的副作用有些技能是有副作用的比如发送邮件修改数据库提交表单。这类技能一旦被误调用后果比查询类技能严重得多。对这类技能我建议加一层确认机制或者在描述里明确标注此操作不可逆调用前需确认。注意有副作用的技能永远不要让它成为模型可以随手调用的选项。要么加确认要么限制调用条件要么干脆从自动调度里排除只允许显式触发。5.4 调试信息不足技能化系统出问题时如果每个技能的执行过程没有日志排查会非常痛苦。你只知道最终结果不对但不知道是哪个技能、哪一步出的问题。我的做法是给每个技能的执行都记录三样东西输入、输出、耗时。这三样信息足够定位绝大多数问题。如果技能内部还有多步再细化记录。日志不用花哨能还原执行链路就行。6. 从零搭一个最小可用的技能系统6.1 定义技能的数据结构先定一个技能长什么样。用 JSON 描述的话大概是这样{ name: query_order_status, description: 当用户询问订单进度、物流位置或预计到达时间时使用。输入订单号返回当前状态。, input_schema: { order_id: string }, output_schema: { status: string, location: string, estimated_arrival: string }, handler: handlers/query_order_status.py }这个结构里description是给模型看的input_schema和output_schema是给调度和组合用的handler是实际执行逻辑。三者分离各司其职。6.2 实现调度循环调度循环的核心逻辑不复杂拿到用户输入把技能描述列表给模型模型返回要调用的技能和参数执行技能把结果喂回模型循环直到模型认为任务完成。def run_agent(user_input, skills, max_steps10): messages [{role: user, content: user_input}] for _ in range(max_steps): response model.chat(messages, toolsskills) if response.is_final: return response.content tool_call response.tool_call result execute_skill(tool_call.name, tool_call.args) messages.append(response.message) messages.append({role: tool, content: result}) return 任务步骤超出上限已终止max_steps这个上限很重要它是防止死循环的最后一道防线。没有它模型可能在两个技能之间反复横跳永远不收敛。6.3 加一层结果校验技能返回的结果不要直接信任尤其是涉及外部数据源的技能。加一层校验检查返回是否符合output_schema字段是否齐全类型是否正确。校验不通过就触发失败处理而不是把脏数据往下传。这一步看起来多余但能挡掉大量莫名其妙的下游错误。很多问题的根源其实是某个技能返回了格式不对的结果然后一路污染到最终输出。7. 技能库变大之后怎么管7.1 命名规范要统一技能一多命名混乱的代价就显现出来了。get_user、fetchUserInfo、query_user_data三种风格混在一起模型选择时容易混淆人维护时也费劲。我建议统一用动词_名词的下划线风格动词尽量收敛到几个标准动作query查询、create创建、update更新、delete删除、generate生成、send发送。这样技能名本身就传达了足够的信息。7.2 定期清理僵尸技能项目迭代过程中总会有一些技能不再被调用但也没人删。这些僵尸技能留在库里不仅占描述空间还会干扰模型选择。定期统计每个技能的调用次数长期为零的要么删掉要么归档。7.3 版本管理技能的输出格式一旦被下游依赖就不能随便改。需要改的时候要么加新字段而不是改旧字段要么引入版本号让新旧版本并存一段时间。这个和 API 版本管理是一个道理只是很多人做技能时忘了这一层。8. 关于这套思路的一点个人体会技能化这套东西说到底是在用工程手段约束模型的自由度。模型很强但强不等于可控。把能力拆成技能本质上是给模型划定了一个个可以做什么的格子让它在格子里发挥而不是漫无边际地自由发挥。我踩过最大的坑是一开始追求技能越通用越好结果每个技能都写得很泛描述模糊模型根本不知道该用哪个。后来反过来把技能写得具体、边界清晰哪怕看起来不够优雅实际效果反而好得多。通用性应该来自技能的组合而不是单个技能的泛化。另一个体会是别指望一次设计到位。技能划分合不合理只有跑起来才知道。先搭一个能跑的最小版本观察模型实际怎么调用、哪里卡壳、哪里误判再回头调整拆分方式。这个过程通常要迭代好几轮急不得。如果你正准备上手我的建议是从三个技能开始一个查询类、一个生成类、一个带副作用的操作类。把这三类都跑通调度、校验、失败处理这些机制也就都摸清楚了后面扩展就是复制经验的事。