1. 为什么我敢说你写的Skill不及格先说三个通病过去大半年里我前前后后翻了不下上百份别人写的Skills——有从GitHub上扒下来的有朋友私信让我帮忙看为什么模型不调用的也有各种群里号称一键生成PPT/一键写论文的技能包。说句得罪人的话能真正达到及格线的真的不多。大部分Skill处于一种看着很努力用着很崩溃的状态。先说结论Skills不是提示词套个壳也不是把工作流写成一堆文件夹就完事。很多人的理解停留在把一段提示词存成md文件起个名字就变成Skill了。这种认知偏差导致写出来的东西模型既不主动调用调用也跑不出预期结果。我下面拆的三个通病基本覆盖了90%的失败案例。通病一只有想让它做什么没有它应该在什么情况下出现。一份SKILL.md的frontmatter里description字段是模型决定要不要唤起这个技能的唯一依据。可我看到太多人这么写description: 这是一个写报告的技能可以让AI写一份专业的报告。这个描述翻译成人话就是当用户想写报告时用我。问题是用户可能说帮我整理一下调研内容也可能说把这个会议纪要扩写成文档——这些都属于写报告的模糊范畴模型拿不准该不该调用你这个Skill。而如果description写得太宽泛模型就更倾向于强行套用导致无关场景也触发最后生成一堆文不对板的内容。写description至少要覆盖四件事明确的触发场景、输入需要什么、输出大概长什么样、哪些情况不要用。比如description: 当用户需要把中文论文翻译成英文投稿稿件时使用。输入为Markdown或LaTeX格式的论文输出为术语一致、保留公式与引用的英文版本。如果用户只是翻译几句话请勿调用本技能。这样的描述模型在任何一次翻译论文相关的对话里都能精准命中而且不会在闲聊式翻译里胡乱触发。通病二步骤写得太抽象模型照做必翻车。SKILL.md正文里如果只写第一步理解用户需求第二步生成大纲第三步撰写内容那这个Skill基本等于没写。因为模型平常不做Skill也能做到这些你的Skill反而多了一层包装根本没啥意义。合格的Skill正文每一步都得是可执行的动作读哪个文件、产出哪个文件、校验什么内容、遇到冲突怎么处理。步子越细模型执行越稳。后面会有详细的示例这里先记住一句话Skill里的每一步都要让模型不需要发挥就能执行。通病三没有退出条件模型不知道什么时候算完。不少Skill让模型完成xxx后继续优化结果模型永远在续写、扩写、自我修改最后交出一份冗长且没用的输出。真正好的Skill会在末尾写明当满足A和B条件时停止输出最终文件。这三个通病叠加在一起就是大多数Skill下载下来没什么用的原因。下面我从骨架、平衡、演进、选库、场景五个方面把及格线以上的Skill到底该怎么写完整捋一遍。2. 及格线第一条线SKILL.md的骨架不是说明书是操作手册一个Skill通常就是一个文件夹里面的核心文件叫SKILL.md。Claude Code、Codex、OpenCode这些工具约定俗成地会去读取这个文件根据frontmatter里的description判断是否调用。所以SKILL.md的写法直接决定了这个Skill的下限。2.1 frontmatter决定模型会不会用你frontmatter是文件顶部的YAML区域写name和description两个字段。很多公开库还会加allowed-tools、model等字段但至少前两个必须有。name要简短好记最好用连字符风格比如latex-article-format、math-modeling-draft不要用中文长名避免不同工具解析出错。description是重头戏。我建议按这个模板写--- name: translate-paper-en description: 将中文论文Markdown/LaTeX翻译为英文投稿版本保留公式、图表引用与参考文献格式确保术语一致。适用于完整论文的翻译场景单句翻译或口语化翻译不适用。 ---注意什么场景不适用这一句很多人忽略但它恰恰能救你。模型在模糊对话里看到这句就不会强行触发误用率会明显下降。2.2 正文步骤要细边界要清正文部分我见过两种极端一种是一大段散文式描述另一种是一堆嵌套Markdown标题像算法题解。都不好用。推荐的结构是目标声明一句话说明这个Skill完成什么任务输出物是什么。输入要求需要用户提供什么缺了怎么办比如如果用户没有提供源文件路径先问清楚再开始。执行步骤用有序列表每一步都包含动作、对象、判断标准。边界与兜底哪些情况不处理出错时怎么回退。退出条件满足什么条件后停止并汇报结果。举个我实际在用的例子一个用于整理代码仓库的Skill骨架--- name: repo-tidy description: 当用户需要清理/重构当前代码仓库的目录结构、删除无用文件、补充README时使用。仅适用于本地已有项目不适用于新建项目。 --- # 目标 整理仓库结构产出 README.md 和目录说明文档。 # 输入要求 - 确定要整理的仓库路径如果路径不存在结束并提示用户。 # 执行步骤 1. 用文件列表命令扫描仓库根目录记录顶层文件和文件夹。 2. 识别明显的临时文件如 *.tmp、*.log、dist/、node_modules/ 中未提交内容列出待删除清单。 3. 将清单展示给用户获得确认后再删除不要擅自删除任何文件。 4. 为剩余目录生成一份 tree 结构描述写入 docs/structure.md。 5. 检查仓库是否已有 README.md若没有根据目录结构撰写一份覆盖安装、启动、目录说明的 README。 6. 完成后报告扫描了多少个文件、删除了什么、新增了什么。 # 边界 - 不处理 git 历史、不修改 .gitignore 之外的文件忽略规则。 - 如果仓库没有 git 初始化先提示用户初始化。 # 退出条件 README.md 与 docs/structure.md 已生成且删除操作经由用户确认视为完成。这个Skill里面每一句都是可执行动作模型不会猜。我每次看到那种只有分析仓库结构并优化一句话的Skill都想叹气——那不是Skill那是愿望。2.3 为什么步骤越细模型越稳定很多人觉得步骤细了会限制模型的灵活性。其实不会。Agent模型每次执行都是在生成token每走一步都要做决策。如果步骤里留了太多开放空间模型就把决策成本摊在你每次使用的过程中结果就是这次一个样、下次另一个样。把决策前置到SKILL.md里相当于把随机过程变成确定性流程这才是Skill存在的意义。反过来步骤也不能细到让模型读起来像读代码。每步控制在动作对象判断三个要素以内写太长同样会失焦。3. 及格线第二条线在模型思考和脚本执行之间找到平衡一个Skill只有md文件没带任何脚本或模板那它的能力上限基本就是在对话框里给你打一段字。可很多高频场景——批量处理文件、解析JSON、抓取网页结构、批量重命名——根本不适合让模型一步步在聊天框里折腾。3.1 什么时候该写脚本什么时候该让模型自己想我判断的标准就一条这事儿是不是重复性、确定性操作如果是交给脚本如果涉及判断和语义理解留给模型。比如说一个把Word文档转成Markdown的Skill如果让模型自己去解析Word二进制格式它大概率会出错或者胡编内容。正确做法是Skill里内置一个Python脚本调用pandoc或python-docx把转换做好SKILL.md里只写调用scripts/convert_docx.py将结果写入目标路径。反过来像帮用户判断这个段落是不是在表达核心结论这种语义活儿就别硬写成规则模型的判断力在这里才是价值所在。3.2 脚本和SKILL.md怎么配合才最顺我在自己的Skills里总结了三条规定脚本只做一件事。哪怕看起来很简单也不要在一个脚本里塞解析转换发送。任何一个环节出错模型很难定位。输入输出尽量走文件不要走长字符串。模型调用脚本时最好传入文件路径产出也写到文件里然后再读取结果。通过命令行传超长文本很容易截断还污染上下文。脚本要幂等、可重跑。同一个输入跑两次结果应该一致且不会覆盖用户已有文件。Skill里被反复唤起时脚本干净很重要。下面是一个简单到不能再简单的示例演示图片尺寸批量整理Skill里脚本和说明文档的分工# scripts/resize_images.py import sys from pathlib import Path from PIL import Image folder Path(sys.argv[1]) max_side int(sys.argv[2]) if len(sys.argv) 2 else 1024 for img_path in folder.glob(*.png): im Image.open(img_path) w, h im.size if max(w, h) max_side: continue ratio min(max_side / w, max_side / h) im.resize((int(w * ratio), int(h * ratio))).save(img_path)SKILL.md里对应的那一步就写运行python scripts/resize_images.py 图片目录 最大边长脚本会原地缩放超过最大边长的PNG图片。模型只需要理解这个步骤在干什么具体计算交给脚本。这种配合比让模型想象自己做了图像处理要可靠得多。3.3 没有脚本的Skill更容易是提示词幻觉我拆过很多公开的高级Skill里面通篇是利用深度学习技术分析用户需求智能化生成高质量内容这类空转表述。这种Skill跑起来完全依赖模型的临场发挥跟直接把需求贴在对话框里没区别。带脚本、带模板、带参考文件的Skill才是真的在扩展Agent的能力边界也才称得上及格。4. 从提示词到Skill一条能照做的演进路径聊完理论我想给你一套我自己反复使用的路径照着走基本不会跑偏。这套路就是从最原始的提示词开始一步步固化成Skill而不是一上来就凭空搭文件夹。4.1 第一步先在普通对话里把流程跑通不要急着写SKILL.md。先找一份真实任务用普通对话让模型做一遍。注意观察它哪些地方做得好哪些地方总在反复。比如你想做一个数学建模比赛选题分析的Skill就先丢一个赛题给模型看它怎么拆问题、怎么选方法、怎么生成本文。多跑几次把每次的优劣记录下来。4.2 第二步把跑通的动作提炼成固定步骤当你在对话里发现每次都要手工告诉它先做A再做B的时候这些A和B就是要固化的步骤。把它们按执行顺序列出来每步配上输入和产出。这一步其实就是写SKILL.md正文的草稿。4.3 第三步把不确定性拆出去写进边界和退出条件哪些地方模型容易发挥过度比如让它搜索可能合适的模型它可能列出几十个让用户无从选择。那你就在边界里写只对比三种主流方案并给出推荐不展开穷举。哪些地方它容易提前停比如没说要给出伪代码就不给——那就在步骤里明确第4步必须输出核心算法伪代码。4.4 第四步固化file加入脚本和模板草稿稳定之后再建文件夹放SKILL.md把脚本、模板、示例文件一并塞进去。最后把description按前面说的四要素打磨一遍。这个顺序很重要因为脚本和模板是照着已经稳定的流程写的而不是反过来让流程迁就脚本。4.5 第五步用三个刁钻问题测它一个Skill写完不叫完至少要过三个测试不触发测试用户聊着无关话题看它会不会误触发。被误触发说明description边界不清。缺参测试用户不给关键输入看它会不会及时追问而不是自己脑补。路径测试让它处理一份真实文件而不是一份理想格式的样例。真实世界的数据永远比样例脏处理不了就说明步骤太理想化。这三关都过了Skill才算到及格线。我自己写的前十几个Skill基本都挂在了第一关——description写得不够精准聊别的也能被调起来后来才慢慢摸到窍门。5. 别闭门造车筛选外部Skills库的几个硬指标现在网上Skills仓库很多GitHub上awesome-claude-skills这类资源列表也不少还有人喜欢收集Superpowers这种成体系的技能包。但下载到本地和能派上用场是两回事。我筛选外部库的时候几乎不看标题吹得有多神只核对下面几个硬指标。5.1 目录结构是否完整一个正经Skill至少要有SKILL.md最好还带scripts/或assets/。如果仓库里只有一堆md文件、没有脚本没有模板先打折。再看文件夹命名是否清晰一个文件夹装多个不相关Skill的直接跳过。5.2 description是否经过打磨打开SKILL.md看frontmatter。如果description写的是这是一个处理文档的Skill说明作者压根没考虑模型的触发机制如果description写了明确场景、输入输出和不适用场景哪怕功能很小也说明作者真的在用。这个指标比看star还准。5.3 是否有实际使用痕迹看两点一是README里有没有作者自己跑过的示例输出二是issues里有没有人反馈过具体问题。一个没有人反馈过问题的仓库并不代表它好很可能根本没人用过。5.4 如何正确安装不同工具的skills目录安装Skill其实没有那么多玄学本质都是把文件夹放到工具约定的目录里。以最常见的几个为例Claude Code个人级放在~/.claude/skills/项目级放在项目下.claude/skills/也可以直接用mcp相关功能做更复杂的接入。Codex一般放在~/.codex/skills/或项目下.codex/skills/。OpenCode位置类似通常在~/.config/opencode/skills/或项目下.opencode/skills/。Cursor新版本有自己的skills目录也可以检查官方文档里对.cursor/skills/的说明。手动装GitHub上的Skills就是git clone到对应目录git clone https://github.com/某用户/某skill /目标目录/某skill装完重启工具或新建会话让配置重新加载然后直接说一句能触发场景的话测试效果。5.5 关于多个工具共用一套Skills的实操建议很多人想让CodeBuddy、Claude Code这类工具共享同一个技能目录省得每换一个工具就重复安装一遍。思路是没错的但我试下来最稳的方案不是直接改路径配置因为不同工具对Skill文件夹的解析方式有差异有的认SKILL.md里的name有的认文件夹名硬指向同一个目录容易出问题。我比较推荐的做法是把公共Skills放在一个工作目录里比如~/shared-skills/然后用软链接指到各个工具的skills目录下。例如ln -s ~/shared-skills/latex-article-format ~/.claude/skills/latex-article-format这样你更新公共目录里的内容各工具实际都能读到。用之前记得先小范围验证一次别因为个别工具解析路径的方式不同弄出装完不生效的尴尬。5.6 定期给Skills做减法社区里有经验的用户经常会讨论怎么清理Skills——别舍不得删。模型每次判断是否调用Skill是要读取description做匹配的。如果装了上百个描述模糊的Skill反而是给模型制造噪音触发更加混乱。我给自己定的规矩是一个月清理一次连续两周都没被调用过的Skill先移到disabled目录观察再没动静就直接删。把常用的精留比堆一堆可能用得上的更有价值。6. 几个高频需求场景的Skill写法参考最后结合最近的搜索热度和大家的日常诉求我挑几个高频场景说说这些Skill的设计思路。不一定给你完整代码但思路足够你照着搭出一份及格线以上的作品。6.1 中文论文翻译成英文的Skill这个场景搜索量一直很高难点在于术语一致、公式和引用不乱。Skill设计上别让模型直接一句句翻译而是拆成四步用脚本解析源文档分离正文、公式LaTeX格式和参考文献区。让模型先提取全文术语表固定每个术语的译法。再按术语表逐节翻译正文公式和引用原样保留。最后用脚本校验参考文献条目有没有丢公式标记有没有被破坏并生成翻译后的完整文档。加一个校验脚本是关键否则模型翻译完经常悄悄把引用编号改改或者丢掉几个反斜杠整篇投稿稿就废了。6.2 LaTeX排版Skill数学建模、论文投稿场景里xxx怎么做一个LaTeX排版Skill被反复问。我的建议是把排版拆成格式校正和编译验证两条线。格式校正类操作交给模型判断——比如作者信息区应该放在标题下方、摘要之前这类规则但编译验证必须走脚本——跑一遍latexmk或pdflatex把报错信息返回给模型修复。没有编译回调的LaTeX排版Skill本质上就是在教模型猜LaTeX长什么样不靠谱。6.3 数学建模/竞赛用Skill数学建模类Skills的搜索量一直很猛比如华为杯等竞赛场景。这类Skill最容易踩的坑是想一步到位生成一篇完整论文结果跑出来的东西又空又假。我建议把建模流程拆成几个独立子Skill选题分析、数据预处理、模型选型、论文LaTeX生成。每个子Skill负责一段最后用一个总调度Skill串起来。比如模型选型子Skill可以这样定义触发条件当用户描述完赛题和数据量后自动对比三类主流模型方案输出可执行伪代码和算法步骤。这样既不失深度模型也扛得住每个环节。6.4 前端开发类Skills搜索词里前端开发skills热度很高也确实好写。但很多人写成了教模型写好看的前端代码这属于给模型讲大道理没意义。真正好用的是脚手架型Skill给定一个页面需求自动生成项目结构、组件文件、样式规范说明再配合一个脚本完成框架文件初始化。这类Skill的价值在于把工程约束比如用哪个路由、样式放哪个目录固化下来让每次生成的前端项目风格一致。6.5 图片生成与多媒体类Skills图片生成skills安装包AI漫剧常用skills这类需求说明大家已经不满足于单纯让模型画张图而是希望Skill里绑定好用的模型接口、参考风格说明、输出目录管理。我的建议是图片生成类Skill的核心是稳定复现同一个风格所以在SKILL.md里必须有一个风格参考区放2-3张示例图和对应的提示词模式让模型每次生成时都先读取风格参考再产出新图。别忘了加上负向提示词和输出规范不然同一个Skill跑十次能出十种风格。我个人写完几十个Skill之后的体会是别指望一个Skill能覆盖一个宏大领域它更像是把一个经常重复的动作封装到让别人不用思考。每一条description的精修、每一个退出条件的补齐都是在减少模型和用户之间的不确定性。把这个思路吃透你写出来的Skills就算不能惊艳所有人至少已经稳稳地站在及格线以上了。