这段时间我翻了不少 Skills 项目说句得罪人的话社区里八成以上的“Skills”本质就是一段 Prompt 换个后缀连及格线都没到。自从 Claude Code、Cursor、Codex 这些工具陆续把 Skills 变成“一等公民”好像一夜之间人人都在写技能包。可真正能稳定干活、能跨对话复用、能让同事接手维护的少得可怜。无论是做 LaTeX 排版、Word/PPT 处理、图片生成还是数学建模辅助大家踩的坑其实同源。这篇文章我不讲漂亮理论就说说我从“提示词”走到 SKILL.md 之后沉淀下来的写法和踩过的坑适合准备认真写技能包、又不想只是把提示词丢进去的开发者。1. 别再拿 prompt 冒充 Skills 了1.1 从“一句话提示”到“能力包”中间差了什么Skills 的本意是给 Agent 一个“可复用的能力单元”。普通 Prompt 是你每次都要把话说全模型理解靠当场发挥Skills 则是把流程、规则、示例、输出格式全部提前固化成一份结构化文档让 Agent 在需要的时候自动加载并按流程执行。这就像你给实习生一份岗位手册而不是口头交代一句“你好好干”就完事。具体到实现层面主流工具基本收敛到同一套玩法在一个skills目录下放一个SKILL.md用 frontmatter 记录名字和描述用正文写完整操作逻辑。Claude Code 认.claude/skillsCursor 认.cursor/skillsCodex 也有自己的 skills 目录。虽然有细微差别但写法内核一模一样。为什么我要强调“差得远”因为我见过太多 SKILL.md 就是一句“You are an expert in Python”这除了让模型给自己贴个标签之外什么都保证不了。及格线意味着它必须像代码一样可以被测试、被维护、被复用而不是一段随缘生效的咒语。你看那些真正好用的“图片生成 skills 安装包”“latex 排版 skills”打开里面的 SKILL.md几乎都是结构清晰、有约束、有示例、有自检清单的完整文档而不是几行灵感式提示词。1.2 及格线好 Skills 的五个判断标准我自己的验收标准有五个任何一个不达标我就不会往仓库里提交。第一描述精准。模型靠 description 判断什么时候调这个技能写太宽容易误触发写太窄该触发时不触发。第二步骤可执行。正文里的任务拆解要细到模型“不用自由发挥也知道下一步做什么”。第三输出可复用。最好输出固定格式能直接接入下一步流程。第四边界清晰。技能只做自己该做的事不越权乱改其他文件。第五可维护可测试。有版本、有示例换一个模型版本也不至于突然失灵。我列一张表对照一下不合格、合格、优秀三种状态大家可以对号入座维度不合格合格优秀描述一句“帮我写代码”写了触发场景和输入要求写明触发条件、输入输出关系、不宜触发的情况流程只有目标没有步骤有步骤但很粗有顺序、有判断分支、有兜底输出自由格式有固定结构有模板 校验清单边界能做任何事简单说明不要做什么明确可操作范围和禁止项可维护没有示例带一个示例带示例、常见错误、版本说明你看很多项目能在“描述”和“边界”这两栏拿到合格就已经超过大部分人了。至于优秀那是持续迭代出来的结果不是第一版就能到的高度。2. 写一个能过及格线的 SKILL.md2.1 元信息name 和 description 是命门在 SKILL.md 的 frontmatter 里最核心的就是name和description。name是技能唯一标识系统会用它来做文件索引和上下文引用。我建议 name 尽量短小精确用连字符分隔比如paper-zh2en不要叫ai-agent-super-tool这种看起来无所不能的名字。名字一旦失控后续维护和排查都会很痛苦。description 更关键因为 Agent 的“路由”基本靠它判断。很多人写 description 特别喜欢用宏大叙事比如“帮助用户解决所有编程问题”。这种话等于没说。我推荐用“当用户需要 X输入包含 Y并且不适合用 Z 时使用此技能”这种模板来写明确触发、输入、边界。这里我举个真实对比不合格翻译文档的工具合格当用户需要把中文论文摘要、引言或正文翻译成英文或要求“中译英”“English version”时使用。输入最好包含原文或文件路径。不适合翻译日常口语、营销文案。第二种写法最大的价值是给 Agent 一个明确的“决策树”。它看到用户说“把这段摘要翻译成英文”就能确定该调哪个技能看到用户说“帮我写一段英文广告语”就知道这个技能不该插手。2.2 正文结构目标、约束、流程、质量检查一个都不能少正文我习惯固定分六块Goals目标、Constraints约束、Workflow工作流程、Output Format输出格式、Examples示例、Self-Check自检清单。这样写的好处是模型阅读结构化文档的效率远高于读一段散文。它知道目标是什么也清楚必须遵守哪些约束然后按流程执行最后还能对照自检清单检查结果。其中 Constraints 特别重要。你要告诉它禁用词、不要做的事、必须保留什么、不能改什么。比如“翻译技能必须保留论文的公式和参考文献编号”这就是约束。没有约束技能越到后面发挥越离谱可能把公式也翻成英文把引用编号当成正文处理掉。Workflow 要写成“第一步做什么产生什么中间结果第二步基于该结果做什么”。这里我会加入输入模板让模型先整理输入再动手。比如先让它把原文分段、标出公式和引用再开始翻译而不是拿到原文就直接一口气输出那样很容易丢格式。3. 手把手实操做一个“学术论文中译英”的 Skills3.1 目录与文件组织实操示例我就选一个搜索热度很高的场景把中文论文摘要、正文翻译成英文。这个任务看起来简单但直接交给 Agent 翻译出来的东西经常很“AI味”术语不一致格式丢失。所以我把它做成一个 Skill把术语表、翻译流程、输出模板全部固化下来。我的目录结构是skills/ └── paper-zh2en/ ├── SKILL.md └── glossary.mdglossary.md是术语表放必须固定的专业术语翻译比如“深度学习”统一用“deep learning”、“大语言模型”统一用“large language model”。这样 Agent 在翻译时会自动参考这个文件避免同一篇论文里出现多种译法。如果你的技能只涉及单一领域这个文件可以很小如果跨领域可以考虑拆成多个术语文件。3.2 完整 SKILL.md 源码下面是我实际在用的精简版 SKILL.md你可以直接复制改--- name: paper-zh2en description: 当用户需要把中文论文摘要、引言或正文翻译成英文 或要求“中译英”“翻译成英文”“English version”时使用。 输入最好包含原文或文件路径。不适合用来翻译日常口语、营销文案。 --- ## Goals 将中文论文内容翻译为英文保留术语一致性、学术语气和原意。 ## Constraints - 不得翻译公式、图表标题、参考文献编号 - 保留 Markdown/LaTeX 格式 - 不扩写、不删减原文内容 - 专业术语必须参考 glossary.md - 输出英文学术语体避免口语化表达 ## Workflow 1. 读取输入定位中文正文与需要保留的部分 2. 读取 glossary.md建立术语映射 3. 逐段翻译每段先保留原意再调整语序 4. 对照原文检查漏译、多译 5. 输出格式化结果 ## Output Format 输出英文译文若原文超过三节按标题结构分段输出。 翻译完成后追加一行 术语核查结果列出实际使用的高频术语与译法 ## Examples 输入本文提出一种基于Transformer的... 输出This paper proposes a Transformer-based... 完整示例略 ## Self-Check - [ ] 是否有被误译的公式/编号 - [ ] 术语是否与 glossary.md 一致 - [ ] 是否丢失段落结构 - [ ] 是否出现明显机翻痕迹3.3 逐步拆解设计思路name 我用paper-zh2en一眼能看懂也便于日志里定位。description 里带上了英文指令的常见说法因为 Agent 识别触发不只是看中文它要理解用户意图。比如用户说“translate this abstract into English”如果描述里只有中文触发词很多工具就无法把它连接到这个技能上。Workflow 第 2 步读术语表是容易被忽视的点。很多人把术语直接塞进 SKILL.md 正文结果技能文件越长模型反而越容易糊涂。拆成单独 glossary 文件更清爽也方便其他技能复用同一个术语表。我试过把五个翻译相关技能都指向同一个 glossary效果比每个技能各写一套术语好得多。Self-Check 是很多人会省掉的。实际上这是稳定性的关键它等于给模型加了一道“提交前检查”能大幅减少漏译和术语漂移。我实测下来加了自检清单之后同一测试用例跑八次输出结构一致性从大约一半提升到了八成以上。加载方式方面不同工具略有差异。以我的经验最简单的是把skills/paper-zh2en整个目录放到工具约定的全局 skills 目录下然后在对话里直接说“把这段摘要翻译成英文”。如果是项目级使用就在项目根目录建.cursor/skills或.claude/skills之类的目录。需要注意目录约定千万别记混放错位置技能不会报错只是永远不会被加载。4. 实测后我踩过的坑Skills 不生效的常见原因4.1 “它没理我”触发条件写崩了最常见的坑是描述写得模糊。我一开始写的是“帮助用户翻译文档”结果用户说“帮我写一段英文简介”它也会加载说“把这段摘要翻成英文”反倒不加载因为描述里没有明确“摘要”。后来我把 description 改成列举触发场景的写法情况才稳定。排查方法很笨但很有效打开工具的运行日志看每次请求有没有加载这个 skill。没加载就回去改 description别靠猜。我见过有人反复改正文内容结果问题根本不在正文而是描述没写好导致技能压根没被唤醒改了半天一点用没有。4.2 “它乱动了”边界与授权没写清没有清晰边界时Agent 会做很多多余的事。比如我早期的翻译技能会在翻译后主动帮用户重写摘要、顺手润色其他段落听起来挺贴心实际很烦人因为用户没要求。有时候它还会自作主张把参考文献格式改掉这在一篇准备投稿的论文里是灾难。解决办法是在 Constraints 里写明“不扩写、不删减、不改动非指定内容”。所有多余行为都要在约束里禁止掉否则大模型发挥起来你没地方说理。我把这个教训总结成一句话Skills 是工具不是助手。它应该精准执行任务而不是试图揣摩用户“没说出口的意图”。4.3 “它今天一个样明天一个样”怎么稳住输出模型输出不稳定常见原因是流程节点没拆到位。有了完整 workflow 和 output format 之后结果稳定性会明显提升。再配合 Self-Check效果更明显。我跑同一个测试输入十次合理的技能应该八次以上输出结构一致。如果你发现技能输出“时好时坏”先别急着骂模型。大概率是某个步骤描述得不够具体。比如“检查术语一致性”和“对照 glossary.md 逐词检查术语一致性”是两回事后者给模型的指令更明确执行结果自然更稳定。4.4 多工具共用、版本管理与团队协作Skills 本质是文件天然适合 Git 管理。我的做法是把所有技能放在一个独立仓库不同项目里用软链接或配置文件指向同一个 skills 目录这样 Cursor、Codex、Claude Code 之类的工具能共用。CodeBuddy 和 Claude Code 共用 skills 目录只要让它们的技能路径指向同一个文件夹即可。但每家工具对子目录的约定略有差异测试时要逐家验证。我吃过亏以为通用路径能通吃结果某工具死活不加载查了半天才发现它只认自己的专用目录。版本管理上我强烈建议给每个 SKILL.md 加一个版本号字段并在 README 里写 ChangeLog。别看 SKILL.md 是一个文本文件它也会随着你的使用不断演进。没有版本记录过三个月自己都分不清哪个版本更稳定。我做了一张排查速查表遇到问题可以先对照现象可能原因对策技能完全不触发description 未覆盖用户表达扩写触发词和场景误触发不该用的时候加载了描述边界写得太宽补充“不适合使用”的情况输出了但格式很乱缺少 Output Format定义固定模板流程跳跃、步骤缺失Workflow 写得太粗每个步骤拆到最小可执行单元术语混用没绑定术语表增加 glossary 并在约束中引用同一个输入两次输出差异大缺少 SELF-CHECK加入自检清单并强制执行5. 从哪学、怎么持续提升 Skills 水平5.1 拆解优秀开源项目如果你刚开始接触我建议去社区搜“awesome claude skills”这类合集挑几个高 star 的仓库把 SKILL.md 一篇一篇读过去。重点不是看它写了多少行而是看几个关键信息描述是怎么写的触发粒度粗还是细正文分段结构是什么有没有自检清单示例是真实场景还是为了凑数配套资源文件是怎么组织的。我拆解过不下五十个技能包留下最深印象的不是那些功能最花哨的而是那些“收敛得很好”的。什么叫收敛就是这个技能只解决一类问题解决方案固定输出格式固定。它尊重 Agent 的上下文窗口不把所有东西都塞进一个文件而是用目录和资源文件把复杂度拆开。另外留意一下打包规范。有些项目会把 Skills 打成独立安装包内置依赖说明和目录结构说明。你可以模仿这种组织方式至少写一个 README 说明技能边界和版本方便团队接手。5.2 建立自己的评测集这是我感受最深的一点写 Skills 和写测试用例很像。我会准备一个评测文本里面放 3 到 5 个固定输入包含典型场景、边缘场景、容易误触发的场景。每次改进技能就统一跑一遍记录输出是否合格。别看这个动作简单它能阻止你“调一次觉得好了就收手”的冲动。具体打分的维度包括是否触发正确、输出结构是否合规、术语是否一致、约束是否被遵守、运行时间是否可接受。我一般用一个表格记录简单粗暴但非常有效。关键是这套评测集要随着技能演进不断补充每次遇到新的失败案例就把它加进评测集里避免同一个坑踩第二次。有条件的话还可以给每个技能写一个“已知限制”文件。没有十全十美的技能明确写出它不擅长的场景能帮自己和团队省下不少试错时间。最后说一点我个人的体会。Skills 不是写一次就完事它是一个持续迭代的“手艺活”。我见过太多人写完第一版就丢进仓库再也不管然后跑来抱怨模型不行。其实模型没变是你的技能文档没有跟上实际使用中暴露出来的新问题。把这篇文章里的方法用起来描述写精准、流程拆到最小、约束写到显式、输出固定格式、自检变成流程的一部分再配一套自己的评测集。今天就可以找一个你每天都在做的重复性任务把它写成第一个真正及格的 Skill。那些“差一点点就及格”的文档改一改马上就是不一样的东西。