agent-skills 这类项目核心价值不是多了一个仓库而是把 AI 代理的能力组织方式从一个模糊概念变成了可落地工程实践。如果你最近在折腾 AI 代理、做复杂提示词或者让大模型反复执行同一类任务你会很快遇到一个问题提示词越来越长改一处就影响全局换一个任务又要重写。skills 的思路就是把代理要用的能力拆成一个个可复用、可描述、可版本管理的技能单元。先给结论这个方向值得深入但不要把它理解成“提示词模板合集”它更像一套代理能力管理的工程方法。下面按我实际使用的顺序拆开讲。1. agent-skills 解决的真实问题代理不是聊天框是干活系统很多人在调大模型时会有一个错觉只要提示词写得足够详细模型就能稳定完成任务。这个说法在小场景里成立一旦任务变多、输入变复杂、输出要对接业务系统纯提示词方式很快就会失控。1.1 为什么“提示词堆在一起”会越来越难用先看一个实际场景你让代理负责整理一次运营会议记录包括抽取行动项、按负责人归类、生成待办列表。第一次写提示词可能只要几百字。跑通之后你发现还要处理语音转写文本的噪声要处理同一个负责人有多个称呼的情况要处理会议里出现的数字格式不统一的问题。每加一条规则主提示词就长一截。再过两周这个提示词已经到了三千字。你改一个环节发现另一个环节的输出格式变了你增加一种输入格式发现原来的规则被冲掉。最麻烦的是你根本说不清楚这一次失败是因为模型能力不行还是因为你的提示词内部有冲突。skills 的思路就是在这一步出现把“抽取行动项”和“处理名称统一”甚至“把数字格式标准化”各拆成一个独立技能每个技能有明确的输入、约束和输出格式代理按需加载而不是把所有知识都塞进一段上下文。1.2 技能库到底把什么结构化了技能库结构化的不是“回答”而是“做事方式”。它包含几个关键部分技能的名称和描述用来让代理判断什么场景该用执行步骤或规则告诉代理这件事怎么做输入输出的约定定义格式、字段、约束示例给代理一个可对照的参考边界和注意事项说明哪些情况不该用这个技能这样一来“让代理完成任务”就从一段线性提示词变成了一套按需调用的能力集合。每个技能可以单独测试、单独修改、单独复用不乱。2. 技能、工具、提示词先把三类概念拆清楚接触 agent-skills 时最容易混淆的是技能、工具和提示词到底什么关系。我在项目里调试时经常看到有人把三者混在一起导致技能库结构混乱、代理误匹配。2.1 三类东西的边界工具是可执行的函数或接口比如读取文件、调用 API、执行 shell 命令。它做的是“能做的事”。提示词是给模型的自然语言指令限制它“怎么说”。它做的是“约束表达”。技能则是把“能做的事”和“该怎么做”包在一起。它可能包含一段提示词、一个工具调用流程、一套输入输出约定和若干示例。它解决的是“某一类任务如何稳定完成”。维度工具提示词技能本质可执行能力指令文本能力包是否执行代码是否可能包含也可能不包含单独测试可以较难可以复用粒度单一动作整段对话一类任务典型文件函数、脚本prompt 文本SKILL.md 示例/脚本2.2 什么时候该用技能而不是工具如果只是让代理调用一个计算函数用工具就够不需要技能。技能适合以下情况任务需要多步骤比如“读取会议记录、抽取行动项、按负责人归类、输出表格”任务依赖业务规则比如“凡是 2023 年之前的项目不用标注‘当前’”任务需要稳定格式比如输出给下游系统解析的 JSON任务需要示例引导比如文本分类、信息抽取这类模型表现容易波动的工作判断标准很简单如果你发现同一个任务需要反复写相似的长指令而且每次写完结果还不一致这就是该做成技能的信号。3. 搭建技能库目录、格式和一个最小示例下面这部分是实操。我建议你先不要追求完整框架而是先搭一个最小技能库把“一个技能从定义到被代理调用”的链路跑通再逐步扩充。3.1 先定目录结构常见的做法是每个技能一个目录目录里放一个主说明文件再按需放示例和脚本。目录命名优先用短横线分隔的小写英文方便代理在匹配时快速识别。skills/ meeting-action-extractor/ SKILL.md examples/ input.txt output.json name-normalizer/ SKILL.md rules.md digit-formatter/ SKILL.md这里不是必须叫 SKILL.md但建议保持统一。因为代理读取技能库时通常会先按文件名扫描统一的命名能减少匹配歧义。3.2 SKILL.md 的常见写法一个技能说明文件通常包含开头描述、正文规则和结尾示例三块。开头描述最重要因为代理选不选这个技能主要看描述和目标任务的匹配度。--- name: meeting-action-extractor description: 从会议记录文本中抽取行动项按负责人归类生成待办列表。 --- ## 适用场景 - 输入是会议纪要或语音转写文本 - 需要输出负责人、行动项、截止时间 ## 执行步骤 1. 识别文本中明确提到负责人的行动句 2. 去掉“可能”“应该讨论”等不确定表达 3. 按负责人生成待办条目 ## 输出格式 JSON 数组每个元素包含负责人、行动项、截止时间三个字段。 ## 边界 - 如果文本中没有负责人输出到 unassigned - 如果截止时间缺失字段值为空字符串这里有个容易被忽略的点技能文件里的描述不是写给用户看的是写给代理看的。描述越具体代理在误匹配时越容易判断“这个技能不适用”。如果写得太宽泛比如“处理会议文本”代理会把什么都不相关的任务也套进来。3.3 最小可用示例我建议每个技能至少配一个输入示例和一个期望输出。这个示例不只是给人类看的更是给代理做比对的。调试时你可以把示例直接喂给代理看它的输出和期望差多少。[ { owner: 张明, action_item: 本周五前完成发布检查清单, due_date: 2025-06-13 }, { owner: 李婷, action_item: 和设计团队确认新版页面交互稿, due_date: } ]有了示例你在跑真实数据时就能快速判断代理是不是理解了这个技能还是只靠运气输出了相似结构。4. 代理怎么找到技能加载、匹配和执行链路技能库建好之后关键是让代理在合适的时机找到并加载合适的技能。这块在项目里最容易出问题因为很多人以为把技能文件塞给代理就可以了。实际链路要分成几步。4.1 技能匹配的核心是描述写得准代理选择技能的逻辑一般是先读取所有技能的名称和描述再根据当前任务判断哪个技能最合适。所以匹配质量的第一决定因素不是代码写得多好而是描述写得准不准。这里要遵守几个原则描述里写清楚输入类型比如“会议记录文本”而不是“文本”描述里写清楚任务目标比如“抽取行动项并生成待办列表”而不是“处理会议”避免用模糊词比如“智能分析”“高效处理”这类词对代理匹配没有帮助同名或相似技能之间描述要刻意做出区分我实际测试时发现代理经常在两个相近技能之间犹豫比如“会议行动项抽取”和“会议摘要生成”。解决方法是各自描述里明确写“本技能不负责生成摘要只抽取行动项”边界信息反而是最好的筛选条件。4.2 一种简单的加载流程如果你的代理没有现成的技能加载机制可以先按这个流程实现启动时扫描技能目录读取所有技能的名称和描述把技能清单以结构化文本形式注入到系统消息代理根据用户任务选择候选技能选中的技能文件内容加载进上下文代理按技能内的步骤执行输出按约定格式返回[系统消息] 你可以使用以下技能 - meeting-action-extractor从会议记录文本中抽取行动项按负责人归类 - name-normalizer统一人名称呼处理简称和别名 当任务与技能描述匹配时调用对应技能如果都不匹配直接给出普通回答。这个流程看起来简单但实际运行中要靠日志确认每一步代理有没有选中技能、选中了哪个、加载文件是否成功、输出是否符合格式。不要跳过日志否则你只能看到一个错误结果完全不知道是匹配错了还是执行错了。5. 技能质量怎么判断不说“效果不错”而是看这四件事技能库写多了之后你会发现一个新的问题有的技能看起来很完整但实际跑起来就是不稳定。这时候不能靠感觉判断要给每个技能建立可验证的质量标准。5.1 可复现性同一个输入连续跑三次输出差异大不大。这是最基础也是最重要的指标。如果一个技能在同一份输入下每次输出结构都不一样那下游解析一定会出问题这种技能不能上线。可复现性差的原因通常是没有把输入格式边界写清楚或者示例不够或者技能内步骤里留了大量让代理自由发挥的空间。修的时候不要加更多规则先补示例再收紧步骤描述。5.2 失败可观测技能执行失败时是直接返回错误还是默默输出一个残缺结果我们更希望它明确失败。比如会议记录里没有负责人技能应该标记 unassigned而不是自己编一个负责人名字。这需要你在技能描述里写清楚“遇到缺失字段怎么办”而不是让代理自行发挥。好的技能应该做到能处理的场景稳定处理不能处理的场景明确说明。含糊糊地输出等于把问题留给下游。5.3 边界清晰边界清晰的技能很克制。它知道自己只负责哪一段遇到不属于自己的任务会主动拒绝而不是硬套。比如 name-normalizer 只处理人名不会跑去整理日期格式。技能之间边界重叠是代理误匹配的主要原因。测试边界的方法是故意给代理一些不匹配的输入看它会不会强行使用技能。如果会说明描述里的边界信息不够明显。5.4 可维护性技能是要长期维护的。三个月后你回头改一个技能能不能在十分钟内定位到规则、示例、边界分别在哪里如果做不到说明文件结构有问题。我建议把“长规则”拆到单独文件主描述只保留触发条件和执行概览避免一个 SKILL.md 撑到几千行。质量维度判断方法常见失败信号可复现性同一输入跑三次输出结构每次不同失败可观测缺失字段时是否明确标记编造缺失内容边界清晰不匹配输入是否拒用强行套用技能可维护性修改定位时间单文件过长、规则重叠6. 实际落地避坑先单技能再技能库最后聊几条我踩过之后觉得最值得说的经验。如果你的项目也打算引 agent-skills 这套思路这几条能帮你少走弯路。6.1 不要一上来就做成框架很多人看到技能库第一反应是先写一个通用加载器、做一个后台、再做管理界面。我建议先别急。先用一个技能、一个代理、一条真实任务跑通链路确认匹配、加载、执行、输出四步都稳定再去考虑批量化和框架化。如果你连基础链路都没验证过就搭框架最后大概率会发现框架限制比帮助大。灵活的系统不是一开始设计出来的是从一个可用版本慢慢演化出来的。6.2 技能多了之后的管理问题技能一多匹配冲突就会出现。我有一次为了让代理处理不同格式的发票连续建了五个技能结果代理经常选错。后来我把五个技能合并成一个靠内部条件分支处理不同格式匹配反而稳定了。所以技能拆分不是越细越好。判断标准是代理能否在只看描述的情况下准确选择。如果它频繁选错先别急着优化描述先考虑是不是拆得太细或者两个技能本身该合并。技能库也需要版本管理。每个技能的改动要留记录因为代理的行为会随技能内容变化而波动没有版本记录你很难知道某次输出变差是不是因为改了一个技能文件。6.3 我建议的推进路径第一步选一个你反复在做、结果一直不稳定的任务第二步把这个任务写成单一技能配一个输入示例和一个期望输出第三步用同一份输入连续跑十次记录成功率和输出一致性第四步确认稳定后再把这个技能接入批量任务或接口第五步技能数量超过五个时再考虑目录管理、加载器和日志系统踩过几次之后我发现很多问题不是模型能力不够而是技能描述和输入输出约定没有处理干净。先单技能跑稳再技能库扩容这个顺序能帮你把问题控制在可控范围内。agent-skills 这类项目真正的价值是逼着你把“让代理干活”这件事当成工程来对待而不是继续依赖一段越来越长的提示词。