如果你最近半年一直在追大模型应用一定绕不开 agent-skills 这个关键词。它不是一个框架也不是某家大厂的独家功能而是 Agent 应用设计里正在快速成型的一种新范式。说人话就是我们不再满足于让大模型“会聊天”而是开始认真地教它“会干活”——把一类任务的处理流程、判断规则、工具调用方式封装成一个可以被复用的技能包Agent 遇到对应场景时能主动调用、稳定执行。这篇文章我就围绕 agent-skills 这条路拆解它的核心逻辑、适用场景再给出一套可以直接上手的技能包搭建方法。这篇文章适合谁看两类人。一类是正在做 Agent 应用开发的工程师想搞清楚为什么自己写的复杂提示词总是跑不稳、换个任务就翻车技能化封装能解决什么问题另一类是把大模型工具嵌入到日常工作流里的重度用户比如用 Agent 辅助写周报、做数据分析、整理会议纪要的人——你不需要会写多复杂的代码但理解技能包的思维模型能让你手里的 Agent 立刻从“偶尔聪明”变成“稳定好用”。1. agent-skills到底是什么为什么现在才火起来1.1 用学乐器类比理解技能包把 agent-skills 理解成“给 Agent 请的私教课”是最贴切的。想象你学吉他给你一本乐理书你能看懂但弹不出曲子给你一份《晴天》的六线谱照着练三遍你就能磕磕绊绊弹出来。乐谱本质上就是把“怎么弹这首歌”这件复杂事拆成了指法、节奏、段落顺序并且用一种固定的格式保存下来下次想弹直接拿谱子对着练不需要重新发明一次。Agent 技能包干的也是这件事。大模型本身像那个看懂乐理但你还没教它弹琴的人它知道很多知识但不知道“处理一场会议纪要”应该按什么顺序来做。而一个写好的 meeting-minutes 技能包就是那份六线谱它告诉 Agent 先读取转写文本、再提取发言人和行动项、接着按模板生成纪要、最后检查格式。Agent 每次遇到“帮我把会议内容整理一下”这类请求时就会自动找到这份谱子并按谱演奏。这个类比还能解释一个重要现象为什么现在才火。因为早期的 Agent 应用大多数是在“提示词里写规则”相当于每一次演出前都现场编一份谱子。任务简单时还行任务一复杂、规则一多现场编谱就容易漏、容易乱、容易前后矛盾。技能包解决的问题就是“把谱子固化下来并且让 Agent 知道什么时候该用哪一份” 。1.2 技能库和提示词、插件、Function Calling的区别很多人会把 agent-skills 和另外几个概念混在一起我在项目里一开始也分不清这里把它们的边界梳理清楚。提示词Prompt是“一次性指令”。你告诉模型“请把这段文字总结成三条要点”它做完就完了。下次再问它不会有任何记忆也不会因为你上次夸过它“总结得很好”就稳定保持那个水平。技能包则是“可复用的操作流程”它把一次性的指令升级成了带有步骤、规则、校验逻辑的整套方法而且能被模型主动识别和调用。插件Plugin解决的是“能力边界”问题。模型不会算数就接个计算器插件模型不能访问外部网页就接个搜索插件。技能包解决的是“做事方法”问题——假设模型已经能调用工具了但它不知道你的团队写周报的固定格式、不知道你处理客户投诉要分几步。所以插件和技能包不是竞争关系反而是上下游技能包是流程层负责编排插件是执行层负责具体动作。Function Calling 则是“单个动作的封装”。它把“查询天气”“计算运费”这类原子操作变成可调用函数。技能包比 Function Calling 高一整个层级一个技能包内部可能包含多个函数调用、多轮判断、条件分支。举个例子Function Calling 能查天气但技能包能完成“根据未来三天的天气决定周末露营是否改期并生成一份备选方案报告”——这中间有数据获取、有规则判断、有报告生成是多个函数的组合和编排。概念厘清之后你会发现 agent-skills 真正解决的是“稳定复现复杂行为”的问题。这是所有把 AI 用到生产环境的人都会遇到的痛点模型不是不会是不稳定。技能包用结构化的方式把“会”固定在文件里让每次执行都有章可循。2. 技能工程的底层逻辑从“告诉AI怎么做”到“让AI自己会做”2.1 上下文工程的瓶颈以及技能路由是怎么解决的在过去一年里“上下文工程”几乎成了 Agent 开发的代名词把背景信息、角色设定、操作规则全部塞进系统提示词让模型在生成时“看到”足够的上下文。这个思路本身没错但它的瓶颈非常明显——上下文窗口是有限的而且模型对长上下文末尾的内容关注度会衰减。我做过一个实测在系统提示词里放 20 条业务规则时模型对前 10 条规则的遵守率明显高于后 10 条。这不是模型笨而是注意力机制的特性——它对靠前和靠后的信息记忆更牢中间部分容易被“吃”掉。而技能包的路由机制本质上是在上下文到达模型之前先做了一次“信息筛选”。系统只把真正与当前任务相关的技能描述注入上下文而不是一股脑塞全部规则。这样窗口占用更小模型注意力更集中规则遵守率自然更高。技能路由的工作方式有点像一个图书馆的检索系统。你不会把整个图书馆的书都搬到一个读者面前而是根据他的问题告诉他“你要的书在三楼东侧书架”。agent-skills 的元数据层干的就是这件事每个技能包自带描述信息name、description、trigger conditionAgent 在收到用户请求后通过语义匹配找到最合适的技能包再把技能内容动态加载到上下文中执行。这个机制带来的直接好处是技能数量可以做到几十上百个而不会把上下文撑爆。因为它不是全部加载、真正生效的只有被选中那一个。这就像你手机里装了两百个 App但每次启动的只有正在用的那个内存压力并不会线性增长。2.2 技能包的执行机制声明式元数据加上命令式操作一个设计良好的技能包内部其实分成两层结构声明式元数据和命令式操作。声明式元数据解决“什么时候该用”。它用结构化的字段描述技能的名称、功能、适用任务类型、输入输出参数。这部分是给模型“看”的帮助模型在用户请求到达时快速判断“该不该调用这个技能”。元数据写得越精准技能路由的准确率越高。反过来如果描述写得太泛比如“用于处理文档”那模型遇到任何文档任务都可能会打这个包的主意结果就是路由混乱、效果全无。命令式操作层解决“具体怎么做”。它可以是自然语言编写的分步操作指引也可以是实际可执行的脚本或者两者结合。自然语言步骤适合描述判断逻辑和决策规则脚本则适合做确定性强的数据处理。我在实战中发现把公式化、重复度高的操作尽量下沉成脚本把需要举一反三的判断留给自然语言指引两者按合适比例混合是技能包稳定性最高的配制。这两层结构互相配合构成了一个完整的最小执行单元。模型先根据元数据做路由判断选中技能包后读取操作指引按步骤执行、必要时调用脚本最后输出结果。整个过程对用户来说几乎是透明的但内部已经完成了一次“自动化的专家决策”。3. 从零搭建一个自己的Skill包实操全流程3.1 设计第一步先把边界和触发条件想明白很多人第一次写技能包上来就写步骤写到一半就乱套了。我的经验是动笔之前先回答三个问题——这个技能解决的任务边界是什么输入什么、输出什么什么情况下模型应该选择我而非其他技能边界问题看起来简单实际最容易翻车。比如你想做一个“周报生成”技能那“月报生成”算不算它的职责范围如果边界不清晰模型很可能拿周报技能去生成月报格式对不上、数据维度也对不上。我在设计中通常会在技能描述里加上排除性说明比如“本技能仅用于周报不适用于月度或季度汇报”这招实测能显著降低误路由的概率。触发条件则是模型选择技能的判断依据建议写成“用户提供…并要求…”的句式把输入形式和任务意图同时描述清楚。比如“用户提供一段会议转写文本并要求生成结构化会议纪要”。这句话同时约束了输入格式和任务动词比单纯写“生成会议纪要”要精确得多。一次调用对应一个技能触发条件写得越具体技能组合使用时的冲突就越少。3.2 技能包的标准文件结构技能包虽然目前还没有全球统一的标准格式但业界已经形成了一套事实上的通用结构。我一般按下面这种方式组织agent-skills/ ├── skills/ │ ├── meeting_minutes/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ │ └── summarize.py │ │ └── assets/ │ │ └── template_zh.md │ ├── weekly_report/ │ │ ├── SKILL.md │ │ └── scripts/ │ └── ... └── registry.jsonSKILL.md 是技能包的主入口负责声明元数据和执行步骤scripts 目录放可执行的脚本assets 目录放模板类资源registry.json 是技能注册表相当于一个索引让 Agent 能快速扫描当前环境里有哪些技能可用。这个结构设计的核心考量是“关注点分离”。元数据、执行逻辑、资源文件分开存放好处有两个一是方便维护改模板不用碰脚本、改逻辑不用翻模板二是方便后续做技能库的批量管理。如果直接把所有内容写进一个巨型 markdown 文件技能少的时候还好超过十个以后维护成本会直线上升。3.3 写一个完整的SKILL.md示例会议纪要技能我拿自己项目里最常用的 meeting_minutes 技能做例子展示一份可用的 SKILL.md 长什么样。--- name: meeting_minutes description: 将会议转写文本整理为结构化会议纪要。适用于头脑风暴、项目同步、客户沟通等场景仅处理单次会议内容。 trigger: 用户提供会议转写文本并要求生成纪要、总结、行动项或会议要点 inputs: transcript: 会议转写文本纯文本格式 attendees: 参会人员列表可选影响发言人的命名 outputs: minutes: 结构化会议纪要包含主题、参会人、议题、行动项 ---上面是 YAML 格式的 frontmatter也就是元数据区。写这段的重点在于 description 和 trigger 必须用“模型容易理解的语言”。我建议多做几次 A/B 测试写同一段描述的不同版本然后拿同样的用户请求去测路由命中率保留命中率高的版本。frontmatter 下面是操作指引区用自然语言告诉模型执行步骤。注意这里的语气应该是“给一个聪明的执行者看的标准操作流程”而不是“给程序员看的代码注释”## 执行步骤 1. 阅读完整的会议转写文本识别会议主题。如果原文没有明确主题根据讨论内容归纳一个不超过15字的主标题。 2. 提取参会人员和发言人。如果用户提供了 attendees 列表将转写中的发言人与名单对齐未提供的场景下直接使用转写中出现的角色标识。 3. 按讨论顺序将内容归纳为议题段落。不要逐条复述转写原文每个议题用2-4句话概括核心讨论和关键结论。 4. 单独整理行动项列表。每条行动项必须包含负责人、事项内容和截止时间如果原文存在。没有明确负责人的行动项标注“待指派”。 5. 按 assets/template_zh.md 中的格式输出纪要输出前检查模板中的必填字段是否全部覆盖。 ## 注意事项 - 不要添加转写文本中不存在的结论 - 行动项数量为零时在对应位置写“无” - 输出语言与转写文本语言保持一致你可能会问为什么执行步骤也写在 markdown 里脚本不是也能做吗原因在于会议纪要里的议题归纳和结论提炼需要语义理解这是脚本做不到的必须靠模型的语言能力。技能包的优势正在于此把模型擅长的语义理解归纳议题和我们擅长的确定性控制格式要求、输出模板组合在一起各取所长。3.4 可执行脚本部分怎么和模型配合刚才的例子偏“纯自然语言指令”但技能包里真正能提升稳定性的是安排脚本去处理确定性强的环节。我还是拿会议纪要技能来举例假设转写文本里有重复的停顿词、口癖模型在归纳时可能会被这些噪音干扰。这时你可以在技能包加一个预处理脚本# scripts/clean_transcript.py import sys import re def clean(text: str) - str: # 去掉口头禅和重复填充词保留语义完整 text re.sub(r(嗯|啊|那个|就是说|然后然后), , text) # 合并多余空白 text re.sub(r\s, , text) return text.strip() if __name__ __main__: input_path sys.argv[1] output_path sys.argv[2] with open(input_path, r, encodingutf-8) as f: raw f.read() cleaned clean(raw) with open(output_path, w, encodingutf-8) as f: f.write(cleaned) print(cleaned transcript saved to, output_path)然后在 SKILL.md 的执行步骤里把第一步改成“先运行 python scripts/clean_transcript.py input.txt output.txt再读取 output.txt 进行后续处理”。这样就把一个确定性很强的清洗动作从模型手里交给了脚本模型只负责真正需要理解力的部分。我个人的设计原则是能用代码确定的不要靠模型临场发挥模型发挥越多结果方差越大。脚本、模板、规则判断这些确定性逻辑全部下沉到可执行、可验证的代码里。模型只保留一个职责理解复杂信息并输出需要语义判断的内容。这样拆完之后技能包的结果稳定性会有一个质的提升。4. 我踩过的坑5个高频翻车现场与排查速查表4.1 翻车现场实录先说一个最常见的翻车场景技能包写好了注册表也配置了但 Agent 就是不调用。最初我把原因归结为模型能力不够后来排查发现是技能描述写得太抽象。我当时写的是“用于处理文档”结果模型面对一封邮件和一个数据分析任务时都犹豫要不要调用它最后干脆都不用。修复方案很简单把描述改成“将用户提供的会议记录转写文本整理为结构化会议纪要包含议题、结论和行动项仅在用户明确提供会议转写内容或要求生成纪要时使用”。第二个高频坑是技能包“过度执行”。有一次我写了个数据分析技能包里面有一条“如果发现数据异常生成一份异常报告”。结果模型在数据完全正常时也强行生成了异常报告理由是“为了稳妥”。这就是操作指引里给了模型太多自由裁量权却没有给出“什么情况下停止”的排除性规则。后来我加了这么一句“如果所有数据点都在合理范围内直接输出正常结论不要生成异常报告”翻车率立刻降下来了。第三个坑和路径有关。技能包依赖的外部文件比如模板、配置文件如果用了相对路径Agent 在不同工作目录下执行时会找不到文件。我早期在技能包里写模板时用的是assets/template_zh.md在项目根目录起步时没问题但有一次把 Agent 的工作目录切到了子目录直接报错。现在我的所有技能包都强制要求使用绝对路径或者在每个技能包自己的目录下启动执行流程彻底规避这个问题。第四个坑是模板字段和脚本输出格式对不上。这属于“技能包自己内部打架”。脚本输出的是英文逗号分隔的数据模板里却用中文顿号最后生成的成果物格式奇奇怪怪。这种问题排查起来特别隐蔽因为它不会直接报错只会让你的输出看起来“不太对”。我在后期加了一整套格式校验脚本在技能执行完之后自动检查输出是否符合模板规范不符合就重跑或提示 Agent 修正。第五个坑也是做技能库的人一定会遇到的多个技能包的描述语义重叠。比如我有一个“周报生成”技能和一个“项目进度总结”技能描述里都写了“总结项目进展”模型面对一个项目周报任务时常常拿不准选哪个。后来我的解法是在两个技能的描述里明确写了各自的边界和周报技能标注“仅按周维度输出”、总结技能标注“不限定时间维度适用于非周期性总结”。边界说清楚之后路由准确率从 70% 左右提升到了 95% 以上。4.2 高频问题排查速查表把上面这些实战经验整理成一张速查表方便你对照排查症状可能原因处理方式Agent 不调用技能直接自由发挥description/trigger 写得太泛模型判断不了是否该用重写描述包含具体输入形式和明确的触发动词调用了但输出不满足模板要求操作指引里没强调输出格式或模板文件没有挂载在 SKILL.md 里增加“必须按 templates 下的模板格式输出”的硬性要求技能执行到一半就停了脚本路径错误、依赖文件缺失改用绝对路径并确保脚本可独立运行验证两个技能经常搞混描述语义重叠给每个技能写边界和排除性描述明确“不适用于什么场景”结果时好时坏不稳定操作指引留白太多模型自由发挥空间过大把判断逻辑尽量细化必要时下沉为脚本技能能跑但模型生成的内容有幻觉操作指引里没有“禁止添加原文不存在信息”的规则加上否定性约束并给出明确检查步骤排查的核心原则是先看路由对不对看模型是否选中预期技能再看执行过程看步骤是否完整走完最后看输出看格式和内容是否达标。三层排查法能覆盖绝大多数问题也避免了一次次“全量重写”的笨办法。5. 技能资产化从个人技能包到团队记忆库5.1 把业务知识封装成可复用技能做 agent-skills 这件事很多人一开始只是图“让 Agent 更稳定”但做着做着会发现这本质上是在把个人经验、团队规范、业务知识全部“固化成资产”。以前新同事入职要学会公司周报怎么写靠的是翻老员工的邮件、问来问去。现在把这些规范封装成周报技能包新同事的 Agent 一键就能按公司格式生成初稿产出物天然符合既有规范。这个转变的底层逻辑是技能包成了组织知识的一种载体。它比文档更好用因为文档是给人看的、需要人去理解后再操作技能包是给 Agent 看的、直接驱动操作。它也比代码更灵活因为代码里要写死各种业务分支而技能包可以把分支判断交给模型的理解力业务规则只要写清楚边界和倾向即可。我在团队内部推过一轮“技能资产化”让每个业务小组把自己最常做、最有套路的工作封装成技能包。数据组做了“异常指标归因报告”包运营组做了“活动复盘”包销售组做了“客户跟进记录整理”包。三个月下来整个团队的 Agent 工具链从“一堆零散提示词”变成了“一套可检索的技能库”搜索、复用、迭代都变得非常顺畅。这里有个个人心得想分享技能包不要想着一次写完美。先以天为单位快速迭代。5.2 技能包的版本管理与跨Agent协作技能包一旦多起来、用起来就要面对版本管理的问题。我现在的做法是每个技能包都进 Git 仓库单独一个仓库管理所有技能包每次修改都走 commit记录改动原因。技能包的版本号分成大版本和小版本大版本改动意味着流程结构变了、执行步骤重排了小版本则是字段微调、描述优化、模板细节更新。Agent 在调用技能时默认用最新版本但通过 registry 可以回溯到任意历史版本。跨 Agent 协作是技能资产化之后自然会浮现出来的需求。不同 Agent 各管一摊但它们的技能库可以共享同一个 registry相当于一个团队级的“技能知识库”。Agent A 发现了一个更好用的数据处理流程提交到技能库后Agent B 下次处理类似任务时也能命中这个技能整个系统的能力是共同演进的。这里给两个实际的协作建议一是每个技能包的描述里标注维护人出现误路由或者执行 bug 时知道找谁二是给技能包写一个简短的 CHANGELOG记录每次修改的影响范围避免改了一个字段导致下游 Agent 的输出结构变化。把技能库当成一个产品来运营而不是随手写的脚本仓库长期收益会非常明显。聊到最后说说我自己这一路做下来的最大体会agent-skills 表面上是技术问题实际上是一种“知识工程”的新形态。它要求你抽丝剥茧地把一种隐性经验显性化、结构化、可执行化这对表达能力和逻辑能力的要求比对代码能力的要求还高。但一旦熬过了最初那段“怎么描述都不对劲”的磨合期技能包给你带来的稳定性和积累感会让你完全不想回到“每次都现场写提示词”的状态。如果你正打算开始我建议从最日常、重复度最高的那个任务做起——把它的流程写清楚封装成第一个技能包然后拿真实数据去测按这里提到的排查表去调你会很快感受到技能工程带来的改变。