我花了一个下午想让Agent帮我整理一份项目文档结果它把上一轮对话里的错误结论又原封不动写进了新版本。气得我差点摔键盘。后来我才意识到问题不在模型而在我自己——我一直在用“聊几句”的方式指挥Agent干活却从没想过给它一份真正可复用的“操作手册”。这份手册就是当前大模型工具链里最热的概念之一Skill。Skill不是什么玄学它是将某个任务的操作流程、规则约束、输出格式和参考示例固化下来让Agent在用户不反复交代的情况下也能稳定复现一套工作方法。这篇文章会从零开始带你搞懂Skill到底是什么、它和Prompt及Agent有什么区别、在主流程具里长什么样然后手把手写一个完整的“论文初稿审阅Skill”最后分享调试过程中的真实坑点和进阶设计思路。不管你是想给日常工作流提效还是想沉淀一套个人方法论这篇文章都能给你一套能直接落地的写法。1. Skill不是提示词是给Agent的操作手册在开始动手之前先把概念掰清楚。很多人一听“Skill”就说不就是把提示词存下来吗我写个模板不就行了这个理解差了很远。1.1 没有Skill的Agent为什么总是“半吊子”用过对话式Agent的人应该都有这种体验第一次让它做某件事效果还不错第二次换个人再问它又给出完全不同的流程和结论。原因在于大模型是“无状态”的——它每次都在根据上下文重新理解任务而对话历史里的信息会稀释、会走样。你让它在第一轮“先读文件再给结论”它照做了到第十轮它可能已经忘了这个约束直接凭印象输出。更麻烦的是如果你每次都把一套复杂流程写进对话里不仅Prompt篇幅极长还容易越写越乱。我见过有人把一个“数据分析报告生成”的指令写到两千字结果模型执行时依然会在中途“自创”步骤。问题出在哪出在你给的是“描述”不是“流程”。Skill的核心价值是把“这次怎么做”升级成“每次都这么做”。它把任务流程拆成一个有边界、有步骤、有校验标准的操作方案让Agent在执行时有一个清晰的行为准则而不是临场发挥。1.2 Skill、Prompt、Agent三者的关系很多初学者问得最多的问题是skill和agent的区别是什么我的理解可以用一句话概括Prompt是“一次性的指令”说完就没了模型只能靠这一次对话里的上下文去理解。Skill是“可复用的操作手册”它把某个任务的方法、规则、示例打包成文件Agent在需要时会自动加载。Agent是“会调度的执行者”它根据用户目标判断该用哪个Skill、按什么顺序调多个Skill并在执行过程中动态调整。用一个生活化类比Prompt像你在便利店口头跟店员说“我要一杯咖啡”成不成看店员临场发挥Skill像你给店员一份SOP手册上面写着用什么豆子、水温多少、杯子多大、加不加糖Agent则是那个店长他看到客人进来会根据需求决定“这个客人适合用这套SOP那个客人适合另一套”。所以说Skill是夹在Prompt和Agent之间的“标准化中间层”。它不应该写得像Prompt那样口语化也不该像Agent那样考虑调度逻辑。它唯一的目标是把一件事的“最佳做法”讲清楚。1.3 Skill在主流工具里长什么样目前主流的代码型Agent产品包括Claude Code、OpenCode、Codex等都陆续引入了自己的Skill机制。虽然各家在目录结构和文件名上有细微差异但核心逻辑高度一致基本都是“在项目里放一个描述文件加上若干参考文件”。我以最常见的目录约定为例skills/ paper-review/ # 一个Skill就是一个目录 SKILL.md # 主指令文件写具体流程和规则 examples/ # 示范目录放参考案例 review_example1.md scripts/ # 可选放辅助脚本 check_length.py当Agent遇到一个任务时它会先扫描SKILL.md里的描述信息比如“用于审阅学术论文”判断当前任务是否匹配匹配了就加载整个目录的内容作为行为约束。搞清楚这个机制之后你会发现写Skill其实分两大块第一块是让Agent“知道什么时候用它”第二块是让它“知道怎么按要求做”。我在下一节详细拆。2. 写Skill前必须搞懂的加载机制我见过不少人上来就写SKILL.md写了一大堆结果Agent根本不触发。这基本都是在“机制”上翻了车。先花十分钟理解下面三件事能省掉后面几小时的调试时间。2.1 Skill文件的核心构成一个标准的Skill通常包含三部分元信息描述Frontmatter写在SKILL.md最顶部用键值对声明这个Skill的name、description、适用场景等。Agent就是靠这段描述来决定“要不要启用”的。主指令正文写这个Skill的执行步骤、判断规则、输出格式。这部分决定Agent“怎么做”。示范文件Examples给模型看的样例目的是让抽象规则变得具体。示范内容的质量直接影响执行效果。有个细节很多人会忽略主指令文件里通常不应该出现“我要你做什么”这种对话式表达而应该用操作手册式的祈使句比如“首先读取目标文件的前500字并提取标题”“若摘要超过300字则直接截断”。因为Agent每次触发Skill时这段文本会被当作执行规范注入上下文它需要的是一份“可以照着做的清单”。2.2 Agent如何“知道”该用哪个Skill这是Skill机制的关键。Agent在拿到用户任务后会把任务内容与每个可用Skill的description做一次语义匹配。匹配度够高它就把对应Skill加载进来匹配度不够它就当这个Skill不存在。很多人的Skill不被触发的根因就是描述写得“太虚”。比如 “这个Skill用来处理论文相关任务”——太模糊了。论文相关任务有查询、有写作、有审稿、有排版到底哪个归它管模型一犹豫就选了别的路径。我建议描述里写清楚三件事适用对象这个Skill是给什么类型的输入用的。触发条件什么场景下用户会需要它。明确排除什么情况不要用它。比如论文审阅Skill的描述可以写成“当用户提供一篇完整的论文初稿、希望获得结构化审阅意见包括章节问题、逻辑漏洞、语言问题和修改建议时使用。若用户只是询问论文写作技巧或查询文献不要使用本Skill。”这样描述匹配准确率会高很多。2.3 目录与命名容易被忽略的潜规则Skill目录的命名看起来是小事实际影响触发。多数工具会通过目录名或文件名来识别Skill建议统一使用小写字母加连字符的格式例如paper-review而不是PaperReview或论文审查。另外Skill文件不一定非要放在项目根目录。有些工具支持全局Skills目录也就是常说的“技能库”有些则要求放在当前项目的skills/或.agents/skills/下。我的建议是全局通用的技能放全局目录跟项目强相关的技能放项目目录不要把两者混在一起。还有一个小技巧给SKILL.md加上版本号写在Frontmatter里每次大改后升个版本方便日后回溯哪些调整带来了效果提升。3. 手把手写一个“论文初稿审阅Skill”概念说完了进入实操。下面我以“论文初稿审阅Skill”为例带你完整走一遍编写流程。选这个场景是因为它规则明确、步骤清晰你能清楚看到每一步设计背后的思考也能直接迁移到代码审查、方案评估、内容校对等其他任务上。3.1 第零步先确定边界再动手写很多人写Skill第一步就打开编辑器敲文字这是错的。先花五分钟回答三个问题这个Skill的输入是什么比如“一篇论文初稿格式为Markdown或PDF”。这个Skill的输出是什么比如“一份结构化的审阅意见清单含总体评价、分章节问题、修改优先级”。这个Skill明确不做什么比如“不做内容润色改写不做格式排版不提出新实验方案”。边界写清楚了后续所有流程都会清晰很多。边界模糊的Skill执行起来也是最飘的。以我的论文审阅Skill为例边界设定为输入用户提供论文初稿的完整文本或标记了文件路径的论文。输出审阅意见Markdown文档包括总体评价、摘要问题、各章节问题清单、语言问题、修改优先级。不做不直接修改论文原文不生成替代段落不判定学术价值高低。3.2 第一步写描述让Agent在正确时机拿起它前面说过描述决定了触发。这一步我直接给出一个可用的写法--- name: paper-review description: 用于对学术论文初稿进行结构化审阅。当用户提供论文全文或文件路径、并希望获得审阅意见、问题列表、修改建议时使用。若用户只是询问论文写作方法、参考文献格式或需要润色改写不要使用本Skill。 ---为什么要不厌其烦地写“不要使用”这句因为实际测试中把排除条件写进去能显著降低误触发率。模型在模糊场景下会倾向于“用工具来试试”而明确的排除说明能帮它做负向判断。3.3 第二步写主指令把流程拆到模型无法“自由发挥”主指令是Skill的心脏。我把它分成四个层次读取阶段、分析阶段、输出阶段、自检阶段。读取阶段要规定优先从哪儿读、读完之后先干什么## 执行流程 ### 阶段1读取 - 若用户提供文件路径先读取该文件并确认内容完整性。 - 若用户粘贴全文先将文本按章节拆分标注每个章节的标题。 - 若全文超过20000字先提取每章首尾段落作为精读样本。 ### 阶段2分析 按以下顺序逐项检查并将结果记录为清单 1. 摘要与正文是否一致重点对比“方法”和“结论”部分。 2. 引言是否清楚交代了研究背景、研究问题与贡献。 3. 方法部分的变量定义、实验设置、样本来源是否清晰可复现。 4. 结果部分是否包含数据支撑是否存在“只给结论不给证据”的段落。 5. 讨论部分是否与结果重复是否将“相关”表述为“因果”。 6. 参考文献格式是否统一正文引用是否都能在文末找到。 ### 阶段3输出 按固定格式输出审阅意见 - 总体评价3-5句话 - 摘要问题清单列表每条标注严重级别高/中/低 - 各章节问题清单按章节分组每条注明原文引用和修改建议 - 语言问题清单包括术语不一致、过长句子、语态混乱 - 修改优先级排序用P0/P1/P2标记 ### 阶段4自检 输出前检查一遍 - 是否给出了具体、可执行的修改建议而不是仅指出“表达不清” - 每条问题是否附带了原文引用方便用户定位 - 是否遗漏了“摘要与正文一致性”这一项这段主指令的写法有几个关键技巧。第一所有的“检查项”都用动词开头比如“对比”“检查”“是否包含”这比“应当关注”这种模糊表述更容易被模型遵循。第二把“具体可执行”写进自检规则能明显提升输出质量——如果你不写模型很容易输出大量“本文表达不够清晰建议优化表达”这种废话。第三用P0/P1/P2这种标记给修改建议排优先级让用户拿到意见后能立即分配精力。3.4 第三步给一个“满分作业”当示范大模型是Few-shot学习者给它看一个高质量示例比写十句抽象规则都管用。示范文件不需要很长但一定要“标准化”一个典型的审阅意见长这样## 示例摘要问题清单 - [高] 摘要中提到的“准确率提升12%”在正文实验部分找不到对应的基线和对比设置。 原文引用摘要第3行“准确率提升12%”。 修改建议在实验部分补充基线模型的具体配置或在摘要中删除具体数值。 - [中] 摘要未明确样本总量。 原文引用摘要第4行“在公开数据集上进行了实验”。 修改建议写明数据集名称和样本数量便于读者判断实验规模。 - [低] “鲁棒性”一词在摘要和方法部分定义不一致。 原文引用摘要第5行“验证了模型鲁棒性”方法部分第2段“通过添加噪声验证鲁棒性”。 修改建议统一术语并在方法部分补充鲁棒性评价指标。我在实际使用中发现示范文件不用多两三个典型案例就够。关键是要覆盖不同的严重级别和不同的问题类型让模型在输出时能顺着示例的“口吻”走。如果你只想写一个示范那就写“包含高/中/低三级问题、且每条都带原文引用和修改建议”的完整样例。3.5 辅助脚本当纯文本不够用的时候有的Skill需要跑脚本做客观检查比如论文里术语一致性就可以用脚本扫。设计辅助脚本时记住一句话脚本负责确定性检查模型负责语义判断。能交给脚本的不要靠Prompt硬聊。比如给论文审阅Skill配一个简单的术语检查脚本逻辑是读取全文、找出“模型”和“算法”混用的地方并输出位置。脚本本身不判断对不对只是把可疑位置标注出来最终判断权留给模型。这样做的好处是把“模型容易忽略的机械性工作”交给程序模型就能把注意力放在它真正擅长的语义分析上。4. 调试Skill的完整链路从“不触发”到“乱执行”写Skill的理想状态是一遍过但现实往往要磨好几轮。我把自己踩过的调试链路完整分享一下你遇到问题时可以直接对号入座。4.1 第一轮Skill根本没被触发现象是你明明把SKILL.md放在正确目录描述也写了但Agent就像没看见一样继续用默认方式回答。先检查三件事文件路径是否正确。有些工具要求Skill放在项目特定目录你放在别处它根本扫不到。描述是否够“具体”。前面说过的匹配机制描述写得太泛模型会认为不匹配。处理文件是否存在。如果你的Skill是用来处理某个特定文件类型的而用户没给文件Agent也可能跳过。我遇到最多的是第一种。很多工具在启动时才会加载Skills目录你新加一个Skill后不重启怎么试都不触发。这不是逻辑问题是流程问题。4.2 第二轮触发了但步骤执行混乱Skill被触发了但你发现它没按主指令的顺序来。比如我要求“先分析摘要再分析正文”它却直接跳到结果部分开始评。这通常是因为主指令的步骤“不够强制”。我后来养成的习惯是在主指令开头加一句“严格按照以下顺序执行不要跳步、不要并步”然后在每个阶段之间加“完成上一阶段后再进入下一阶段”。听起来很笨但对模型有实际约束力。还有一种情况是步骤太多。如果一个SKILL.md里写了超过八个步骤模型很容易丢三落四。我建议把步骤控制在五步以内实在复杂的拆成两个Skill或者用“检查清单”的方式压平。4.3 第三轮输出格式不对最折磨人的是格式问题。模型有时会自作主张改输出格式比如要求Markdown表格它给出列表要求列表它给出一段话。针对这一点我建议在SKILL.md里直接放一个“输出模板”开头写“你的输出必须严格使用以下模板不得增删层级”。## 输出模板 # 审阅意见 ## 总体评价 此处写3-5句话 ## 摘要问题清单 | 严重级别 | 原文引用 | 问题说明 | 修改建议 | |---------|---------|---------|---------| ## 各章节问题清单 ### 章节名 列表每条包含严重级别、原文引用、修改建议把模板直接放进Skill里比你在对话里反复纠正要有效得多。模型在生成时能看到一个“最终形态”输出稳定性会大幅提升。4.4 调参的边界感别把Skill写成“大而全”调试到后面很多人会陷入一个误区为了让Skill更准确不停往里塞规则最后SKILL.md变成一部长篇巨著。我见过有人把一个“数据分析Skill”写到五千字规则密密麻麻结果执行时模型反而不知道该重点执行哪条。Skill的设计哲学和代码一样单一职责。一个Skill只做好一件事。如果你发现自己在一个Skill里既要审稿又要润色还要查重正确做法是拆成三个Skill而不是一个写满所有。调试的时候记住一个“稳定优先”原则每次只改一个变量。比如这一轮只改描述语让它更容易触发下一轮只改输出模板让它格式更统一。混着改出了问题根本定位不到是哪个改动引起的。5. 从“能用”到“好用”Skill的进阶设计思路当你写出第一个能稳定工作的Skill后面就是优化和延展的事了。这一节分享几个进阶方向都来自我自己的实践。5.1 让Skill“记得”上下文内建记忆字段有些Skill需要在多次执行中积累信息比如“写项目周报”这个技能需要知道上周的事、这周的事、下周的计划。如果每次都是用户临时输入用起来很累。一个实用做法是在Skill目录里放一个state.md文件专门存储跨次执行的状态信息。主指令里写一条规则“每次执行前先读取state.md执行完成后将本次新增信息合并回state.md”。这样Skill就具备了简单的“记忆能力”每次输出会更连贯。5.2 多Skill协作让Agent当调度员更进阶的玩法是把一些强相关但职责不同的Skill组织起来形成一个工作流。比如写论文这个场景可以拆出“文献检索Skill”“论文初稿审阅Skill”“参考文献格式化Skill”。Agent接到一个综合任务时会按顺序调用这些Skill实现流水线作业。这其实就是Skill和Agent协同的典型模式。Skill本身不需要知道其他Skill的存在它只需要把自己那一环做专业Agent负责判断先调谁、后调谁、每个技能的输出怎么喂给下一个。所以写Skill时不要写“如果前面格式整理已完成”这种和别的技能耦合的假设保持技能间互不可见才能让Agent有足够的调度灵活性。5.3 把Skill变成资产版本管理与分享Skill的价值在于复用。我在维护自己的技能库时都会用Git管理每个Skill独立成目录Frontmatter里带上版本号。每次效果有明显提升就升一个版本并在README里写清楚这一版改了什么。现在GitHub上已经有大量开源的Skill技能库涵盖编程、写作、研究、数据分析等方向。我的建议是先参考优秀开源Skill的写法理解别人是怎么拆步骤、怎么定边界的然后把自己日常最高频、流程最固定的操作沉淀成Skill。因为Skill的本质是方法论的固化它真正值钱的地方不是那几个文件而是你脑子里那一套经过验证的操作流程。写Skill的过程其实就是逼着自己把流程想清楚的过程。从0到1写出第一个Skill最难的不是语法不是格式而是思维方式的转换别再像写Prompt那样“跟模型对话”要像写SOP那样“给模型定规矩”。我在跑通第一个论文审阅Skill之后最明显的感受是Agent的输出质量不再是“看运气”而是可预期、可复现的。这种从“能用”到“好用”的差距不大但很关键。