做了快两年 Agent 开发我踩过最大的坑就是把技能做成一段又长又全的提示词模板。每次新任务进来就在模板上加一段规则几个月后那段 Prompt 自己都看不懂。后来全面改成 SKILL.md 来组织技能才意识到技能和提示词模板不是字数的区别是结构上的区别。这篇文章我会讲清楚 SKILL.md 到底怎么用、它解决了哪些模板解决不了的问题以及我迁移过程中踩过的真实坑。适合正在做 Agent 开发、想搭技能库但还没找到方法的读者。1. 为什么一段提示词撑不起一个 Agent 技能1.1 上下文长度陷阱写得多不等于记得住刚接触大模型时我跟大多数人一样迷信一件事只要我把规则写清楚、写详细模型就会照做。于是我给 Agent 写技能动辄七八百字人设、语气、禁忌、输出格式、成品范例全堆在一段文本里。那段时间生成结果忽好忽坏最典型的问题就是——我在开头写了不要用感叹号它结尾照样满屏感叹号。这不是模型笨是注意力机制在起作用。模型处理超长指令时每一条规则都要跟上下文里其他 token 抢注意力资源。规则越多单条规则被稳定执行的概率就越低。你把二十条要求塞进提示词里跟把一整本书压缩成一页纸没有区别看起来信息都在实际能被有效记住的很有限。SKILL.md 解决的第一步就是别再让所有规则挤在同一段文本里。1.2 触发逻辑和执行逻辑严重耦合传统提示词模板还藏着一个更隐蔽的问题模板里既要写这个技能什么时候用又要写这个技能怎么用两件事混在一起。我以前写的模板开头永远是这样的当用户需要把一段文字改编成不同平台的文案时请你扮演资深新媒体运营专家按照以下步骤操作……问题来了Agent 在真正运行的时候并不会把每一个技能模板完整读一遍再决定用哪个。它靠的是对用户意图的近似匹配。模板越长、内容越杂这个匹配的噪声就越大——有时候用户只说了一句帮我把这段文章改短点技能压根没被唤起有时候用户问了个无关问题模型却把模板里的某个规则拿来套。更难受的是维护。上周产品说改一下小红书那边的 tag 规则我打开那段八百字模板改了三处结果和抖音规则那一段产生了冲突。改模板里的某一段就像改一坨没有函数封装的意大利面牵一发动全身。1.3 不可测、不可复用、不可共享工程上我们早就接受了一个事实没法自动化验证的东西迟早要还债。提示词模板恰恰就是这种东西。你想做单元测试没法做。顶多跑两次人眼看一下结果但改了一个字你是说不清结果变好还是变坏。而且提示词模板高度依赖个人书写习惯换一个团队、换一个 Agent 框架模板基本没法平移。去年我们把几个 Agent 从一套框架迁到另一套模板几乎全部重写疼得不行。回头看这些痛点正好是 SKILL.md 这类结构化技能定义要解决的——它是文件不是字符串它是目录不是一篇作文。2. 认识 SKILL.md它不是一个更长的提示词2.1 一个技能其实是一个目录SKILL.md 最核心的思路是把技能从一段 Prompt 文本变成一个结构化的目录。目录是技能的主体SKILL.md 只是入口。一个典型的技能目录长这样content-rewrite/ ├── SKILL.md ├── references/ │ ├── xiaohongshu-rules.md │ ├── douyin-rules.md │ └── gzh-rules.md ├── examples/ │ └── before-after.md └── scripts/ └── check_length.pySKILL.md 是 Agent 首先读取的入口文件它告诉模型这个技能什么时候用、大致流程是什么references 目录放的是领域知识、平台规则、注意事项模型可以根据需要按需读取examples 目录放输入输出样例给模型照着这个样子做的参考scripts 目录放可执行的脚本处理纯文本搞不定的计算、文件操作之类的任务。这套结构最大的优势是按需加载。Agent 只有在判断当前任务匹配这个技能之后才会真正去读 SKILL.md读完之后再根据指令去加载 references 里具体需要的部分。相比之下提示词模板是一次性把所有信息轰炸进上下文表面看是省事实际是增加了模型的负担。2.2 YAML frontmatter决定 Agent 什么时候醒过来SKILL.md 开头通常是一段 YAML frontmatter名字和描述都在这里写--- name: content-rewrite description: 当用户需要将长文改写成小红书笔记、抖音口播稿或公众号文章时使用。输入为素材文本与目标平台输出为对应平台文案。 ---就这么两行却往往是技能能不能被唤起的关键。description的写法非常讲究我推荐遵循当……时使用句式在描述里带上具体动作和输出形态比如将已有素材改写为小红书笔记而不是宽泛地写处理文本内容。描述是给模型看的索引不是给人看的说明。一个好的 description 要做到模型读到它时能在 0.5 秒内判断出是不是该调用这个技能。我反复调试后的经验是描述至少包含一个明确的动作动词、一个输入对象和一个输出载体。比如将会议纪要整理成待办事项就比整理信息好得多。后面我会专门说这个坑。2.3 正文写流程不写剧本SKILL.md 正文写的是工作流不是剧本。什么意思剧本是给模型立的规矩、讲的人设、提的要求工作流是给模型的一张操作清单清楚地写先做什么、拿到什么、产出什么、怎么自检。写正文时要特别注意语气。我的习惯是命令式用提取判断输出对照自检这种动词开头少用可以考虑如果方便的话这种软绵绵的措辞。模型对指令的理解程度跟句式稳定度强相关同一个技能里步骤的叙述风格越统一执行就越稳定。正文长度我有过一个很实用的经验阈值超过一屏大概 40-50 行就说明你把太多知识细节写进来了。知识细节应该外置到 references正文只留流程骨架。这个正文瘦身的过程就是把模板思维切换成技能思维的关键一步。2.4 各家框架是怎么接这个规范的坦白说SKILL.md 不是一个官方标准而是逐渐形成的社区惯例。Anthropic 的 Claude Skills 里用 skill 目录Hugging Face 的 Agent Skills 也有类似的目录约定不少开源 Agent 框架已经把技能目录当成了头等公民。它背后的共识是技能应该是一个可搬运的文件单元而不是写死在代码里的字符串。对开发者来说这个趋势有一个实操含义语法差异不重要目录思维才是核心。只要你按入口文件 references 知识库 examples 样例 scripts 脚本的方式组织技能将来迁到哪个框架都很顺。这个好处是提示词模板永远给不了的。3. 实战把多平台发文技能从模板改成 SKILL.md3.1 先拆掉你现有的提示词模板光讲概念没用我拿一个真实场景演示。假设你有一个高频需求根据产品素材生成小红书笔记、抖音口播稿和公众号文章三套文案。老办法就是写一个通用模板类似这样你是资深新媒体文案专家。请根据产品信息和目标用户生成三个平台的推广文案。 要求小红书文案600-900字带15-20个标签开头要有钩子口语化 抖音文案要短平快30秒内说完要有反转 公众号文案要结构完整有标题、副标题、正文、结尾引导关注。 注意不要用绝对化用语不要虚构数据语气自然……这段模板最大的问题不是它写得不好而是它把所有信息平铺在一层模型处理起来只能抓重点但抓到的重点不一定是你想要的。改造 SKILL.md 的第一步就是拆掉这坨平铺文本把它分成四类内容。旧模板里的内容内容类型改造成 SKILL.md 后放哪当用户需要生成三个平台文案时唤醒条件frontmatter 的 description根据产品信息生成初稿并自检工作流SKILL.md 正文小红书 600-900 字、15-20 个标签等平台知识references/ 下对应 md 文件一段标准范文样例examples/ 目录这个拆分动作是迁移过程中最重要的一步。别急着写文件先把模板放到表格里分好类你会发现很多你以为不可或缺的规则其实属于特定平台的领域知识根本没资格出现在主流程里。3.2 搭建目录把知识外置按上面的分类目录结构就清晰了。这里我给出精简版content-rewrite/ ├── SKILL.md ├── references/ │ ├── xiaohongshu-rules.md │ ├── douyin-rules.md │ └── gzh-rules.md └── examples/ └── before-after.md接下来写 references 里的小红书规则文件。注意这个文件只服务于小红书平台所以可以写得非常具体# 小红书笔记规则 - 正文 600-900 字开头前 20 字必须有钩子 - 使用 15-20 个标签前 3 个标签与内容强相关 - 语调口语化允许少量但克制的表情符号 - 禁止绝对化用语最第一100%等 - 结尾固定互动引导你们还想看什么评论区告诉我 - 正文字号偏小段落之间要有空行方便手机阅读为什么这样做更好因为当 Agent 需要生成小红书文案时它只需要加载这个文件而不用把抖音、公众号的规则一起压在上下文里。每条规则的注意力权重明显更高规则被遵循的概率自然就上去了。这就是知识外置的意义。3.3 用 SKILL.md 正文指挥工作流SKILL.md 正文不需要写太多它负责的是流程调度--- name: content-rewrite description: 将给定的长文或素材改写成小红书笔记、抖音口播稿或公众号文章时使用。输入为素材文本与目标平台输出为对应平台文案。 --- # 多平台文案改写 ## 开始条件 确认用户提供了素材且素材已在对话上下文中。若缺少目标平台信息先询问并确认。 ## 执行步骤 1. 提取素材中的 3 个核心信息点和目标读者画像。 2. 确认目标平台后加载 references/ 目录下对应的平台规则文件。 3. 根据核心信息点和对应规则生成初稿。 4. 逐项对照 references 中的规则自检初稿列出每一条修改原因。 5. 输出最终稿并附上已检查项清单。 ## 输出要求 最终输出必须包含平台名称、核心信息点、正文文案、标签/标题建议、自检结果。若任何一项缺失视为未完成。这段正文的价值是流程明确。模型读到后知道自己先干嘛、再干嘛、最后要交付什么。每个大步骤之间有空行有编号有输入输出约定比一段口吻散文式的提示词更像任务书。3.4 调用前后的实际差别迁移完跑了一次真实调用输入是产品资料请求生成一篇小红书笔记。旧办法下模型偶尔会漏标签偶尔会忘记结尾互动引导风格也飘忽。换成 SKILL.md 版的连续跑了几次每次都能稳定带上 15-20 个标签结尾必有互动引导开头钩子也基本在。更关键的是后面你再想调整小红书规则只需要动references/xiaohongshu-rules.md一个文件其他平台丝毫不会受影响。这个稳定 可维护的组合就是我从提示词模板迁到 SKILL.md 之后最直接的体感差异。4. SKILL.md 落地过程中的常见坑与排查链路4.1 技能根本没被唤起问题九成出在 description先给排查链路后面再展开。当你发现调用了技能但结果完全没体现技能特征时按这个顺序查看日志里有没有技能被触发的记录检查 frontmatter 里的 description 是否足够具体做一个最小复现用例用一条清晰指令强制唤起技能如果强制唤起后技能工作正常说明问题就在唤起环节description 最常见的毛病就是写得太功能化像在写代码注释而不是给模型做意图匹配的索引。我踩过很具体的例子把 description 写成内容改写工具模型根本不知道什么时候该用。改成当用户需要将长文改写成小红书笔记、抖音口播稿或公众号文章时使用之后唤起率明显上升。4.2 frontmatter 解析失败YAML 缩进和 name 命名有硬约束有一种情况最隐蔽技能文件已经放对位置了SKILL.md 也写得很完整但 Agent 就是完全不认这个技能。这种时候十有八九是 frontmatter 本身出事了。YAML 解析是非常死板的过程name里出现空格、中文冒号、特殊符号description 超过了一行导致没有正确闭合整个技能都会被静默跳过。我的做法是在本地写一个极简校验脚本用 yaml 库把所有 SKILL.md 的 frontmatter 批量解析一遍解析失败就直接报红。这个脚本花了二十分钟写之后至少帮我省了十次明明没问题啊为什么不生效的排查时间。如果你也不想写脚本至少要在编辑器里确认 YAML 缩进和引号是正常的。4.3 正文过长、references 嵌套太深Agent 会减少主动读取技能没有触发问题后下一个坑是触发了但效果不好。排查到最后我和团队发现原因往往不是模型不行而是我们把 SKILL.md 又写成了小号提示词模板——步骤特别多、每条步骤下面还带说明、references 还被套了二级三级目录。结果 Agent 读正文就花掉了大量上下文预算根本没有余力再去 references 里找知识。我的调整原则就两条第一正文控制在 40 行以内超过就强制外置第二references 里的文件嵌套最多两层太深的话 Agent 会因为找不到目标而放弃读取。这里的本质是上下文是有限的你得用最省流量的方式让模型掌握流程。4.4 版本管理与回归测试技能也需要 git 记录很多人在提示词模板阶段没有版本管理的习惯总觉得改一改就行。但技能一旦结构化就完全可以像代码一样管理。我的最低限度实践是每个技能目录都放进独立的 git 仓库或子目录里每次改动先跑一遍固定的回归用例再提交。拿前面的 content-rewrite 举例我固定三个测试输入一段长文、一个小红书素材、一条抖音选题。每次改动后跑一遍肉眼 diff 一下输出重点看标签数量、结尾引导、绝对化用语这类硬指标有没有回归。这个方法虽然原始但能堵住改完技能结果忽好忽坏的一半问题因为大部分退化是有规律可循的。5. 哪些任务值得做成 SKILL.md哪些别硬上一张选型表解决要不要做技能的问题任务特征推荐做法理由一次性问答、闲聊、临时求助直接写提示词技能建设成本高收益撑不起来重复执行 10 次以上、流程稳定做成 SKILL.md稳定、可维护、可复用强逻辑、多分支、需要计算或文件操作SKILL.md scripts纯文本提示词搞不定强工具需求高度依赖实时信息技能骨架 实时工具调用写死的知识很快就会过时需要给团队共享、跨 Agent 复用SKILL.md 标准化目录即规范迁移和交接成本低5.1 趁早切换的目录思维比具体格式更重要说了这么多我最想传达的不是 SKILL.md 的具体语法而是一种思维的切换。提示词模板适合解决一次性问题但当你发现同一个任务要反复做或者同一个技能要交给好几个 Agent 用时它就不再是文本问题而是工程问题。工程问题就得用工程手段确定入口、拆分知识、安排流程、做版本管理。我现在每接到一个新技能需求会问自己三个问题这个任务会不会重复出现流程是不是基本稳定有没有共享需求三个问题里中两个就直接按目录方式搭技能只有一个或者一个都没有老老实实写提示词别为了用技能而用技能。技能不是越多越好而是每个技能都值得被稳定调用。5.2 最后一个实操习惯起名和描述要像搜索引擎关键词最后分享一个我个人用起来特别顺手的小习惯给技能起名时尽量别用写文章处理文本这种宽泛的词。我的技能目录名现在基本都是content-rewrite、weekly-report-summarizer、meeting-notes-actions这种动词 对象的格式description 里也一定会带触发语境。这样做的原因是Agent 的决策过程本质上是一个检索 匹配的过程。你的技能名和描述写得越像搜索关键词被正确唤起的概率就越高。技能不是说给模型听的规矩是你帮 Agent 规划好的一份作业流程。写完它你省心模型也省力。