从模型只会“聊天”到能“干活”中间隔着的往往不是更强的模型而是一套能把能力沉淀下来、随时复用的技能框架。最近我在梳理自己的 Agent 项目时把大量时间花在“让 Agent 稳定地完成某个具体动作”上比如搜索网页、解析文档、调用 API、生成结构化数据。一开始每个任务都在对话里临时写 prompt后来发现这套玩法在真实场景里根本撑不住——同样的动作换个数据源就要重写Agent 稍微跑偏一点整个流程就崩。最后我转向了一种更工程化的组织方式把每个可复用的能力封装成独立的“技能”skill用统一的格式描述、注册、调用和管理也就是现在社区里讨论很多的 agent-skills 思路。这篇文章就基于我实际落地的项目经验把技能化改造的完整过程、关键细节和踩过的坑一次性讲清楚适合正在做 Agent 应用、被 prompt 工程折腾到头秃的开发者参考。1. 从“一把梭”到“技能库”为什么 Agent 需要技能化改造1.1 没有技能体系的 Agent 长什么样很多人的第一个 Agent 是从“一个 system prompt 一个模型 API”开始的。我自己的第一个版本就是这样把所有指令写在一大段 system message 里再把几份文档直接丢进上下文然后期待模型自己“理解并完成”任务。在小规模演示的时候这套方案确实够用因为任务单一、文档不长、容错率高。一旦任务变复杂问题就会集中爆发。最典型的症状是“全局上下文失控”。假设你的 Agent 要完成三步连招抓取网页 → 提取正文 → 生成摘要并发送到某个接口。如果这些逻辑全部堆在同一个 prompt 里模型每一步都会重新读一遍所有指令和中间结果。上下文越长注意力就越分散到第三步时模型很可能已经忘了第一步产出的数据是什么格式。我实测过把抓取逻辑、解析规则、摘要风格、接口规范全写在一起之后模型执行第三步的成功率会从九成以上掉到七成左右而且失败方式千奇百怪。另一个症状是“改动成本极高”。业务方说“摘要风格改成三段式”你表面上只改一句话实际上要重新调试整个 prompt 链。因为每段逻辑之间互相耦合牵一发而动全身。更麻烦的是这种“一把梭”方案几乎无法测试——你能测试的是“整个对话的输出”但没法单独验证“网页抓取这一步是否稳定”。一整套流程跑下来出了问题只能靠肉眼排查浪费时间还不解决问题。1.2 技能化的核心收益我把项目拆成技能体系之后感受最明显的变化是每个动作终于有了独立的“单元测试”。Agent 技能的思路其实很朴素——它把 Agent 的一项能力封装成一个自包含的单元这个单元既包含“什么时候用”的描述信息也包含“具体怎么干”的指令还可能包含简化实现的代码片段。结构上有点像给模型准备了一份“可调用的说明书”模型看到任务后不再从零理解你零零散散的指令而是直接匹配最合适的技能包。技能化之后有三点收益是实打实的。第一个是可复用性。我在 A 项目里写好的“网页正文提取”技能在 B 项目里直接复制过去就能用只要换一下输入参数即可不需要重新调试 prompt。第二个是可评测性。每个技能是独立单元我可以单独构造测试用例批量跑一百次来看成功率而不是等到端到端流程跑挂了才后知后觉。第三个是可组合性。技能像乐高积木一样可以拼接。这次任务需要搜索 提取下次任务需要搜索 翻译我只需要重新编排技能调用顺序不需要重写底层逻辑。这里要强调一个容易误解的点技能化不是“把 prompt 拆成几个文件”就完事了。真正的技能化是三层解耦——描述层、指令层、实现层彼此独立。描述层告诉 Agent“这个技能是干什么的、什么时候用”指令层是模型执行时的思维引导和步骤说明实现层则是可选的代码函数用于完成模型不擅长的精确计算或 API 交互。我花了很长时间才想明白这个分层之前一直把“技能文件”理解成“大号 system prompt”结果迁移效果很差。后面会详细展开。2. 拆解“技能”的最小可用单元2.1 技能文件的标准形态先给出一份通用技能目录的最小结构。不同框架的具体命名可能不同但核心单元是一致的skill-name/ ├── SKILL.md # 技能描述与使用说明Agent 通过它来决定是否调用 ├── reference/ # 参考文档与示例供模型在需要时查阅 │ ├── example-input.json │ └── api-schema.md └── scripts/ # 实现层代码可被模型直接调用执行 ├── run.py └── requirements.txt以我自己最常用的“网页正文提取”技能为例SKILL.md 的开头长这样--- name: webpage_content_extractor description: 从指定 URL 抓取网页正文去除导航、广告、页脚等干扰内容返回干净的文本与标题。适合用于阅读文章、收集信息、内容分析等场景。 --- # 网页正文提取技能 ## 使用条件 - 用户提供 URL 并要求提取网页内容、获取正文、做内容分析时使用 - 输入需要包含目标 URL - 输出为结构化文本标题 正文内容 ## 执行步骤 1. 使用 get_webpage() 函数获取网页 HTML 2. 调用 parse_article() 解析正文提取标题与内容 3. 清理无用字符控制返回长度在 5000 字以内这里最关键的字段不是“执行步骤”而是description。Agent 决定是否调用这个技能主要看 description 里描述的“适用场景”和用户的当前意图是否匹配。我见过很多新手把 description 写得特别宽泛比如“从 URL 获取内容”结果模型在任务完全无关的时候也强行调用造成幻觉式输出。好的 description 应该像给函数写 docstring 一样说清楚输入、输出、适用边界和典型场景让模型的“匹配决策”有足够依据。2.2 技能描述与触发条件的边界在配置技能描述时我总结出一个“两明确一模糊”的经验明确输入、明确输出、适当模糊过程。输入明确描述里要写清楚调用这个技能需要什么前置信息。“需要用户提供 URL且 URL 必须能通过公网访问”就比“输入网页链接”精确得多。输出明确写清楚技能返回什么格式。比如“返回 title字符串和 content字符串”模型就知道拿到结果后该怎么接后续流程。过程模糊不要事无巨细地规定“第几步做什么第几步再做什么”。模型需要的一定程度的自由度规定得太死反而会让它在遇到意外情况时卡住不动。我还踩过一个具体坑在 description 里写了“注意不要访问非法页面”。这句话本意是安全限制但模型读完反而对“非法”这个概念产生了过度解读在一次正常新闻抓取任务中拒绝调用技能理由是它判断目标页面“可能包含不当内容”。后来我把这句删掉只保留“仅抓取用户明确指定的 URL”问题就消失了。技能描述是写给“匹配器”看的不是写给“审查器”看的不要往里面塞过多额外的语义。触发条件的设置还涉及一个平衡问题到底该让 Agent 在什么情况下“忽略”这个技能我的做法是给每个技能加一个“反向条件”明确写清楚“不需要调用本技能的情况”。比如网页提取技能的反向条件是“用户只是讨论网页设计风格不要求获取内容”翻译一下就是“别滥用我”。这样做的一个最直接收益是减少模型在无关任务上的自动调用次数既省 token 又避免错误输出。2.3 技能实现层什么该用代码什么该靠模型技能实现层不是必须的但没有实现层的技能往往会卡在“精确计算”和“结构解析”上。模型天生擅长语义理解不擅长严格的数值计算和字符串处理。如果你让 Agent 自己“数一下这段文本里出现了几次某个关键词”它十有八九会给你一个统计值但你没法验证这个值是否正确换成一段简单的 Python 代码结果是确定的、可复验的。因此我的原则是凡是能用代码确定性完成的操作就绝不让模型自由发挥。拿“网页正文提取”来说如果只依赖模型读 HTML 再归纳正文面对几十 KB 的 HTML 源码上下文先爆一半提取质量还不稳定。我的实现层用 Python 直接处理先请求页面拿到 HTML再用解析库提取 main 标签或 article 标签内的文本最后做清洗。模型只负责“决定调用技能 把目标 URL 传进来”剩下的脏活累活用代码完成。实现层的另一个价值是可以封装外部 API。比如“发送 HTTP 请求并保存响应”这个技能脚本里其实只是标准库的 requests 调用但封装之后模型不需要理解 HTTP 状态码、超时重试、SSL 异常这些细节只需要把 URL 和参数传给脚本即可。这对模型来说极其友好。我实测过不封装时模型写出的 requests 代码经常漏掉 timeout 参数或者不处理连接异常封装之后这些通病全部消失。3. 手把手构建一个可复用的技能3.1 场景选择与技能边界第一个技能建议选择一个“边界清晰、动作明确、可验证”的任务不要一上来就做“综合分析报告”这种高难度动作。我用得最顺手的入门案例是“把一段 Markdown 文本里的标题自动提取成目录”。这个技能边界很清晰输入是 Markdown 文本输出是带有层级的目录列表。整个过程不涉及外部 API不依赖网络环境适合用来跑通整个技能开发和调用流程。确定场景后最重要的设计决策是边界划分。什么叫边界就是技能到底应该做什么、不应该做什么。如果技能设计成“输入 Markdown输出目录并自动渲染成网页”那就有两个边界问题它是负责提取目录还是负责渲染网页一旦某个功能模块有多个意图技能描述就会变得含糊Agent 在调用时也会犹豫。正确的做法是“一件事一个技能”目录提取归目录提取网页渲染另起炉灶。我在实际开发中给技能边界设了三条硬约束你可以直接用技能必须能被一句话讲清楚。如果一句话讲不清说明边界还是太宽需要继续拆。输入输出必须能用一个 JSON 结构描述。不能明确描述出参和入参的技能后续组合一定会出问题。技能不得依赖另一个技能才能“完成基本功能”。技能之间可以组合但单个技能必须能独立调用并产出有效结果。这三条约束帮我砍掉了不少华而不实的设计。早期我总想做一个“超级信息处理技能”输入任何文档输出结构化总结结果描述写了两百字还是模棱两可。按上面三条规则一拆变成了“PDF 文本提取”“长文本分段”“摘要生成”三个独立技能每个都简单清晰组合起来反而比那个“超级技能”更好用。3.2 技能外壳从描述到指令的完整写法选定“Markdown 标题提取目录”这个场景后我写出的技能外壳如下--- name: markdown_toc_generator description: 提取 Markdown 文本中的标题#、##、### 以及 #### 级生成带层级和锚点的目录。适合用于文档整理、文章结构分析、自动生成目录等场景。若用户要求渲染网页或输出 HTML则不使用本技能。 --- # Markdown 目录生成技能 ## 输入 - markdown_text: 字符串Markdown 格式的文档内容 ## 输出 - toc: 数组每个元素包含 level1-4、title标题文本、anchor锚点 ## 执行步骤 1. 逐行扫描 markdown_text识别行首的 # 数量标记标题级别 2. 清洗标题文本去掉行内格式符号保留纯文本 3. 根据标题文本生成 GitHub 风格锚点 4. 忽略代码块内的 # 字符避免误判这个外壳就是技能的门面和说明书。模型拿到它第一步读description判断当前任务是否匹配第二步读执行步骤了解该怎么做第三步决定是否调用。由于这个技能很简单没有实现层也可以。但为了演示完整形态我加了一个run.py直接用 Python 正则处理标题提取和锚点生成模型只需要把 markdown_text 传进来拿到的就是标准 JSON 目录结构。编写技能外壳时有一个特别重要的写作习惯不要出现“如果需要”“可以尝试”“尽可能”这类模糊词。技能指令是指令不是建议模糊词会让模型在执行时产生随机性。比如“忽略代码块内的 # 字符”这是一个确定性指令而“尽量忽略代码块内的 # 字符”模型就可能在某些情况下不忽略然后输出错目录。确定性指令可能不是最优写法但它是可复现的而可复现是技能工程的第一步。3.3 在 Agent 中注册与验证技能写完下一步是注册进 Agent 的调用流程。不同框架注册方式不同但核心动作是统一的把技能的描述信息注入到模型可感知的上下文中。我用的方式是为每个技能生成一个精简的注册表条目在每次会话开始时作为上下文前缀注入。注册表长这样{ skills: [ { name: markdown_toc_generator, description: 提取 Markdown 文本中的标题生成带层级的目录。, input_schema: { markdown_text: string }, output_schema: { toc: array } }, { name: webpage_content_extractor, description: 从指定 URL 抓取网页正文返回标题与内容。, input_schema: { url: string }, output_schema: { title: string, content: string } } ] }这里有一个关键经验注册表里不要放“完整 SKILL.md”只放“描述 输如出结构”。因为完整 SKILL.md 可能几百上千字全部塞进上下文会占用大量窗口还会稀释其他系统指令的注意力。精简注册表就像给模型一份“菜单”先看菜单选菜选中了再上详情。模型决定调用某个技能后系统再把完整的 SKILL.md 和实现脚本注入执行上下文这时候才需要完整指令。验证流程同样重要。每写完一个技能我的测试步骤固定在五步构造 5 个正常输入用例确认技能能产出期望输出。构造 2 个边界用例比如空输入、超长输入、含代码块的文档确认技能表现稳定。检查输出结构是否严格符合 schema不允许字段缺失。在完整 Agent 中以自然语言发一次任务看模型能不能正确触发该技能。检查调用过程消耗的 token 数记录基线方便后续优化。这五步不仅能验证技能本身的正确性还能顺便验证“描述是否足够清晰”。如果模型在第四步没能触发技能大概率是 description 写得不够精准优先级第一排查的就是它。4. 技能编排与组合的精髓4.1 顺序编排的典型陷阱单技能跑通只是第一步。真实业务里Agent 要做的事情往往是多技能组合。我自己最早踩的坑是“把技能编排写死成固定流程”先技能 A再技能 B再技能 C像流水线一样。这么做的问题是真实任务中 A 的输出并不总能成为 B 的合法输入。举个例子搜索技能 A 输出一组 URL网页提取技能 B 本来应该接收其中一个 URL但如果 A 输出的格式因为某个搜索源变化而意外改变B 就会拿不到合法 URL整条流程卡死。固定流程还有一个问题它剥夺了模型在中间步骤做判断的机会。Agent 的意义就在于“动态决策”如果流程完全固定那跟普通脚本有什么区别我后来的做法是给编排层加了一个“步骤校验点”每一步执行完先把输出与预期 schema 做一次校验校验通过才进入下一步不通过则触发重试或让模型修复数据。这个校验逻辑很轻量但对稳定性的提升是数量级的。关于顺序编排我还有一个很现实的建议组合链路超过四个技能时尽量考虑拆分任务。不是技术上做不到而是排错成本会指数级上升。链路越长中间产物链路越复杂任何一环的意外都会让端到端调试变成噩梦。四个技能以内是可控的超过这个数我会重新思考整个任务拆解看看能不能合并中间步骤或引入更粗粒度的技能。4.2 组合复用与技能路由技能组合有两种模式我习惯叫它们“串联模式”和“路由模式”。串联模式比较好理解就是 A→B→C 依次执行每个技能的输出作为下一个技能的输入。路由模式则是在一组技能前面加一个“路由器”模型根据任务内容动态选择走哪个分支。路由模式更适合“多类型输入、多类型输出”的场景比如内容整理任务里模型先判断输入是网页链接、PDF 文件还是纯文本再选择对应的处理技能。路由模式的实现不需要额外的模型调用只需要在编排层加一个轻量的“意图判断”逻辑读取当前任务的输入结合各技能的 description 做一次相似度或规则匹配选出一个技能加载。如果匹配结果置信度低可以再让模型做一次明确的选择但不建议每个任务都让模型来做路由那样费 token 且增加了不确定性。技能路由的一个关键设计是“兜底技能”。不管模型能不能匹配到合适的技能系统都应该有一个默认的“万能技能”比如一个最简单的“自然语言回答”兜底防止它面对陌生任务时不知所措。打个比方技能路由就像一家餐厅菜谱上的菜是各种技能但总得准备一道“今日例汤”客人实在不知道吃什么的时候至少不会饿着肚子出去。这个兜底技能不需要复杂它的价值是让 Agent 在异常情况下仍然能给出合理响应而不是输出一堆错误代码或断言失败。4.3 技能状态管理与记忆技能编排遇到的下一个问题是状态管理。串联模式下技能 A 的中间结果要不要保存技能 C 用到的数据是技能 B 的完整输出还是只需要其中一部分这些决策直接影响 token 消耗和输出稳定性。我的做法是引入一个“工作记忆区”working memory以轻量 JSON 结构保存每个步骤的产出摘要而不是把完整输出一直挂在上下文中。比如网页提取技能的完整正文有 5000 字但后续摘要技能只需要前 1000 字和标题那么工作记忆里只存这 1000 字加标题既保持上下文干净又不会丢关键信息。工作记忆不是越大越好它应该是“够用即可”的。我常比喻这就像做菜时台面上只放当前步骤要用的调料其他瓶瓶罐罐收到柜子里。如果你把十几个技能的全部产出都堆在台面上模型到后面根本分不清哪些是当前的、哪些是过期的。给每条记忆加时间戳和来源技能名是保持状态清晰的最简单手段。更进阶一点技能之间还可以共享“持久化记忆”。比如“用户偏好信息”技能可以把用户偏好的摘要写到持久化存储中后续会话直接读取不需要用户重复描述。这个机制实现起来不难难点在于“什么时候更新记忆、什么时候读取记忆”。我的经验是读操作显式触发写操作显式触发不要让模型自己决定是否读写否则它会在任何任务开始时都尝试读一下用户偏好白白浪费上下文且影响主要任务的注意力。5. 常见问题与排查技巧实录5.1 技能就是不触发怎么办这是技能化落地时遇到频率最高的问题。技能文件明明写好了注册表也注入了模型就是不调用宁愿自己“硬答”也不走技能。我排查这个问题的顺序如下先检查description是否和用户“会怎么提问”的方式对得上。模型有很强的情景匹配能力但前提是技能描述里的词汇和用户问题的词汇有足够的语义重叠。如果你的技能叫markdown_toc_generator描述是“提取 Markdown 文本中的标题生成带层级的目录”用户提问则是“帮我把这篇文章整理一下”这中间缺乏直接的语义桥梁。解决办法是在 description 里多补几个“别名场景”比如“整理文档结构”“看看文章有哪些章节”“帮我做一份文章大纲”。再检查注册表的注入位置。有的框架会把技能注册表作为 system prompt 的一部分注入有的则作为“工具列表”语义注入。不同位置对模型的约束力不同。如果技能描述被放在离主任务指令很远的上下文位置模型读取它的注意力权重会明显降低。我的经验是技能注册表要么放在最开头要么放在最接近“用户最新一条消息”的位置这两个位置是模型注意力最强的区域。最后检查是不是有“竞争性指令”在干扰。比如系统 prompt 里写了“直接回答用户问题不要解释”模型可能因此产生误解觉得调用技能是一种多余动作。调试的时候先把这些约束性指令临时删掉看技能是否恢复触发然后再把指令用更精确的方式加回去。5.2 上下文膨胀与技能瘦身技能数量一旦超过十个上下文就开始吃紧。每个技能注册表条目哪怕只占 200 token十个就是 2000 token。加上系统 prompt、用户历史消息和中间产物窗口很快就满了。这个问题最常见的表现是模型开始遗忘早期步骤的关键信息技能输出的结果越来越偏离预期。我的解决思路是“分层加载、按需注入”把技能注册表分成两层。第一层是“常驻层”只放最高频调用的 3-5 个技能的精简描述占用 500 token 以内。第二层是“候选层”所有技能都登记在内部索引中但不主动注入。当用户任务涉及某个候选技能时编排层先做一次关键词或意图匹配再把对应技能的完整描述临时注入到下一个模型调用中。这样既保证了技能覆盖面又把常驻上下文控制在可接受范围。技能本身的指令也可以瘦身。SKILL.md 里最占 token 的往往是“执行步骤”里的长句子。我的写法是尽量用短句和关键词能列表就列表能省略的修饰词一律不写。“逐行扫描 markdown_text识别行首的 # 数量标记标题级别”比“你需要仔细地逐行扫描用户输入的 Markdown 内容并且识别每一行开头有几个 # 符号这个符号数量代表了标题级别”省了一半多的 token信息量完全相同。瘦身的核心原则是技能指令是给模型“看的”不是给模型“读的”句子越短指令性越强。5.3 技能执行失败后的恢复策略技能执行失败是必然事件设计系统时必须把它当成“正常路径”来对待而不是“异常分支”。我自己整理出的恢复策略按成本从低到高排列重试一次适用于偶发性网络错误或临时性 API 抖动。数据修复适用于“输出结构对但字段值不对”。让模型对照 schema 修复数据而不是推翻重来。降级方案比如网页提取失败时改为提示用户手动粘贴内容不强行重复尝试。链路回退编排链中间某技能失败且修复后仍不成功直接让用户选择“终止”或“换一种任务思路”不要让模型硬编一个不存在的执行结果。这里我最想强调的一个反直觉经验是不要追求 100% 的成功率。在真实系统里追求最后 5% 的成功率往往要付出 50% 的工程成本。更现实的策略是让失败变得“可感知、可恢复、可接受”。例如网页提取技能成功的核心场景成功率做到 92%剩余 8% 走降级方案用户虽然没拿到自动提取结果但至少收到一个明确的提示没有卡死在无限重试或输出错误结果的状态。对整个产品体感来说这种“干脆的失败”远比“假装的成功”要好。5.4 技能质量的三个评测层级技能化之后最舒服的一件事就是可以分层评测了。我现在每个迭代周期都会跑三类评测对应三个不同的关注点评测层级关注点评测方式最低达标线单技能正确性给定标准输入输出是否符合预期离线数据集 批量调用95%单技能鲁棒性面对边界和异常输入是否崩溃或产出垃圾模糊测试 边界用例85%组合链路成功率多技能串联后端到端任务完成率端到端任务模拟70%这三个层级对应的是不同的调试手段。单技能正确性出问题问题基本出在指令清晰度或实现逻辑鲁棒性出问题问题基本出在输入校验和异常处理组合链路出问题问题往往出在步骤衔接和状态管理。用这套分级方式我一看到测试报告就能定位到到底是哪一层出了问题不用再像最早那样“从一团乱麻中找线头”。另外评测数据集的维护是一个长期工作。每发现一个新失败案例我会第一时间把它加入对应技能的回归测试集。这个做法虽然简单但带来的稳定性提升非常显著。三个月下来我手里积累了上百个历史失败用例每一次新改动都可以立刻跑一遍回归确保修复了一个 bug 不会引发另一个隐藏问题。写在最后的实操体会从头梳理 agent-skills 这套做法我最深的感触是技能化的本质不是“把 prompt 拆成文件”而是重新思考 Agent 的能力组织方式。它把我的项目从“一个大 prompt 驱动所有行为”变成了“一个调度器 一组可插拔能力单元”调试难度和管理成本都下降了一个量级。最后分享一个亲测有效的经验在搭建技能体系初期不要急着写很多技能先用三个边界清晰的技能跑通完整链路然后逐渐增加。技能多到十几个之后真正的难点不再是写技能而是“如何让模型在正确的时机选择正确的技能”——那时候你会感谢自己早期养成的分层注册和路由设计习惯。