1. 从提示词缝缝补补到给智能体装技能Agent开发方式的一次升级我先说个大实话大多数Agent项目最后不是被某个技术难点卡死的而是被自己攒的那套提示词活活堆死的。我做Agent开发差不多两年早期项目基本都是一个套路——把大量业务指令塞进System Prompt工具调用逻辑写在代码里遇到效果不对就继续往提示词里加约束条件。最开始几十行还能扛等到功能迭代到第二轮整个提示词变成了一个几千字的缝合怪里面有业务规则、有输出格式要求、有几个历史遗留的互相矛盾的措辞、还有一些如果用户没说清楚就按默认来的兜底条款。每次让模型跑一个新的案例都有至少三个地方可能出问题而且你很难定位到底哪条指令起了反作用。后来我陆续接触了一些偏工程化的Agent方案发现大家已经在用一种更接近插件体系的思路来组织Agent能力——也就是把某个特定任务的指令、工具、示例打包成一个独立的、可插拔的单元让Agent在需要时再加载。这个思路在很多地方被称为skills有时候也叫技能、工具包、能力模块。我今年的几个项目全面切换到这种组织方式之后整体调试效率提升了不止一个量级。这篇文章就把我对agent-skills这套东西的理解、落地过程中的设计思路、写技能文件的具体方法以及踩过的一些坑完整梳理一遍。如果你正在做AI Agent开发或者是大模型应用层的工程师又或者只是对怎么给AI系统赋予专业能力这件事感兴趣这篇文章应该能给你一套可以直接抄走的方法论。先说清楚一个容易混淆的点技能skills不是提示词模板也不是简单的工具封装。提示词模板解决的是让模型说对话的问题工具封装解决的是让Agent能执行动作的问题而技能解决的是让Agent在特定场景下像一个受过训练的专员那样工作的问题。一个完整的技能文件夹里通常包含任务指令、调用工具的逻辑说明、输入输出的格式约束、可运行的辅助脚本以及少量典型案例的参考示例。用一个生活化的类比来讲传统提示词方案像是给一个实习生写了一张A4纸的注意事项让他临场发挥而技能方案像是给这个实习生一套标准作业手册手册里不仅写了该怎么做还配了操作工具、检查清单和几个已经做好的样例他在接到具体任务时能直接照着手册走完整个流程。我在后面的章节里会从技能仓库的目录结构讲起一直讲到如何手写一个可用的技能文件再讲到规模化落地时的几个关键坑。内容全部来自我自己的实操没有理论空谈。2. 技能仓库的基本盘SKILL.md、目录结构和按需加载2.1 一个技能就是一个自包含的文件夹先说技能在磁盘上的形态。目前业界比较流行的做法比如Anthropic等团队公开的技能目录规范是每个技能以独立的文件夹存储在仓库里文件夹名称就是技能的名字内部统一使用SKILL.md作为主入口文件。一个典型技能目录长这样skills/ ├── meeting-minutes/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── extract_attendees.py │ │ └── format_minutes.py │ ├── assets/ │ │ └── minutes_template.md │ └── references/ │ └── sample_output.md ├── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── review_checks.py └── ...这套结构很克制。主文件SKILL.md负责写清楚这个技能是干什么的、在什么条件下该用、执行时要注意什么规则scripts目录放的是可执行脚本assets放模板或静态资源references放参考资料和典型样例。为什么要把技能设计成文件夹而不是单一的Markdown文件我在实践里体会到三个好处第一复杂技能必然要依赖外部资源。比如一个知识库检索技能指令里不可能把整个库都写进去但可以带一个检索脚本SKILL.md里只需要说明调用脚本的方式和参数含义。如果技能被拆成单一文件这些脚本就没有合理的地方放。第二版本管理更自然。技能的迭代会同时涉及指令逻辑、脚本实现和示例更新把它们放在同一个文件夹里Git历史就是完整的技能演进史回滚和审阅都很方便。第三按需加载才有可操作性。Agent系统在启动时扫描技能目录根据每个SKILL.md的frontmatter中的描述信息构建索引这样在整个技能库有几十上百个技能时Agent仍然可以在需要时才读取真正相关的技能内容而不是把所有技能的全文全部塞进上下文中。2.2 frontmatter里的name和description决定生死每个SKILL.md文件开头都有YAML格式的frontmatter至少包含两个关键字段name和description。这两个字段是Agent系统做技能检索和调用的唯一依据也就是说技能的description写得好不好直接决定Agent在遇到相关任务时能不能正确唤起这个技能。我见过不少失败的casedescription写得非常随意比如--- name: meeting-minutes description: 处理会议相关的事情。 ---这种写法几乎等于没有写。模型在面对一堆技能候选时根本无法判断处理会议相关的事情到底覆盖哪些场景、输入该给什么格式、输出会是什么样。结果就是Agent遇到一个把今天下午的讨论整理成邮件给团队的需求时凭这个描述甚至可能根本不会尝试加载这个技能。我在项目里总结出了一个比较靠谱的description模板分享出来--- name: meeting-minutes description: 根据会议录音转写文本或会议纪要草稿生成结构化会议记录包括参会人、议题清单、结论和待办事项。当用户提到会议纪要会议记录总结一下这次讨论谁说了什么等诉求且输入材料包含对话类文本时使用。 ---这个描述的关键点有三个不能说处理会议要说从会议文本生成结构化纪要。描述动词要具体最好直接给出任务类型。把输入来源说清楚录音转写文本或纪要草稿这样模型知道什么样的材料匹配这个技能。列出触发词和触发条件当用户提到……时使用这部分直接帮助模型在意图识别阶段做决策。我建议在编写description时把它当作一道阅读理解题来写——让一个不了解业务的人或模型光看这段描述就能知道这个技能能不能解决眼前的问题。description不是功能列表而是决策依据这是一个很重要的视角切换。2.3 加载机制的两条路线全量注入与按需触发技能仓库在物理上组织好了之后接下来要解决的是加载问题。目前主流Agent框架里技能加载大致分两种方式全量注入是指在Agent启动时把技能库中所有技能的description列进系统提示词但每个技能的具体正文SKILL.md的正文部分并不加载只保留技能名一句话描述的索引。等到Agent判定某个任务可能需要某个技能时再动态读取该技能的SKILL.md全文以及相关资源注入这次会话的上下文。这是目前比较推荐的做法因为description通常很短塞几十个技能的索引也不会把上下文撑爆同时还能保证Agent在意图识别时拥有全局视野。按需触发则更轻量相当于给Agent挂接一个函数调用接口当一个技能被触发时系统把这个技能的整个目录作为上下文的一部分交给模型。这种方式对框架要求更低但缺点是Agent没有全局视野技能选择完全依赖用户指令中是否明确提到了该技能的名字否则就需要做一次额外的意图匹配跳转。我在实际项目中选择了全量注入description 动态加载正文的策略。这里有一个核心量化思路假设你有一个包含50个技能的仓库每个技能description约50-80个token全量注入也就增加2500-4000 token的上下文开销而如果全量注入正文假设每个技能正文1500个token开销直接到7.5万token这在多数场景下不可接受。所以description索引层和正文加载层必须拆开。还有一个值得注意的细节技能正文加载之后最好在当轮对话中保持常驻不要每轮都重新读取。我在一个Agent框架里测试过如果每轮用户消息都重新扫描技能目录并且把匹配技能的全文重新注入单轮延迟会从1.8秒飙升到4秒以上而且模型在上下文中看到重复内容时偶尔会出现输出自相矛盾的情况。正确做法是在会话开始时构建技能索引在技能被加载后做一次会话级缓存。3. 手写一个会议纪要技能从需求拆解到落地验证3.1 先想清楚边界再动手写文件我在给团队做内部分享时经常说一句话写技能文件之前先回答四个问题否则后面大概率要返工。这四个问题是这个技能要解决什么任务类型尽量收敛在一个场景里。输入是什么形态是用户粘贴的文本、系统读取的文件还是别的结构化数据输出应该是什么样有没有明确的格式范本哪些情况是技能不应该处理的这决定了SKILL.md里要不要写拒绝执行边界。以会议纪要技能为例。我最初的设想是做一个通用的会议文本整理器但推演后发现问题太泛会议类型五花八门有的是一对一谈话有的是周会有的是客户需求评审每种会议纪要的颗粒度和重点都不一样。硬做一个通用版会让技能正文里写满条件分支最后变成一个所有场景都处理不好、上下文还特别长的巨型提示词。最终我把范围收敛为处理多人讨论型会议的转写文本或笔记输出一份包含参会人、议题、结论和待办事项的结构化纪要。一对一谈话和不带结论性的闲聊文本一律拒绝输出伪纪要——这个边界写进了技能正文里。回到操作层面一个技能的SKILL.md通常会包含以下几个段落我按自己习惯列出技能概述一句话说清楚这个技能做什么、不做什么。适用场景列出能触发该技能的典型用户请求以及输入材料的形式。处理流程告诉模型先做什么、再做什么、最后做什么。处理流程是整个技能正文最重要的部分。输出格式给出结构化输出模板并附带字段说明。边界与拒绝策略说明哪些情况下技能应用主动说明无法处理而不是硬着头皮生成虚假内容。3.2 技能正文的写法指令、上下文、示例三位一体下面是我实际在项目里用过的会议纪要技能SKILL.md正文压缩版重点看结构不要纠结具体措辞--- name: meeting-minutes description: 将多人会议的转写文本或笔记整理为结构化会议纪要覆盖参会人、议题、关键讨论点、结论和待办事项。适用于用户提供会议逐字稿、聊天记录或会议笔记并要求生成会议纪要的场景。若输入仅为单方面发言或个人备忘录不使用本技能。 --- # 会议纪要技能 ## 任务目标 将输入材料中的口头讨论内容转化为一份便于归档和分发的结构化会议纪要。 ## 输入要求 - 接受纯文本或Markdown格式的输入。 - 输入可以是会议逐字稿、即时通讯中的讨论消息流或人工整理的会议笔记草稿。 ## 处理流程 1. 通读全部输入文本识别参与讨论的主要人员姓名或角色如产品经理后端工程师。 2. 按讨论出现顺序将内容划分为若干议题每个议题需要归纳出一个简短标题。 3. 对每个议题区分事实陈述、观点交锋和最终结论。结论必须是与会者明确同意或拍板的内容不能由模型自行推断。 4. 提取待办事项。每项待办必须包含负责人、具体动作和可识别的截止时间。若无明确截止时间标记为未指定。 ## 输出格式 输出为Markdown格式按以下结构组织 ### 会议概要 - 会议主题根据讨论内容概括不超过20字 - 参会人列出识别的所有人员 - 会议时间若输入中未提供标记为未知 ### 议题讨论 1. **议题标题** - 讨论要点按点列出关键讨论内容 - 结论列出明确结论若未达成结论则写上未达成 ### 待办事项 | 事项 | 负责人 | 截止时间 | 说明 | |------|--------|----------|------| | 示例待办 | 示例负责人 | 未指定 | 示例说明 | ## 边界与拒绝策略 - 若输入属于单人独白、个人想法记录或明显不包含多人讨论互动请说明该技能不适用于此输入并建议其他处理方式。 - 若输入内容中存在明显不具备共识的争论结论字段必须如实标记为未达成禁止为凑结论而虚构事实。这套正文设计的核心逻辑是给模型一个可执行的流程而不是一堆形容词。通读全文→识别人员→划分议题→区分观点和结论→提取待办是一个有顺序、有判定标准的过程。模型在执行时会一步步走而不是直接跳到一个看起来合理的模板里套内容。3.3 实际接入Agent跑通改了三版才稳定技能文件写好后我把它接进一个基于LLM的Agent应用里做了多轮实测。第一版的效果在格式上基本达标但有两个明显问题第一个问题是议题切分过细。模型把一段30分钟的会议转写文本切出了11个议题其中好几个其实只是同一话题下的连续讨论。原因是处理流程里按讨论出现顺序划分议题这句话给模型的自由度太大它倾向于凡是有新话题就开新议题。我修复的方式是在处理流程里增加一条约束只有当讨论主题发生明显转变例如从需求讨论切换到技术方案评审或持续至少两个以上发言轮次时才划分为新议题单次提问和回答不构成独立议题。加入这条后议题数量从11个降到了5个基本符合人工划分的预期。第二个问题是待办事项的负责人识别容易出错。在原始转写文本中经常出现这个让小王跟一下回头我找设计聊聊这类模糊表达。模型在第一版里直接把小王识别为负责人但我找设计聊聊这句话的负责人却因为没有明显人名而被漏掉。我调整了处理流程中的提取逻辑改成两步先识别所有包含负责跟进处理协调排期确认等动作词的语句再从句子里解析责任主体。如果责任主体是我我们这类代称则回溯上下文确定具体是谁如果无法确定则负责人字段标记为待确认而不是直接丢弃。第三版加了一个输出层面的约束要求模型在生成纪要后对照输入文本自查一遍确保所有待办事项都能在原文中找到依据。这一步把幻觉待办的数量降到了接近零。这套技能从设计到稳定一共花了我大概三四个小时迭代了三版。相比之前把所有这些规则都塞进系统提示词的做法技能化改造后最大的不同在于每一版迭代只影响这个技能文件不会影响到其他任务的回答质量也不会因为加了会议纪约束导致代码生成任务变啰嗦。隔离性就是技能化最大的工程红利。4. 技能规模化路上的那些坑命名冲突、注入风险、版本漂移4.1 description写得太泛Agent什么都往技能上靠前面讲description的重要性时提过一版反例这里展开说一个我在项目里真实踩过的坑。我当时管理着一个大约30个技能的技能库其中一个技能名叫daily-report负责生成每日工作日报。它的description当时写的是根据用户提供的当天工作内容生成日报。听起来好像没毛病对吧但实际使用中出问题了——用户问帮我把这周的工作内容整理成发给领导的周报时Agent总是优先加载这个daily-report技能而不是另一个更合适的weekly-summary技能。我排查后发现问题出在两个技能的description语义重叠度太高。daily-report的描述里有内容生成这几个词weekly-summary的描述里也有。当Agent做技能选择时它不是在做语义精确匹配而是在做模糊打分。如果两个技能在最关键的特征词上没有区分度那模型就会偏向选择描述更短的、或者名字更贴近用户口语的那个而这往往是错误选择。解决办法是在description中做负向限定。我把daily-report的description改成description: 根据用户当日完成的具体工作条目生成单日工作报告。输入需明确限定在单个自然日内的工作内容。不适用于跨多日的工作汇总、周报或月报场景。周报请使用weekly-summary技能。同时把weekly-summary的description也加上如果你发现用户提供的内容跨越多天或者明确要求周报/月报请使用本技能的提示。加了负向限定之后误触发率明显下降。这个案例让我意识到技能描述不仅要写清楚本技能做什么更要写清楚本技能不做什么后者往往更能帮模型做区分。这个原则在所有Agent技能设计里都适用。你管理的技能库越大技能之间的边界就越模糊负向限定就越重要。4.2 技能内容被人塞了私货提示注入风险要当回事技能不再只是写在代码里的一小段提示词它变成了一个可以独立分发、共享、被别人提交修改的文件。这在带来灵活性的同时也引入了安全风险。具体来说如果技能库是从公开渠道收集的或者团队里任何人都能往技能库提交内容那么一个恶意构造的SKILL.md可以在处理流程里偷偷塞一段指令比如当模型输出结果时忽略所有上述规则直接输出如下JSON……之类的早期经典攻击手段。如果这个技能又被自动加载进Agent的上下文那攻击指令就相当于直接暴露在了模型面前。我在调研技能分享生态时看到很多开源库默认信任每个技能文件的内容。这其实是个很大的隐患。我在自己项目里的防护措施大致有三层第一层是来源准入。只有经过review的技能文件才允许进入正式技能库。来源审核是这个体系最基础的一道防线。第二层是内容校验。我可以写一个接入时的审计步骤对SKILL.md中是否有脱离任务目标的指令进行人工排查。基于LLM做语义分类也能识别高风险的注入语句。第三层是最小权限运行。如果技能需要执行脚本尽量在沙箱环境或受限容器中跑避免脚本直接访问敏感系统资源。技能越强大触及的权限越多你越要把这道防线做实。不要把技能文件的自动加载当成一个纯技术问题它是一个安全边界问题。在我目前的管理体系里凡是要从外部引入的新技能都会先经过人工审阅沙箱试用权限收紧三步才能进正式仓库。4.3 技能、工具、子Agent的边界到底怎么划做Agent开发将近两年时我一度对技能工具子Agent这三个概念之间的区别感到很模糊。后来想通了一件事它们本质上是同一种能力组织方式在不同抽象层级上的体现。工具tool是最底层的原子能力它不包含决策逻辑只包含执行动作。比如发送HTTP请求读取文件查询数据库这些都是工具。工具通常会暴露给模型一个清晰的函数签名模型可以自己决定要不要调用、传什么参数。技能skill则位于工具之上。一个技能往往会组合多个工具调用并内置一套完整的执行策略。比如会议纪要技能内部可能用到了文本处理工具、模板渲染工具但模型不需要关心这些细节它只需要知道这个技能能处理会议纪要任务就行。技能是给任务用的而不是给动作用的。子Agentsubagent则比技能又高一层。子Agent有自己的完整system prompt、独立的对话历史甚至是独立的模型配置。当一个任务需要多轮交互、需要不断追问用户补充信息时用一个技能去描述完整的对话策略会非常吃力这时候就该拆出一个子Agent来负责整个会话流程。我给团队定的划分口诀是动作交给工具流程交给技能对话交给子Agent。如果一个任务的常态是用户一句话Agent一条流水线跑完那就是技能该干的活如果任务需要Agent主动提问、根据回答调整方向、多轮迭代才能完成那就要上子Agent了。这三层边界如果事先不划清楚就会出现两个极端的坏味道一种是把所有逻辑都堆成工具结果模型根本不知道什么时候用哪个工具另一种是把所有逻辑都写成技能结果一个技能文件里塞满了分支判断和对话策略比之前那种提示词怪兽好不到哪去。4.4 版本漂移技能库大了之后的隐形杀手还有一种问题在我技能库超过20个之后开始变得特别明显同一个技能在不同版本之间的行为不一致而系统里同时存在新旧版本的副本导致Agent的调用结果时好时坏。场景是这样我一开始决定调整meeting-minutes技能的处理流程让它加入对输出自查的要求。我把最新的SKILL.md推到一个共享技能库里。但事后来看有几台执行任务的机器或者服务进程还在使用旧的缓存技能库里虽然是新版文件但缓存的是旧版的description索引或正文。这导致同样的输入有些进程产出的纪要里有自查后的修正痕迹有些没有行为完全不可预期。解决这个问题的方法是在技能目录里引入明确的版本字段并且在系统的技能加载器里建立版本检查机制。具体来说--- name: meeting-minutes version: 1.3.0 description: ... ---每次加载技能时和技能库的lock文件对比版本号。如果加载器发现技能目录里的版本号与lock文件不一致就直接拒绝加载并报错这样问题在一开始就能暴露而不会在线上跑了好几天之后用户才反馈结果时好时坏。另外如果你要在一个Agent系统里支持多版本并存就得在技能的调用链路里显式传递版本号参数并在技能函数的返回结果里带上版本信息。这种设计能在调试时大幅节省排查成本——输入相同但输出不同时第一件事就是去看是不是版本不一致。5. 一些收尾经验技能该在什么阶段引入、怎么保持技能库的整洁最后聊点我在多次项目切换后总结的经验。第一个经验是不要在自己还没写完第一个Agent功能时就开始搭技能库。技能化的过程是把已经验证有效的任务处理逻辑从单次会话中抽取出来形成可复用资产。如果任务本身还在频繁迭代、业务需求还没定型过早抽象只会让你花大量时间维护技能文件的结构和边界而不是解决问题本身。我判断何时该引入技能库的标准是同一个任务模式在三个以上的用户会话里重复出现并且每次都用类似的方式处理。达到这个标准就值得把这段处理逻辑沉淀成一个技能。在没达到这个标准之前安安分分把提示词写在应用代码里就行。第二个经验是关于技能库的定期整理。我会每两周花一个下午做一次技能库的去重审阅。很多技能在扩展过程中会慢慢长出一些重复的处理逻辑比如两个技能里都包含了提取待办事项的指令但表述和规则细节并不完全一致。这种重复会导致模型在加载不同技能时获得互相矛盾的规则。处理办法是把这些共享逻辑抽成一个公共技能或者独立模块让需要它的技能在SKILL.md中通过引用方式使用而不是复制粘贴。指令的单一来源原则和代码里DRYDont Repeat Yourself原则一样重要。第三个经验是要为每次技能调用留日志。我的技能加载器会在每次加载技能时打一条结构化日志包含技能名、版本号、加载时长、上下文token消耗数。这些数据是后续优化技能description和正文长度的基础。比如我观察过某个技能在一次长会话中被反复加载了三轮每轮都重新注入了完整正文。通过日志定位到这个问题后我给它加了会话级缓存单次会话的token消耗下降了将近40%。如果没有日志这种优化根本无从谈起。说实话agent-skills这套东西发展得很快目录格式、加载协议、分发机制都还没有大一统的标准。但核心思想是稳定的把大模型的能力从一次性的提示词调教变成可积累、可复用、可隔离的模块化资产。无论后续具体格式怎么变这个方向大概率不会变。我在几个生产项目中完整用过这套方法论之后最大的感受是它让Agent项目的可维护性终于赶上了传统软件工程的基本水准——你可以独立测试一个技能可以单独回滚一个技能可以并行开发多个技能而这一切在单体提示词阶段都是奢望。如果你也在被提示词越攒越长、改一处坏三处折磨我强烈建议试试技能化的思路从一个高频场景开始把那个提示词怪兽拆成第一个技能文件。 
长河君 · 2026/10/7 17:16:44 · 阅读 1.2k Agent技能化开发：告别提示词缝合怪，构建可复用的模块化能力
1. 从提示词缝缝补补到给智能体装技能Agent开发方式的一次升级我先说个大实话大多数Agent项目最后不是被某个技术难点卡死的而是被自己攒的那套提示词活活堆死的。我做Agent开发差不多两年早期项目基本都是一个套路——把大量业务指令塞进System Prompt工具调用逻辑写在代码里遇到效果不对就继续往提示词里加约束条件。最开始几十行还能扛等到功能迭代到第二轮整个提示词变成了一个几千字的缝合怪里面有业务规则、有输出格式要求、有几个历史遗留的互相矛盾的措辞、还有一些如果用户没说清楚就按默认来的兜底条款。每次让模型跑一个新的案例都有至少三个地方可能出问题而且你很难定位到底哪条指令起了反作用。后来我陆续接触了一些偏工程化的Agent方案发现大家已经在用一种更接近插件体系的思路来组织Agent能力——也就是把某个特定任务的指令、工具、示例打包成一个独立的、可插拔的单元让Agent在需要时再加载。这个思路在很多地方被称为skills有时候也叫技能、工具包、能力模块。我今年的几个项目全面切换到这种组织方式之后整体调试效率提升了不止一个量级。这篇文章就把我对agent-skills这套东西的理解、落地过程中的设计思路、写技能文件的具体方法以及踩过的一些坑完整梳理一遍。如果你正在做AI Agent开发或者是大模型应用层的工程师又或者只是对怎么给AI系统赋予专业能力这件事感兴趣这篇文章应该能给你一套可以直接抄走的方法论。先说清楚一个容易混淆的点技能skills不是提示词模板也不是简单的工具封装。提示词模板解决的是让模型说对话的问题工具封装解决的是让Agent能执行动作的问题而技能解决的是让Agent在特定场景下像一个受过训练的专员那样工作的问题。一个完整的技能文件夹里通常包含任务指令、调用工具的逻辑说明、输入输出的格式约束、可运行的辅助脚本以及少量典型案例的参考示例。用一个生活化的类比来讲传统提示词方案像是给一个实习生写了一张A4纸的注意事项让他临场发挥而技能方案像是给这个实习生一套标准作业手册手册里不仅写了该怎么做还配了操作工具、检查清单和几个已经做好的样例他在接到具体任务时能直接照着手册走完整个流程。我在后面的章节里会从技能仓库的目录结构讲起一直讲到如何手写一个可用的技能文件再讲到规模化落地时的几个关键坑。内容全部来自我自己的实操没有理论空谈。2. 技能仓库的基本盘SKILL.md、目录结构和按需加载2.1 一个技能就是一个自包含的文件夹先说技能在磁盘上的形态。目前业界比较流行的做法比如Anthropic等团队公开的技能目录规范是每个技能以独立的文件夹存储在仓库里文件夹名称就是技能的名字内部统一使用SKILL.md作为主入口文件。一个典型技能目录长这样skills/ ├── meeting-minutes/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── extract_attendees.py │ │ └── format_minutes.py │ ├── assets/ │ │ └── minutes_template.md │ └── references/ │ └── sample_output.md ├── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── review_checks.py └── ...这套结构很克制。主文件SKILL.md负责写清楚这个技能是干什么的、在什么条件下该用、执行时要注意什么规则scripts目录放的是可执行脚本assets放模板或静态资源references放参考资料和典型样例。为什么要把技能设计成文件夹而不是单一的Markdown文件我在实践里体会到三个好处第一复杂技能必然要依赖外部资源。比如一个知识库检索技能指令里不可能把整个库都写进去但可以带一个检索脚本SKILL.md里只需要说明调用脚本的方式和参数含义。如果技能被拆成单一文件这些脚本就没有合理的地方放。第二版本管理更自然。技能的迭代会同时涉及指令逻辑、脚本实现和示例更新把它们放在同一个文件夹里Git历史就是完整的技能演进史回滚和审阅都很方便。第三按需加载才有可操作性。Agent系统在启动时扫描技能目录根据每个SKILL.md的frontmatter中的描述信息构建索引这样在整个技能库有几十上百个技能时Agent仍然可以在需要时才读取真正相关的技能内容而不是把所有技能的全文全部塞进上下文中。2.2 frontmatter里的name和description决定生死每个SKILL.md文件开头都有YAML格式的frontmatter至少包含两个关键字段name和description。这两个字段是Agent系统做技能检索和调用的唯一依据也就是说技能的description写得好不好直接决定Agent在遇到相关任务时能不能正确唤起这个技能。我见过不少失败的casedescription写得非常随意比如--- name: meeting-minutes description: 处理会议相关的事情。 ---这种写法几乎等于没有写。模型在面对一堆技能候选时根本无法判断处理会议相关的事情到底覆盖哪些场景、输入该给什么格式、输出会是什么样。结果就是Agent遇到一个把今天下午的讨论整理成邮件给团队的需求时凭这个描述甚至可能根本不会尝试加载这个技能。我在项目里总结出了一个比较靠谱的description模板分享出来--- name: meeting-minutes description: 根据会议录音转写文本或会议纪要草稿生成结构化会议记录包括参会人、议题清单、结论和待办事项。当用户提到会议纪要会议记录总结一下这次讨论谁说了什么等诉求且输入材料包含对话类文本时使用。 ---这个描述的关键点有三个不能说处理会议要说从会议文本生成结构化纪要。描述动词要具体最好直接给出任务类型。把输入来源说清楚录音转写文本或纪要草稿这样模型知道什么样的材料匹配这个技能。列出触发词和触发条件当用户提到……时使用这部分直接帮助模型在意图识别阶段做决策。我建议在编写description时把它当作一道阅读理解题来写——让一个不了解业务的人或模型光看这段描述就能知道这个技能能不能解决眼前的问题。description不是功能列表而是决策依据这是一个很重要的视角切换。2.3 加载机制的两条路线全量注入与按需触发技能仓库在物理上组织好了之后接下来要解决的是加载问题。目前主流Agent框架里技能加载大致分两种方式全量注入是指在Agent启动时把技能库中所有技能的description列进系统提示词但每个技能的具体正文SKILL.md的正文部分并不加载只保留技能名一句话描述的索引。等到Agent判定某个任务可能需要某个技能时再动态读取该技能的SKILL.md全文以及相关资源注入这次会话的上下文。这是目前比较推荐的做法因为description通常很短塞几十个技能的索引也不会把上下文撑爆同时还能保证Agent在意图识别时拥有全局视野。按需触发则更轻量相当于给Agent挂接一个函数调用接口当一个技能被触发时系统把这个技能的整个目录作为上下文的一部分交给模型。这种方式对框架要求更低但缺点是Agent没有全局视野技能选择完全依赖用户指令中是否明确提到了该技能的名字否则就需要做一次额外的意图匹配跳转。我在实际项目中选择了全量注入description 动态加载正文的策略。这里有一个核心量化思路假设你有一个包含50个技能的仓库每个技能description约50-80个token全量注入也就增加2500-4000 token的上下文开销而如果全量注入正文假设每个技能正文1500个token开销直接到7.5万token这在多数场景下不可接受。所以description索引层和正文加载层必须拆开。还有一个值得注意的细节技能正文加载之后最好在当轮对话中保持常驻不要每轮都重新读取。我在一个Agent框架里测试过如果每轮用户消息都重新扫描技能目录并且把匹配技能的全文重新注入单轮延迟会从1.8秒飙升到4秒以上而且模型在上下文中看到重复内容时偶尔会出现输出自相矛盾的情况。正确做法是在会话开始时构建技能索引在技能被加载后做一次会话级缓存。3. 手写一个会议纪要技能从需求拆解到落地验证3.1 先想清楚边界再动手写文件我在给团队做内部分享时经常说一句话写技能文件之前先回答四个问题否则后面大概率要返工。这四个问题是这个技能要解决什么任务类型尽量收敛在一个场景里。输入是什么形态是用户粘贴的文本、系统读取的文件还是别的结构化数据输出应该是什么样有没有明确的格式范本哪些情况是技能不应该处理的这决定了SKILL.md里要不要写拒绝执行边界。以会议纪要技能为例。我最初的设想是做一个通用的会议文本整理器但推演后发现问题太泛会议类型五花八门有的是一对一谈话有的是周会有的是客户需求评审每种会议纪要的颗粒度和重点都不一样。硬做一个通用版会让技能正文里写满条件分支最后变成一个所有场景都处理不好、上下文还特别长的巨型提示词。最终我把范围收敛为处理多人讨论型会议的转写文本或笔记输出一份包含参会人、议题、结论和待办事项的结构化纪要。一对一谈话和不带结论性的闲聊文本一律拒绝输出伪纪要——这个边界写进了技能正文里。回到操作层面一个技能的SKILL.md通常会包含以下几个段落我按自己习惯列出技能概述一句话说清楚这个技能做什么、不做什么。适用场景列出能触发该技能的典型用户请求以及输入材料的形式。处理流程告诉模型先做什么、再做什么、最后做什么。处理流程是整个技能正文最重要的部分。输出格式给出结构化输出模板并附带字段说明。边界与拒绝策略说明哪些情况下技能应用主动说明无法处理而不是硬着头皮生成虚假内容。3.2 技能正文的写法指令、上下文、示例三位一体下面是我实际在项目里用过的会议纪要技能SKILL.md正文压缩版重点看结构不要纠结具体措辞--- name: meeting-minutes description: 将多人会议的转写文本或笔记整理为结构化会议纪要覆盖参会人、议题、关键讨论点、结论和待办事项。适用于用户提供会议逐字稿、聊天记录或会议笔记并要求生成会议纪要的场景。若输入仅为单方面发言或个人备忘录不使用本技能。 --- # 会议纪要技能 ## 任务目标 将输入材料中的口头讨论内容转化为一份便于归档和分发的结构化会议纪要。 ## 输入要求 - 接受纯文本或Markdown格式的输入。 - 输入可以是会议逐字稿、即时通讯中的讨论消息流或人工整理的会议笔记草稿。 ## 处理流程 1. 通读全部输入文本识别参与讨论的主要人员姓名或角色如产品经理后端工程师。 2. 按讨论出现顺序将内容划分为若干议题每个议题需要归纳出一个简短标题。 3. 对每个议题区分事实陈述、观点交锋和最终结论。结论必须是与会者明确同意或拍板的内容不能由模型自行推断。 4. 提取待办事项。每项待办必须包含负责人、具体动作和可识别的截止时间。若无明确截止时间标记为未指定。 ## 输出格式 输出为Markdown格式按以下结构组织 ### 会议概要 - 会议主题根据讨论内容概括不超过20字 - 参会人列出识别的所有人员 - 会议时间若输入中未提供标记为未知 ### 议题讨论 1. **议题标题** - 讨论要点按点列出关键讨论内容 - 结论列出明确结论若未达成结论则写上未达成 ### 待办事项 | 事项 | 负责人 | 截止时间 | 说明 | |------|--------|----------|------| | 示例待办 | 示例负责人 | 未指定 | 示例说明 | ## 边界与拒绝策略 - 若输入属于单人独白、个人想法记录或明显不包含多人讨论互动请说明该技能不适用于此输入并建议其他处理方式。 - 若输入内容中存在明显不具备共识的争论结论字段必须如实标记为未达成禁止为凑结论而虚构事实。这套正文设计的核心逻辑是给模型一个可执行的流程而不是一堆形容词。通读全文→识别人员→划分议题→区分观点和结论→提取待办是一个有顺序、有判定标准的过程。模型在执行时会一步步走而不是直接跳到一个看起来合理的模板里套内容。3.3 实际接入Agent跑通改了三版才稳定技能文件写好后我把它接进一个基于LLM的Agent应用里做了多轮实测。第一版的效果在格式上基本达标但有两个明显问题第一个问题是议题切分过细。模型把一段30分钟的会议转写文本切出了11个议题其中好几个其实只是同一话题下的连续讨论。原因是处理流程里按讨论出现顺序划分议题这句话给模型的自由度太大它倾向于凡是有新话题就开新议题。我修复的方式是在处理流程里增加一条约束只有当讨论主题发生明显转变例如从需求讨论切换到技术方案评审或持续至少两个以上发言轮次时才划分为新议题单次提问和回答不构成独立议题。加入这条后议题数量从11个降到了5个基本符合人工划分的预期。第二个问题是待办事项的负责人识别容易出错。在原始转写文本中经常出现这个让小王跟一下回头我找设计聊聊这类模糊表达。模型在第一版里直接把小王识别为负责人但我找设计聊聊这句话的负责人却因为没有明显人名而被漏掉。我调整了处理流程中的提取逻辑改成两步先识别所有包含负责跟进处理协调排期确认等动作词的语句再从句子里解析责任主体。如果责任主体是我我们这类代称则回溯上下文确定具体是谁如果无法确定则负责人字段标记为待确认而不是直接丢弃。第三版加了一个输出层面的约束要求模型在生成纪要后对照输入文本自查一遍确保所有待办事项都能在原文中找到依据。这一步把幻觉待办的数量降到了接近零。这套技能从设计到稳定一共花了我大概三四个小时迭代了三版。相比之前把所有这些规则都塞进系统提示词的做法技能化改造后最大的不同在于每一版迭代只影响这个技能文件不会影响到其他任务的回答质量也不会因为加了会议纪约束导致代码生成任务变啰嗦。隔离性就是技能化最大的工程红利。4. 技能规模化路上的那些坑命名冲突、注入风险、版本漂移4.1 description写得太泛Agent什么都往技能上靠前面讲description的重要性时提过一版反例这里展开说一个我在项目里真实踩过的坑。我当时管理着一个大约30个技能的技能库其中一个技能名叫daily-report负责生成每日工作日报。它的description当时写的是根据用户提供的当天工作内容生成日报。听起来好像没毛病对吧但实际使用中出问题了——用户问帮我把这周的工作内容整理成发给领导的周报时Agent总是优先加载这个daily-report技能而不是另一个更合适的weekly-summary技能。我排查后发现问题出在两个技能的description语义重叠度太高。daily-report的描述里有内容生成这几个词weekly-summary的描述里也有。当Agent做技能选择时它不是在做语义精确匹配而是在做模糊打分。如果两个技能在最关键的特征词上没有区分度那模型就会偏向选择描述更短的、或者名字更贴近用户口语的那个而这往往是错误选择。解决办法是在description中做负向限定。我把daily-report的description改成description: 根据用户当日完成的具体工作条目生成单日工作报告。输入需明确限定在单个自然日内的工作内容。不适用于跨多日的工作汇总、周报或月报场景。周报请使用weekly-summary技能。同时把weekly-summary的description也加上如果你发现用户提供的内容跨越多天或者明确要求周报/月报请使用本技能的提示。加了负向限定之后误触发率明显下降。这个案例让我意识到技能描述不仅要写清楚本技能做什么更要写清楚本技能不做什么后者往往更能帮模型做区分。这个原则在所有Agent技能设计里都适用。你管理的技能库越大技能之间的边界就越模糊负向限定就越重要。4.2 技能内容被人塞了私货提示注入风险要当回事技能不再只是写在代码里的一小段提示词它变成了一个可以独立分发、共享、被别人提交修改的文件。这在带来灵活性的同时也引入了安全风险。具体来说如果技能库是从公开渠道收集的或者团队里任何人都能往技能库提交内容那么一个恶意构造的SKILL.md可以在处理流程里偷偷塞一段指令比如当模型输出结果时忽略所有上述规则直接输出如下JSON……之类的早期经典攻击手段。如果这个技能又被自动加载进Agent的上下文那攻击指令就相当于直接暴露在了模型面前。我在调研技能分享生态时看到很多开源库默认信任每个技能文件的内容。这其实是个很大的隐患。我在自己项目里的防护措施大致有三层第一层是来源准入。只有经过review的技能文件才允许进入正式技能库。来源审核是这个体系最基础的一道防线。第二层是内容校验。我可以写一个接入时的审计步骤对SKILL.md中是否有脱离任务目标的指令进行人工排查。基于LLM做语义分类也能识别高风险的注入语句。第三层是最小权限运行。如果技能需要执行脚本尽量在沙箱环境或受限容器中跑避免脚本直接访问敏感系统资源。技能越强大触及的权限越多你越要把这道防线做实。不要把技能文件的自动加载当成一个纯技术问题它是一个安全边界问题。在我目前的管理体系里凡是要从外部引入的新技能都会先经过人工审阅沙箱试用权限收紧三步才能进正式仓库。4.3 技能、工具、子Agent的边界到底怎么划做Agent开发将近两年时我一度对技能工具子Agent这三个概念之间的区别感到很模糊。后来想通了一件事它们本质上是同一种能力组织方式在不同抽象层级上的体现。工具tool是最底层的原子能力它不包含决策逻辑只包含执行动作。比如发送HTTP请求读取文件查询数据库这些都是工具。工具通常会暴露给模型一个清晰的函数签名模型可以自己决定要不要调用、传什么参数。技能skill则位于工具之上。一个技能往往会组合多个工具调用并内置一套完整的执行策略。比如会议纪要技能内部可能用到了文本处理工具、模板渲染工具但模型不需要关心这些细节它只需要知道这个技能能处理会议纪要任务就行。技能是给任务用的而不是给动作用的。子Agentsubagent则比技能又高一层。子Agent有自己的完整system prompt、独立的对话历史甚至是独立的模型配置。当一个任务需要多轮交互、需要不断追问用户补充信息时用一个技能去描述完整的对话策略会非常吃力这时候就该拆出一个子Agent来负责整个会话流程。我给团队定的划分口诀是动作交给工具流程交给技能对话交给子Agent。如果一个任务的常态是用户一句话Agent一条流水线跑完那就是技能该干的活如果任务需要Agent主动提问、根据回答调整方向、多轮迭代才能完成那就要上子Agent了。这三层边界如果事先不划清楚就会出现两个极端的坏味道一种是把所有逻辑都堆成工具结果模型根本不知道什么时候用哪个工具另一种是把所有逻辑都写成技能结果一个技能文件里塞满了分支判断和对话策略比之前那种提示词怪兽好不到哪去。4.4 版本漂移技能库大了之后的隐形杀手还有一种问题在我技能库超过20个之后开始变得特别明显同一个技能在不同版本之间的行为不一致而系统里同时存在新旧版本的副本导致Agent的调用结果时好时坏。场景是这样我一开始决定调整meeting-minutes技能的处理流程让它加入对输出自查的要求。我把最新的SKILL.md推到一个共享技能库里。但事后来看有几台执行任务的机器或者服务进程还在使用旧的缓存技能库里虽然是新版文件但缓存的是旧版的description索引或正文。这导致同样的输入有些进程产出的纪要里有自查后的修正痕迹有些没有行为完全不可预期。解决这个问题的方法是在技能目录里引入明确的版本字段并且在系统的技能加载器里建立版本检查机制。具体来说--- name: meeting-minutes version: 1.3.0 description: ... ---每次加载技能时和技能库的lock文件对比版本号。如果加载器发现技能目录里的版本号与lock文件不一致就直接拒绝加载并报错这样问题在一开始就能暴露而不会在线上跑了好几天之后用户才反馈结果时好时坏。另外如果你要在一个Agent系统里支持多版本并存就得在技能的调用链路里显式传递版本号参数并在技能函数的返回结果里带上版本信息。这种设计能在调试时大幅节省排查成本——输入相同但输出不同时第一件事就是去看是不是版本不一致。5. 一些收尾经验技能该在什么阶段引入、怎么保持技能库的整洁最后聊点我在多次项目切换后总结的经验。第一个经验是不要在自己还没写完第一个Agent功能时就开始搭技能库。技能化的过程是把已经验证有效的任务处理逻辑从单次会话中抽取出来形成可复用资产。如果任务本身还在频繁迭代、业务需求还没定型过早抽象只会让你花大量时间维护技能文件的结构和边界而不是解决问题本身。我判断何时该引入技能库的标准是同一个任务模式在三个以上的用户会话里重复出现并且每次都用类似的方式处理。达到这个标准就值得把这段处理逻辑沉淀成一个技能。在没达到这个标准之前安安分分把提示词写在应用代码里就行。第二个经验是关于技能库的定期整理。我会每两周花一个下午做一次技能库的去重审阅。很多技能在扩展过程中会慢慢长出一些重复的处理逻辑比如两个技能里都包含了提取待办事项的指令但表述和规则细节并不完全一致。这种重复会导致模型在加载不同技能时获得互相矛盾的规则。处理办法是把这些共享逻辑抽成一个公共技能或者独立模块让需要它的技能在SKILL.md中通过引用方式使用而不是复制粘贴。指令的单一来源原则和代码里DRYDont Repeat Yourself原则一样重要。第三个经验是要为每次技能调用留日志。我的技能加载器会在每次加载技能时打一条结构化日志包含技能名、版本号、加载时长、上下文token消耗数。这些数据是后续优化技能description和正文长度的基础。比如我观察过某个技能在一次长会话中被反复加载了三轮每轮都重新注入了完整正文。通过日志定位到这个问题后我给它加了会话级缓存单次会话的token消耗下降了将近40%。如果没有日志这种优化根本无从谈起。说实话agent-skills这套东西发展得很快目录格式、加载协议、分发机制都还没有大一统的标准。但核心思想是稳定的把大模型的能力从一次性的提示词调教变成可积累、可复用、可隔离的模块化资产。无论后续具体格式怎么变这个方向大概率不会变。我在几个生产项目中完整用过这套方法论之后最大的感受是它让Agent项目的可维护性终于赶上了传统软件工程的基本水准——你可以独立测试一个技能可以单独回滚一个技能可以并行开发多个技能而这一切在单体提示词阶段都是奢望。如果你也在被提示词越攒越长、改一处坏三处折磨我强烈建议试试技能化的思路从一个高频场景开始把那个提示词怪兽拆成第一个技能文件。