前两天有个朋友问我：你天天挂在嘴边的skills到底是个啥？我一时半会儿还真没答上来——因为skills这个东西，你把它叫成“技能包”“角色卡”“工作流模板”好像都沾边，但又都不够准确。后来我换了个说法，他立刻就懂了：skills就是给AI代理准备的一份“岗位说明书+操作手册+边界红线”打包文件，让AI在干某类活的时候，不用你每次重新解释需求、交代流程、提醒它注意什么，它自己就能照着这一套标准动作干活。

这篇文章我会从概念拆解、文件结构、实操开发、问题排查到生态选型，完整梳理一遍我在实际项目里用skills的经验。不管你是前端开发、内容创作者、效率工具爱好者，还是在搞自动化办公、论文辅助、分镜脚本这类需求的人，只要你在跟各种AI agent打交道，这篇文章都值得你看完——因为学会了skills，你就等于给AI“开了外挂”，而且这套外挂是可以自己定制、不断复用的。

1. 先把“skills”这个概念掰开揉碎

1.1 skills到底是个什么东西

先别急着去翻文档，我们用大白话理解它。假设你公司来了个新同事，这人学习能力极强、知识面很广，但有一个问题：他不知道你公司的具体流程、不知道你要的报表格式、不知道哪些话不能说。你每次让他干活都要花十分钟交代背景，他每次干出来的东西都和你的预期偏差一大截。这时候你最想要的是什么？是一份入职手册，把岗位职责、操作流程、常用工具、注意事项全写清楚。skills就是给AI agent写的那份入职手册。

具体到技术层面，一个标准的skills包通常是一个文件夹，里面包含一份核心说明文件（很多实现里叫SKILL.md），以及若干辅助文件，比如脚本、参考模板、示例输出等。这份SKILL.md用结构化语言描述了“这个技能是干什么的”“什么时候触发”“第一步做什么、第二步做什么”“输出格式是什么”“绝对不能做什么”。当AI agent在对话中识别到相关任务时，就会把这份说明书注入到自己的上下文里，然后按照上面写的流程干活。

我最早看到这个概念是在一些支持自定义技能的开源agent项目里，后来各家主流工具都开始跟进，比如Claude Agent Skills、Codex Skills这些。它们的底层逻辑几乎一致：与其相信模型“临场发挥”，不如把专家经验写死成流程，让模型在框架内发挥。你可以理解为，以前你是让AI“自由创作”，现在是给AI“出题+答题模板+评分标准”。

1.2 为什么各家都在推skills

一个东西能火起来，背后一定是解决了真问题。AI模型的能力这几年突飞猛进，但有两个致命的弱点始终没解决：一是“记性差”，上下文窗口再大也经不住你塞一堆背景资料；二是“发挥不稳定”，同一个问题问十次，答案可能差出十万八千里。skills恰好对症下药。

先说“记性差”。以前我写一个高质量的前端开发skills，要把公司内部组件库的用法、代码规范、部署流程全部塞进提示词里，结果提示词越来越长，AI反而开始犯迷糊。现在我把这些内容拆成独立的参考文档放在skills包里，主文件只写流程和触发条件，等到真正需要某部分知识的时候，再让agent去读取对应的子文件。这样既省上下文，又让信息组织更清晰。

再说“发挥不稳定”。AI的自由发挥有时候是惊喜，但在生产环境里更多是惊吓。尤其涉及代码审查、安全审计、批量文案生成这类需要稳定输出的场景，你根本不敢让AI“自由创作”。skills把流程标准化以后，输出质量就变得可预期了。我有一次处理批量论文摘要，写了一个skills包，规定好每篇摘要必须包含几个固定小节、引用格式必须符合指定规范、每次最多处理五篇。从那以后，AI输出的一致性明显提升，我再也不用每篇都手工改写结构了。

所以各家都在推skills，本质上是在抢“AI agent生态”的入口。谁家的skills体系好用、分享方便，开发者就更愿意留在谁家的生态里。对我们普通用户来说，这是好事——竞争越激烈，skills的玩法就越丰富。

1.3 它和插件、提示词、工作流有什么区别

很多人会把skills和插件、提示词、工作流混为一谈，我简单做一下区分。

插件（Plugin）是能直接调用外部工具和API的，比如读取文件、请求接口、操作数据库。skills本身不一定有执行能力，它更像“知识和流程的集合”，但它可以配合插件使用，比如skills规定“读取a.json文件”，实际读取动作还是由插件完成。

提示词（Prompt）是一次性的临时指令，你发给模型的那一刻就生效了，用完就没了。skills是持久化的、可复用的提示词集合，它比单个提示词更系统，还可以带上附件的脚本和模板。

工作流（Workflow）通常强调多个步骤之间的编排和数据流转，比如“先抓取网页→再清洗数据→然后生成报告”。skills更侧重“在单次对话里，让AI按照既定方式思考和输出”。一个skills内部也可以包含步骤编排，但它的粒度通常比跨应用的工作流更小、更聚焦。

用生活化的比喻：提示词是你临时交代AI的一句话；插件是AI的手和脚；工作流是流水线；skills则是那份写着“岗位职责和工作手册”的文件夹。四者可以组合使用，但解决的问题不一样。清楚了这点，后面你理解怎么设计skills就会顺很多。

2. 从零开发一个可用的skills包

2.1 一个标准skills包的文件结构

开发skills不神秘，本质上就是组织好文件和写好Markdown。我先说一下最常见、最稳定的目录结构，这一节建议直接抄作业。

my_skill/ ├── SKILL.md # 技能核心说明，必填 ├── assets/ # 存放脚本、模板、参考文档 │ ├── template.md # 输出模板示例 │ ├── checklist.md # 核对清单 │ ├── helper.py # 辅助脚本 │ └── reference.doc # 详细参考资料 └── meta/ # 可选的元信息目录 ├── icon.svg # 技能图标 └── example.md # 使用示例

这个结构看起来简单，背后有讲究。SKILL.md 是入口，它必须短小精悍——因为模型每次触发技能时都会优先读取它，如果它写了一万字，上下文瞬间就被吃掉一大半，后面真正的干活环节反而没有空间了。所以SKILL.md的主要职责是“指路”，而不是“把所有知识都装进去”。

assets目录放的是“知识弹药库”。你在SKILL.md里写“遇到具体规范时读取assets/reference.doc”，模型就会在需要的时候去加载那个文件。这种延迟加载的思路，我实测下来能省大量上下文。有朋友问为什么不用单文件搞定一切，我的回答是：主文件太臃肿会导致触发率降低，因为模型一看到超长文档就不想动，甚至会出现“选择性失明”。

meta目录属于锦上添花。给skills加一个示例文件特别有用，因为模型非常擅长“照猫画虎”。你在example.md里展示“输入什么、输出什么”，它就会严格模仿这个格式。这比你在SKILL.md里反复强调“要按格式输出”管用得多。

2.2 写好SKILL.md的五个关键段

SKILL.md怎么写，直接影响技能好不好用。我踩过不少坑之后，总结出五个关键段落，建议每个skills都保留这个骨架。

第一段是名称和简介（name与description）。名称要精确，简介要写清楚“这个技能处理什么任务、在什么条件下触发”。这里有个细节：简介最好包含触发关键词。比如我写一个分镜脚本生成技能，简介里会写上“分镜”“storyboard”“镜头脚本”“运镜”等词。因为很多agent是拿description做语义匹配来触发技能的，你写得太文艺，它可能识别不出来。

第二段是目标与边界（goal与scope）。目标写三到五条即可，比如“输出带时间轴的镜头清单”。边界更重要，要写清楚“不做什么”，比如“不生成画面描述以外的内容”“不评价故事剧情合理性”。边界写好了，能避免AI过度发挥。我见过不少翻车案例，都是因为没写边界，AI把技能范围之外的活也干了。

第三段是流程步骤（steps）。这是最核心的一段。我推荐用编号列表把流程写清楚，比如“第一步，检查输入素材是否齐全；第二步，拆分场景；第三步，为每个场景生成镜头表”。尽量把流程控制在五到七步，太长了模型记不住，步骤之间也会产生歧义。每一步的描述要可操作，避免使用“适当分析”“合理处理”这类模糊词，要写“按清单逐项核对”这种明确指令。

第四段是输出格式（output format）。我建议给出一段模板，甚至直接在SKILL.md里写死几个需要用到的占位符。对于前端开发类的skills，输出代码时注明语言和文件路径；对于文案类skills，标明标题层级和字数范围。模型对“格式”的服从度，比对“内容的服从度”高得多。

第五段是注意事项（constraints）。这里写红线，例如“禁止编造引文”“必须基于用户提供的资料”“每次只处理一个文件”。我建议把最常踩的坑直接写成禁止项，因为模型和人都一样，你只说“要小心”，它不会当回事；你写“禁止”，它反而会强约束。

2.3 命名规范和放置目录

命名规范这件事，很多人不重视，但真的能省不少事。skills的包名建议全部小写字母加下划线，比如web_frontend_checker，不要用空格、驼峰和特殊字符。因为不少agent工具在解析路径时对大小写敏感，你手写路径的时候很容易因为大小写不一致而找不到文件。

放置目录方面，不同工具要求不完全一样。有的放在用户级配置目录下的skills文件夹中，有的支持项目级.agents/skills目录，还有的可以在配置里手动指定路径。我的习惯是：通用型skills放用户级目录，项目专用skills放项目级目录。这样既能在多个项目里复用通用能力，又不会让项目仓库被用不到的技能污染。

还有个容易被忽略的点：包名最好和文件夹名一致。比如你的技能叫report_writer，那文件夹也建议叫report_writer，内部入口文件叫SKILL.md。很多agent就是根据文件夹名去识别和索引技能的，命名不一致会造成“装上了但触发不了”的诡异问题。我在后面第4节会专门排查这一类问题。

3. 手把手做一个“论文写作辅助skills”

3.1 定义场景和边界

空谈概念没用，我们直接上手。我拿最近做的一个“论文写作辅助skills”当例子，全程拆给你看。首先明确使用场景：帮研究生和科研人员做文献整理、论文结构梳理、摘要润色、参考文献格式校对。这个技能是在对话中使用的，用户会贴一段文字或者给一个选题方向，技能负责输出结构化建议。

边界要提前画清楚。我在这个技能里明确写了：不做事实核查，不生成虚假引用，不代写整篇论文，不评价学术水平，只做结构、语言和格式层面的辅助。写边界这一步，很多新手会偷懒，但我建议你别省，不然AI会忍不住“越界”。我遇到过最夸张的一次是让它润色摘要，它直接给我“写”了一篇讨论结论出来，完全脱离了原文。

场景和边界想清楚了，再设计具体流程。这一步很关键，因为流程就是技能的“灵魂”。流程设计不是凭空想，我一般会先人工走一遍老流程，拆成步骤后交给AI执行。人工怎么做，AI就怎么写。你让AI模仿你的流程，永远比你自己脑补一套流程再丢给它执行要靠谱。

3.2 编写指令主体

下面我给出一个简化版SKILL.md的核心片段，你可以直接参考它改写。

--- name: paper_assistant description: > 用于辅助论文写作的技能，适合文献整理、结构梳理、摘要润色、参考文献格式校对。 当用户提到“文献综述”“论文润色”“摘要修改”“参考文献格式”等时触发。 --- # 目标 - 帮助用户优化论文的逻辑、语言和格式 - 提供具体、可操作的修改建议，而不是泛泛点评 - 输出结果时保留原文的核心观点 # 边界 - 不生成虚假引用 - 不进行事实核查 - 不代写整篇研究内容 - 不参与学术评审 # 流程 1. 读取用户当前输入，判断任务类型：结构梳理/摘要润色/格式校对/文献整理。 2. 如果是文献整理，要求用户提供文献条目或PDF文本片段。 3. 针对不同任务类型执行对应子流程（见assets/paper_workflows.md）。 4. 输出结果时，先给一段“修改说明”，再给“修改后文本”。 5. 在末尾附上一份“自查清单”，提醒用户确认核心观点未走偏。 # 输出格式 【修改说明】 - 本次修改涉及哪些部分、基于什么理由 【修改后文本】 - 文本正文 【自查清单】 - [ ] 核心观点是否保留 - [ ] 专业术语是否准确 - [ ] 引用格式是否统一 # 约束 - 每次只处理用户当前提供的一段文本，不主动扩大范围 - 所有建议使用中文输出，除非用户明确要求其他语言 - 遇到不确定的内容，明确标注“此处建议人工核对”

这个文件的写法有几个值得注意的地方。第一，没有堆砌大量论文写作知识，而是把详细规则放到了assets/paper_workflows.md里，主文件保持“指路”属性。第二，约束写得非常具体，连“每次只处理当前一段文本”都写了。第三，输出格式里加入了“自查清单”，这是一种聪明的做法——让AI自己给自己做最后一道检查，出错率会明显下降。

3.3 挂载、触发与实测

写完SKILL.md和辅助文件后，把它放进agent配置的skills目录，然后重启会话。这时候建议你做一轮“触发测试”：不要直接说“请执行论文辅助技能”，而是用平时自然说话的方式问一句“能不能帮我把这段摘要润色一下，顺便看看参考文献格式”。

为什么建议用自然方式测试？因为大多数人日常使用agent时不会喊出技能名，如果技能本身设计得好，它应该能根据语义自动触发。我在实测中发现，好的SKILL.md里description写得越具体，触发成功率就越高。一旦测试发现“没触发”，我马上就回去检查description里的关键词是不是跟用户真实表达差太远。

实测时建议准备两组输入：一组是“照着技能设计场景来的标准输入”，一组是“故意跑偏的边界输入”。比如我这个论文技能，标准输入是给一段摘要；边界输入是让它“评价一下这篇论文的学术水平”。正确的表现是：处理标准输入时顺利走完流程；碰到边界输入时，它能回应“这个超出了我的辅助范围”。如果你的技能连边界都能守得住，那基本就算合格了。

4. 实战技巧与避坑指南

4.1 为什么你的skills经常“不生效”

我在各个社区看到最多的求助帖，就是“技能装好了，但AI完全不按套路走”。这里有个朴素的道理：技能不生效，80%是因为它压根没被触发。你要先确认技能有没有真正进入agent的上下文。

我第一反应永远是检查名字和路径。如果你把文件夹叫paper-assistant，而SKILL.md里写的name是paper_assistant，有些工具就会识别异常。包括路径大小写、文件编码，都可能成为“不生效”的元凶。我建议你使用纯小写命名，并且确保SKILL.md是UTF-8编码无BOM。Windows记事本保存的默认编码常常带BOM，我就被坑过一次，最后用VS Code重新保存才解决。

另外一个高频原因就是description写得太抽象。比如写“帮助用户写作”，模型根本不知道什么时候该触发。你要写得让一个不了解背景的模型能在三秒内判断“这个输入匹配不匹配”，比如“当用户给出英文摘要并要求润色时触发”。我在多个agent上做过对比，具体化description之后，触发成功率从不到五成提升到九成以上。

4.2 上下文爆掉的应对思路

上下文窗口再大，也架不住你给AI塞一个“万言书”式的skills。我见过有人把一个技能包写得比毕业论文还长，结果每次对话一开始，AI光读技能说明就读到失忆，后面的工作全在“忘记前面内容”的泥潭里挣扎。解决方案就是我在第2节说的“延迟加载”。

具体做法是，把详细资料拆成多个小文件丢进assets目录，在SKILL.md里用“当需要处理格式校对时，读取assets/format_checklist.md”这种指令来按需加载。这样对话开始的几分钟内，AI只读主文件和必要的子文件，上下文压力会小很多。

我还会做“信息电梯式”设计：主文件提供五分钟能看完的精华版流程；子文件提供三十分钟才能看完的详细规则；更深层的数据模板、代码脚本放在备用目录。AI在大部分情况只坐电梯到二楼，很少需要到顶楼。这样既保证了输出质量，又控制了上下文消耗。

还有一个实用技巧：如果某些工具允许“分段摄取”，你可以让技能分步读取。比如第一步读完A文件开始思考，第二步读取B文件再输出。这比一股脑把所有文件全读进来要稳得多。实测下来，我的长流程技能每轮会话能省下至少三成的上下文空间。

4.3 提示冲突和模型“不听话”的解法

有时候技能本身写得很完美，但AI还是“不听话”。最常见的原因是：用户的即时指令和技能里的流程起了冲突。比如技能里写“输出格式为修改说明+修改后文本”，但用户说“直接给改好的版本就行”，模型很可能就按用户说的去做了。

面对这种场景，别急着怀疑技能写得有问题。你可以在SKILL.md的约束里加入一条“如果用户指令与本技能冲突，先执行技能流程，然后在输出开头询问用户是否需要简化输出”。这相当于给模型一个“处理冲突”的预案，它就不至于在冲突面前手足无措。

还有一种“不听话”是表现型的：技能明明说“不要编造引用”，但它还是编了。这往往不是技能写得不好，而是模型本身的固有倾向。我的补救措施包括：在技能里添加“当无法确认引用来源时，输出[引用待核实]占位符”；同时让输出模板每次自带“声明”：“本技能不保证引用的真实性，请人工核实”。模型被反复提醒之后，编造的概率会显著下降。

还有个小技巧：给步骤之间增加“检查点”。比如流程第二步结束之后，让AI先输出一个“中间结果”，等用户确认再继续。这样做虽然多了一次交互，但能防止AI在错误的道路上狂奔。尤其适合写代码、写长文案这种一旦跑偏就代价很大的场景。

5. skills生态和选型参考

5.1 去哪里找现成skills

自己从零写技能当然好，但成熟生态里已经有大量现成的skills可以用，没必要什么都从头造轮子。GitHub是最主流的聚集地，你可以直接搜“awesome skills”“agent skills”或者加上具体领域比如“前端开发skills”，通常能找到很多合集仓库。这些仓库一般附有安装说明和目录结构，照着下载到本地配置即可。

另外，一些主流agent工具自己就有官方或者社区贡献的skills市场。在这些市场里，你可以按分类浏览，比如写作、编程、数据分析、项目管理、设计协作等。安装方式一般是“一键安装”或者复制配置文件。有的平台还支持在线预览SKILL.md内容，下载前先扫一眼再决定要不要装。

下载平台之外，还有一些个人博客和社媒博主会分享自用skills包。这类资源的优点是“实战性强”，因为是个人长期打磨的成果，细节往往比官方示例更接地气，还会附带使用心得和翻车案例。我在不少“今天学会了skills”“打开新世界”这类分享帖里，就看到过非常实用的小众技能包。但也要留个心眼，下载之后把SKILL.md通读一遍，再决定要不要让它接触你的敏感数据。

5.2 怎么判断一个skills值不值得用

看到一个skills，怎么快速判断它靠谱不靠谱？我总结了三个指标：结构是否完整、描述是否具体、维护是否活跃。

先看结构。一个正规的skills包至少应该包含SKILL.md和必要的参考文件。如果只有一个孤零零的Markdown文件，也不是说一定不好，但复杂度稍高的任务往往撑不住。看作者有没有分拆assets，能看出他对“上下文控制”有没有概念。

再看描述。description写得越具体，技能通常越实用。如果一句话能让人（和AI）明白适用场景、触发词、主要动作，那就是好描述。相反，如果描述写得像广告文案，比如“强大的全能技能，提升你的效率”，这种多半是玩具。

最后看维护。GitHub上的项目看最近更新时间和Issue回复情况；社区市场看评论和下载量；个人分享看博主有没有持续玩这个方向。我自己的习惯是，优先选最近三个月内还有更新的技能包，因为AI模型更新太快，一年前的技能很可能已经不适配当前版本了。

5.3 从“用skills”到“写自己的skills”

用别人的skills一千遍，不如自己动手写一遍。因为你真正会遇到的场景，大概率是别人没考虑过的。比如你所在团队有独特的前端代码规范，比如你有自己偏爱的一套分镜描述方法，这些个性化经验很难在公开技能包里找到，自己写才是正解。

我的建议是从“记录自己的操作手册”开始。下次做一件重复三次以上的事，就把步骤写下来，标注每一步“为什么这么做”“常见坑在哪里”。当你把这条文档写成SKILL.md的结构，再补上输出格式和约束，一个属于你自己的skills就诞生了。这个过程不需要你有多深的技术背景，只需要你认真复盘过自己的工作流。

我个人的体会是，写skills真正的难点不是技术，而是“想清楚自己到底想让AI怎么干活”。很多时候你觉得自己已经在用AI了，但回头一看，每次都要重复交代背景、反复纠正输出，那就是你还没有一个成型的技能化思维。等你把三五个常用场景做成skills之后，效率的提升是肉眼可见的，而且这种积累是滚雪球式的——技能包会越来越完善，新场景也能基于旧技能快速扩展。

最后再送大家一个我自己一直在用的小技巧：定期给skills做“版本笔记”。我今天改了什么、为什么改、效果怎么样，随手记在CHANGELOG.md里。看起来只是一个小动作，但三个月后回看，这份笔记比技能本身还有价值——因为你能从中看到自己与AI协作方式的变化轨迹。