从零搭建Agent技能体系：结构、触发与迭代的skills实践-北京尧图网络

“skills”这个词最近在我本地的工作目录里出现得实在太频繁了。不管是Claude那边的SKILL.md还是Cursor里越分越细的能力卡片又或者自己用Agent框架时随手建的技能包“把能力下沉成文件”这件事正在快速取代过去那种在对话框里反复粘贴prompt的操作方式。这篇文章我想好好讲一次一个名为skills的目录到底该怎么从零搭起来才能让Agent真的用起来、用得好而不是变成一个落灰的Markdown仓库。内容围绕的是通用技能体系设计方法不绑定某个特定产品。我踩过的坑、反复改过的结构、最后沉淀下来的经验都会直接写出来。适合正在折腾Agent工作流、或者感觉提示词已经撑不住复杂任务的开发者参考。1. skills不是提示词仓库先想清楚它到底解决什么问题1.1 普通提示词的问题就出在“没有边界”如果你往一个系统提示里塞过三十条工作规范你一定会感觉到那种“说不上来哪里不对但模型就是在装傻”的体验。原因其实不复杂大模型对超长指令的注意力是会稀释的放在第15条的管理要求很可能还不如用户随手补的一句话权重高。而skills体系的出现本质上就是把长指令拆成一个个可以被按需加载的独立单元让它只在对应场景里进入上下文。这个区别很关键。普通的系统提示是“主机常驻内存”无论用户聊什么你都得让模型想着skills是“按需挂载”只有任务特征匹配到某个技能才会加载它的说明。我见过不少团队把“提示词工程”迁移成“技能工程”时只是把原来的长提示词塞进一个叫SKILL.md的文件里然后告诉自己“我已经用上技能体系了”。第一版我本人也这么干过效果一般。原因很简单技能文件最大的价值不是“内容换了个存放位置”而是触发机制、使用流程、结束条件和参考素材被结构化地组织起来了。1.2 Skills和普通文档的本质区别是“可执行”一份普通的设计规范文档模型读了之后能不能按规范干活能但效果极其不稳定。你最好还是每条都提醒它。而一份好的技能包至少要包含四个要素这个技能处理什么问题、它基于哪些方法论执行、它需要用户提供哪些必要信息、它完成时以什么格式输出。我习惯把它们叫做技能四要素。缺了任何一个技能包都会在使用中变形。举一个很实际的例子。我之前给团队知识库机器人写过一个“新员工入职问答”技能包。最初里面只有一段FAQ和“请根据知识库回答新员工问题”这句话。实际跑起来之后模型经常回答得太随性把不该给的内部系统账号细节也贴出来。后来我把输出边界写进技能明确规定“只输出可直接引用的文档链接和一句话结论涉及账号权限时只提示找IT支持”效果立刻稳定不少。所以skills目录不是用来存放知识的它更像是给Agent准备的一份“操作手册加工具箱”。2. 搭建技能目录一个可用体系的文件结构长什么样2.1 目录规范与命名约定我的基本单元是一个目录放一个技能包目录下至少有一份SKILL.md。整体结构大概是skills/ ├── code-review/ │ ├── SKILL.md │ ├── references/ │ │ └── review-checklist.md │ ├── scripts/ │ │ └── scan_for_todos.py │ └── examples/ │ └── before-after.md ├── meeting-minutes/ │ ├── SKILL.md │ └── templates/ └── incident-response/ ├── SKILL.md └── references/关于命名我的原则是用动词短语或明确的名词不用含糊的形容词。code-review、incident-response这种一看就知道什么时候用的名字比quality、best-practice这种强得多。后者看着很全面实际触发时模型根本不知道它该不该被调用。目录内部的文件排布也有讲究。SKILL.md必须放在技能包第一层references放不会频繁改动的参考资料scripts放可执行脚本或数据抽取逻辑examples放给模型看的少量示例。这里有个常见误区examples不是越多越好。放三五个足以说明输入输出形态的样例就好放多了只会稀释模型对主指令的注意力。2.2 SKILL.md的字段该怎么设计SKILL.md的编写是这套体系的核心。我不建议把它写成自由格式散文应该用带元信息的结构化格式。下面是我目前比较稳定的模板--- name: code-review description: 对指定目录中的代码提交进行逐文件评审 version: 1.2.0 when_to_use: 用户要求检查代码、Review MR/PR、或让AI检查提交前问题 tags: [code-review, qa, lint] --- ## 执行步骤 1. 确认目标代码路径或本次变更文件列表 2. 调用references/checklist.md中的检查项 3. 输出问题列表按阻塞/建议分类 ## 输出格式 - 阻塞问题文件路径、行号、原因、修改建议 - 建议问题文件路径、行号、说明、可选方案 - 无权访问的文件明确标出未检查 ## 边界 - 不修改代码除非用户明确要求生成diff - 不评审无意义的格式改动重点关注几个字段。description要能被模型用来做匹配建议写成“当用户想要X时使用”when_to_use更直白一些直接列举触发场景。version很重要因为技能会迭代没有版本号出了问题你都不知道是哪一版逻辑导致的。还有一个我自己习惯加的字段must_avoid。它用来告诉模型“这个技能不要做什么”。比如知识问答技能里我写的是“不要编造不存在的文章链接”。这个字段对控制模型行为非常有效效果不亚于正向指令。2.3 参考资料和脚本怎么跟主文件配合SKILL.md主文件最好保持在三百行以内太长了模型反而不容易抓住重点。复杂的方法细节放references目录需要计算或批处理的部分放scripts目录。举个例子我给“会议纪要”技能放了一个templates/meeting-notes.md模板SKILL.md里只写“按模板输出纪要”模板本身放在references里。这样主文件干净模型执行时又能拿到完整的格式约束。脚本的情况类似。写过一个“统计代码行变化”的脚本SKILL.md里只声明“调用scripts/diff_stats.py生成统计”并不把代码贴进主文件。脚本编写本身就是独立小工程优点是技能可以复用Shell能力和外部工具缺点是你要保证脚本在目标机器上能跑。如果你生成的技能包要给别人用脚本的跨平台性就一定不能忽视路径分隔符、依赖库版本这些细节都会成为隐藏炸弹。3. 触发与执行让模型在合适时机主动使用技能3.1 把when_to_use写得像行为特征而不是语义词汇模型判断该不该用某个技能靠的不是人类阅读后理解出的“这个领域相关”而是描述里的行为线索。所以when_to_use里我几乎不用“如果用户需要代码质量评估”这种话我会写“如果用户要求做Code Review、检查提交、评审MR/PR或让AI找代码里的bug”。行为化描述的好处是模型在推理时更容易匹配上具体动作。光是“代码质量”这个词可能匹配到优化建议、架构调整、静态扫描等多种意图但“检查提交”“评审MR/PR”这种动作词指向性就明确得多。我后来做了一次A/B测试同一个技能分别用两种风格的when_to_use去跑同样的评审请求。结果行为化描述的那一版触发率高了接近三成。触发这步做不好后面技能内容写得多精细都没用因为模型压根不会翻开这个文件。3.2 技能内部的状态约定调用中、完成、失败很多人写技能是从执行步骤直接跳到输出中间缺了一个状态约定。实际上技能在执行过程中会遇到各种意外用户给出了不完整信息、依赖的脚本报错、目标路径不存在。如果技能文件里不写这些情况的处理方式模型就会自己即兴发挥最常见的结果就是编造一个看似合理的输出。我的做法是在SKILL.md中显式定义三类状态正常完成按输出格式返回分析结果输入缺失列出需要用户补充的信息逐项询问执行失败说明失败的操作和原因给出备选方案比如改用人工确认这样不管环境怎么变化模型至少知道自己的输出边界。对生产环境来说稳定比聪明重要得多。3.3 召回测试如何确认技能真的会被触发这一节直接给操作路径。搭建完技能之后我建议立刻跑一遍召回测试而不是直接上线。做法是准备十个不同的用户请求覆盖面要广一半是明确命中场景一半是模糊边界场景在干净的会话里逐条发出观察模型是否加载并使用该技能检查哪些请求被漏掉回头修改when_to_use检查哪些请求被误触发收紧description描述这个过程通常要重复三轮以上才能稳定。我电脑上至今还保留着一份recall_test_cases.md里面记录了每个技能的测试用例和结果因为技能文件更新后原本能触发的场景可能因为措辞改动反而失灵回归测试是这玩意的保险栓。4. 进阶玩法技能的组合、版本管理和多项目复用4.1 用Git管技能记录“为什么改”技能文件的生命力在迭代迭代就必须有记录。我把整个skills目录做成独立仓库每个技能作为目录独立演进。提交信息里我会写清楚改了什么和为什么比如“在边界字段中禁止生成未经验证的链接——线上出现过一次幻觉”。一方面这能让你回滚到任何一个历史版本另一方面当Agent突然行为异常时你能准确判断是不是一次技能变更导致的。版本号管理我用的是语义化版本习惯主版本号在技能操作流程变更时增加次版本号在边界和细节调整时增加补丁号对应错别字或小修小补。虽然听起来有点工程化但多技能并存之后你会发现没有版本概念根本没法做对比分析。4.2 组合技能的三种模式单个技能解决单类问题真实业务往往是多类问题的组合。我总结过三种稳定的组合模式。顺序流水线模式前一个技能的输出直接作为后一个技能的输入。比如“日志分析”产出异常清单后自动接“故障定位”技能。父子依赖模式外部技能包只声明依赖某个基础技能基础技能提供公共工具函数或统一输出模板。条件分支模式根据用户请求的性质判断走哪个子技能路线。比如“代码相关请求”进入评审或修复分支“文档相关请求”进入总结或翻译分支。第三种模式实现起来最复杂需要在SKILL.md里定义清晰的分流判断条件。我的建议是别贪快先把顺序模式和父子模式用熟分支模式真的有必要再上。4.3 跨项目同步与灰度验证同一个技能会被多个项目复用这时候最怕的是“改了一个项目里的技能其他项目还是老版”。我的做法是用git submodule或独立的技能包目录进行多项目引用统一从技能仓库分发。分发之前要做灰度。道理和发版一样技能改动先在自己搭的测试环境里跑几天确认没有明显劣化再同步到全部项目。如果同步之后发现某个特定项目的上下文比较容易误触发就单独为它加一条上下文规则做减法。灰度验证时的指标我放在后面专门讲这里先记住一个关键原则技能改动必须视为代码变更不能当作文本润色来对待。5. 一二线实操中常见的坑skills目录是怎么变成垃圾场的5.1 排查“技能没生效”的完整链路技能没有生效的原因按我的经验出现频率从高到低排列如下when_to_use写得过于模糊模型认为当前场景不匹配技能被其他系统指令遮挡模型选择了另外的执行路径SKILL.md中的步骤互相矛盾导致执行中自行中断引用文件路径写错模型读不到references里的内容却仍然硬编排查的时候别上来就改SKILL.md里的正文描述。我自己的调试顺序是第一打开调试信息或让Agent自述当前执行计划看它到底有没有加载这个技能第二如果加载了但没照做检查执行步骤是否与环境实际能力匹配比如要求调用一个不存在的脚本第三如果没加载检查when_to_use与用户请求的语义距离把用户实际说的话原样贴到测试用例里跑一遍第四检查是否有更早加载的其他技能“抢占”了语境这四步走完绝大部分问题都能定位到具体环节。5.2 过封装、字段冲突、引用失效的处置经验你可能会觉得技能写得越细越好但实际上有一种症状特别典型技能文件越写越长执行反而越来越飘。因为它内部塞了大量“如果……那么……”的分支模型在长上下文推理时容易顾此失彼。我的约束是单技能SKILL.md不超过三百行步骤不超过七个。超过就要拆分子技能或把细节挪进references。字段冲突也值得提一嘴。我在一个项目里同时挂了“知识问答”和“信息检索”两个技能description高度相似模型几乎每次一遇到信息获取请求就随机选一个。解决方式是把知识问答改名为“内部wiki知识问答”明确限定它只在知识库检索时使用信息检索则改为“跨平台网络资源搜索工具”两个场景瞬间就分开了。引用失效是另一种常见坑。技能里引用的文档挪了位置SKILL.md里的相对路径就没更新。模型读不到材料又不想承认失败就开始靠记忆硬撑。解决办法说起来简单每次移动文件后全局跑一遍链接检查脚本。5.3 小心“技能幻觉”和过度自信最后一个坑是心理层面的。你搭好了十来个技能包每层都有模有样很容易产生“我的Agent已经很强了”的错觉。但技能文件本质上还是给模型看的文字模型没有真正理解技能背后的业务逻辑只是被instruction带着走。我曾经遇到过几次技能输出看起来很专业、但稍微对一眼源数据就发现完全对不上的情况。结论还是那句老话技能解决的问题边界一定要清晰超出边界时要允许它向用户说明“该场景超出我的技能范围”而不是硬着头皮生成一份貌似合理的废话。6. 我用真实失败案例驱动迭代的做法和一组观测指标6.1 从故障报告反推技能更新清单我维护技能的方式与其说是“定期复盘”不如说是“让事故来敲打”。只要线上出现一次错误输出我就整理一份故障记录包含用户请求原文、模型错误输出、期望输出、根因判断、需要改哪个技能字段。这个故障报告文件就是下一轮迭代的清单。技能不是凭感觉去优化的而是根据已知失败来逐个击破的。做得久了你会发现大部分技能问题不是发生在日常顺手的地方恰恰是那些“你怎么问它都不会出错”的边界情况。举一个真实故障有一次知识库机器人把一篇内部未发布计划的标题直接输出给了外部提问者。根因是技能里没有定义“未发布文档”的处理策略。我就在SKILL.md的must_avoid字段下加了一条“不要输出状态为草稿或未发布的文档内容”并在references里补充了一套可见度分级规则。之后再没出现过同类问题。6.2 可量化的几项指标衡量技能效果我所在的团队目前会采集这几项数据指标计算方法目标触发准确率正确触发次数 / 应触发次数≥ 90%错误输出率产生幻觉或错误信息次数 / 调用次数≤ 5%无效调用占比调用了但输出对用户无用的比例≤ 15%技能间冲突数两个及以上技能同时被触发且输出打架的次数降为0这些指标不需要专门搭建平台简单统计就能用。重点是让每个技能的变化都能收到反馈。一个技能改了跑一个月的调用数据触发率有没有提升错误率有没有下降数据比感觉可靠得多。6.3 写到最后技能目录的定位永远是“边学边改的活文档”“skills”最终长成什么样没有一个标准答案。我的经验是保持目录结构稳定、触发描述行为化、迭代靠故障数据驱动同时克制地控制单个技能的范围和长度。我不打算写一个完美的终极技能模板因为我知道下一周遇到新问题我又会往某个SKILL.md里加一条边界规则。构建技能体系这件事本质上就是持续整理你和模型协作之间的相处规则。每多一条规则Agent就多一分可靠。如果看完这篇你准备动手清理自己的skills目录我的建议是先做两件事检查所有技能的when_to_use是不是行为化描述把每个SKILL.md的版本号补上。剩下的等跑出真实数据再滚动迭代。

从零搭建Agent技能体系：结构、触发与迭代的skills实践

相关推荐

Paperclip文件上传实战：从模型绑定到对象存储迁移

本地图片去重与相似检索：感知哈希+CLIP特征向量实践

从零构建AI工程能力：Python、TypeScript、Rust三语言实战指南

更多资讯

Academic Figure Generator 实时进度指南：SSE 流式推送与异步后台任务实现

scipilot-figure-skill 数据剖析实战：用 profile_data.py 读懂你的实验数据

字符串匹配

深入pdfcn Registry机制：shadcn CLI如何用一条命令安装PDF组件

Adobe 软件安装提示msvcp110.dll 缺失怎么办？手把手教你搞定

【实战】STM32 ADC采集数据乱跳？从参考源选型到软件滤波的工程调优笔记（附HAL库完整代码）

今日更新

45个经典Linux面试题：从命令到网络排障的完整考点解析

SAP生产预留实战指南：MB21/MB23/MB25协同与MRP集成

编译原理实验：递归下降分析器消除左递归与避坑指南

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？