最近这段时间AI编程圈子里skills这个词的出场频率已经快赶上当年的prompt了。Claude Code把Skills做成了官方能力Codex、OpenCode这些工具也陆续跟进GitHub上一个接一个的skills合集冒出来还有人直接把整套技能包做成了可安装的库superpowers就是其中比较出名的一个。这不是单纯换了个流行词而是很多人在同一条路上摸到了同一个答案光让AI“聊得好”远远不够还得让它“干得对”。所谓skills通俗点讲就是把某一类任务的做法、规范、踩坑记录打包成一份结构化的指令文件AI遇到对应任务时自动调出来照着执行。这篇文章我想结合自己这几个月的实测把skills是什么、怎么装、怎么写、怎么挑、怎么排坑一次讲清楚。无论你正在用Claude Code、Codex还是OpenCode只要想把AI从“偶尔靠谱”变成“稳定靠谱”都值得往下看。1. 先别急着装搞清楚skills的原理再动手1.1 一份skill本质上是给AI的“工作手册”很多人第一次接触skills会把它当成一种更高级的提示词。这个理解对了一半但它远不止是提示词。提示词是你每次对话都要重新说一遍的要求而skill是一份可以反复调用、自动触发、甚至带脚本和模板的“工作手册”。想象一下你带新人你不可能每天重复八百遍“提交代码前先跑测试、再检查commit信息格式”你会写一份《开发规范手册》放在桌上新人遇到问题自己去翻翻完照着做做完打勾。skills就是干这个的。它把“什么场景下该干什么事”“按什么顺序干”“干到什么程度算合格”“有哪些雷区不能踩”这些隐性知识固化成AI随时能查阅的显性文档。一份标准的skill通常包含三部分触发说明告诉AI什么时候该用、执行流程具体怎么做、检查清单和禁区做到什么程度、哪些事不许做。形式上一般是一个带frontmatter的Markdown文件必要时旁边还可以跟着脚本、模板、参考文档。之所以选Markdown而不是JSON或者代码原因很实在大模型读Markdown几乎零成本人也能直接看懂、用git做版本管理门槛低到任何人都能上手改。1.2 按需触发AI是怎么“想起”某个skill的理解了它是个手册下一个问题就是AI怎么知道“现在该翻哪本手册”以Claude Code为例工具会在固定的几个目录里扫描skill一个是用户级的~/.claude/skills一个是项目级的.claude/skills。扫描到的每个skillAI会看到它的名字和description字段。真正开始对话后模型根据用户当前的请求对照这些名字和描述判断“这个任务和哪个skill匹配”匹配上了才把那个skill里的具体内容加载进上下文。这个设计背后是一个很实在的工程考量上下文窗口是有限的也是花钱的。如果把几十个skill一次全塞进上下文既浪费token还会让模型注意力被无关内容干扰。按需匹配就像图书馆不把所有书摊在桌上你问“怎么做红烧肉”管理员才把菜谱递给你。所以你在写skill的时候description写得好不好直接决定了它会不会在正确的时间被“想起”。1.3 skills、MCP、AGENTS.md它们不是一回事也别拿来互相替代跟skills经常一起被提起的还有两个词MCP和AGENTS.md。我见过不少朋友把它们混为一谈结果配置了半天发现完全不是自己想要的效果。拿表格说清楚概念本质解决什么问题类比skills行为规范和流程手册AI“怎么做、按什么顺序做、做到什么标准”员工手册MCP工具和数据接入协议AI“能调用什么外部工具、读什么数据源”工具箱和数据库接口AGENTS.md项目级全局约定AI“进入这个项目后必须遵守的规矩”项目规章制度它们可以配合使用MCP给AI接上执行代码、读写文件的能力skill告诉AI拿到这个能力之后按什么流程用。比如一个“数据清洗”skill里面写清楚“先看缺失值、再处理异常、最后做分布检查”而具体的pandas执行能力由MCP或者内置工具提供。AGENTS.md更像项目层的大纲skills是具体场景的分册。理解了这个分层你后面写skill的时候思路会清晰很多不要让skill去教AI怎么调用工具要让它教AI怎么组织工作流。2. 从安装到验证主流工具的skills落地方法2.1 Claude Code手动安装GitHub上的skills很多人问得最多的就是“Claude Code怎么手动装GitHub上的skills”。网上搜到的合集很多但装的时候总出岔子其实步骤就那么几步。第一步确定装在哪。只有你自己用的放用户级目录mkdir -p ~/.claude/skills cd ~/.claude/skills想让某个项目里的人共用、或者某个skill只属于当前项目就放进项目目录mkdir -p .claude/skills cd .claude/skills第二步把GitHub仓库clone进来或者直接下载单个文件夹。clone整个仓库是最省事的git clone 仓库地址第三步也是最容易翻车的检查SKILL.md是不是在正确的位置。正确结构应该是skills/ └── my-skill/ ├── SKILL.md └── 可选的其他文件很多仓库为了展示方便目录结构是repo/skills/xxx/SKILL.md你直接把整个repo clone进来就会变成~/.claude/skills/repo/skills/xxx/SKILL.md多套了一层工具根本扫不到。我自己的习惯是clone之后先find . -name SKILL.md看一下把对应的skill目录挪到顶层。第四步验证。装完不用重启什么服务但已经打开的会话最好重新开一个新skill在旧会话里未必会被识别。然后你可以直接问AI“你现在有哪些可用的skills”或者故意制造一个触发场景看它反应。Claude Code会在debug日志里记录skill的加载情况实在不确定就开debug模式看一眼。注意不要用sudo去装skill也不要把用户级和项目级的同名skill混着放项目级会优先覆盖用户级容易造成“我明明更新了怎么还是旧行为”的错觉。2.2 Codex CLI用AGENTS.md把skills“接”进来Codex原生支持的是AGENTS.md没有像Claude Code那样标准的skills目录。但社区早就折腾出了办法核心思路就一句话让AGENTS.md告诉Codex“遇到什么任务先去看哪个文件”。我实测下来比较顺的做法是在项目根目录建一个skills/文件夹再在AGENTS.md里加一段当任务涉及数学建模、数据分析或论文排版时必须先阅读 skills/math-model/SKILL.md并严格按其中的流程执行。这样一来Codex每次进入项目都会先看到这段指引遇到对应任务时就会去翻那个文件。效果上跟Claude Code的skill加载已经很接近了只是触发逻辑更依赖AGENTS.md的措辞。社区里还有不少把Claude Code的skill转换成Codex格式的脚本和合集名字五花八门比如有人整理过带“nature”字样的合集实际上就是把自然语言工作流做成了Codex能读的文件。你只要把握住“找到Codex认的配置入口把流程文档挂进去”这个原则具体格式差异都不难解决。2.3 OpenCode、Cola这类社区工具查目录约定放对位置OpenCode、Cola这类工具现在也很活跃它们对skills的支持各有各的路径。以OpenCode为例它有自己的agent配置目录社区推动的skills格式也越来越向SKILL.md统一靠拢。你拿到一个新工具第一步永远是去文档里查“它扫描哪个目录”而不是凭感觉猜。这类工具目前生态还在快速变化可能上个月支持的目录约定这个月就改了。但万变不离其宗工具的配置目录里放一个带frontmatter的Markdown文件名字和描述写得清楚基本都能被识别。如果工具支持的是JSON或者YAML格式的agent配置那就花十分钟把SKILL.md的内容翻译成对应格式流程文档的骨架完全可以复用。2.4 Superpowers全家桶选、装、维护一体化的思路superpowers算是skills圈子里绕不开的名字。它不是单个skill而是一整套经过筛选和打磨的技能包覆盖从项目启动、测试驱动开发到代码重构、写文档这类高频开发场景。它的安装方式有好几种网页生成器可以按需勾选技能、生成安装包也可以用npm全局安装再就是直接clone它的GitHub仓库。我个人的习惯是clone仓库然后像2.1里说的一样只把需要的技能目录软链到自己的skills目录ln -s /path/to/superpowers/skills/xxx ~/.claude/skills/xxx这样做的好处是方便更新——上游一更新我pull一下仓库所有软链的技能全部同步不用一个个复制。安装全家桶前有个建议第一次不要全装。superpowers里有些技能的设计哲学和你的工作习惯未必合拍全装进去只会让AI的“注意力”被稀释。先挑两三个跟你日常工作最贴的用半个月再决定要不要扩大。3. 手写自己的skill一套可复用的方法论3.1 拆任务什么样的工作适合做成skill不是所有任务都配拥有一个skill。写skill是有成本的要维护、要测试、要迭代。判断一个任务值不值得做成skill我一般看四条标准重复出现这个任务你每周至少做两三次而不是一年一次。步骤相对固定流程基本稳定不是每次都得重新发明一遍。容易漏步骤中间环节多靠脑子记大概率会漏。有明确的输出标准能写清楚“什么样算做完、做对”。比如“给新功能写测试”“生成数学建模论文的LaTeX框架”“按团队规范创建React组件”这些都很适合。“帮我想个创意点子”——这种高度发散的任务就不适合写成skill反而会限制发挥。3.2 写frontmatter把“什么时候用”这件小事写明白frontmatter是整个skill的灵魂尤其是description。很多人生成skill时最爱在这件事上偷懒写“用于数学建模”结果这个描述太宽泛AI在完全不相干的场景里也可能触发它或者该触发的时候又因为不够具体而错过。我的经验是description要回答三个问题任务是什么、有什么明显的触发词、什么时候不要用。给你看一个反面例子和一个正面例子。反面description: 数学建模辅助正面name: math-model-paper description: 生成符合华为杯/国赛格式要求的数学建模论文LaTeX框架与写作规范。当用户提到“华为杯”“数学建模论文”“摘要写作”“LaTeX排版”时使用。仅用于论文写作阶段不用于数据处理和模型求解。写清楚“仅用于……”这种排除条件能少掉一半的误触发问题。3.3 正文结构的五个标准块我写过的skill不少最后收敛出一套固定的正文结构五个块基本能覆盖绝大多数场景适用场景与目标这个skill在什么前提下生效最终要交付什么。执行流程分步骤每步写清楚输入、操作、产出。输出规范交付物的格式要求、位置、命名方式。检查清单让AI在结束时逐条自检防止漏步骤。禁区与反例明确“不要做什么”比如“不要修改用户未授权的文件”“不要使用外部API”。这套结构本身没什么高深的但写完你会发现原来跟AI反复强调的那些话终于有了一个固定的“家”。3.4 一个可以直接改用的前端代码审查示例写一个我最近在用的前端审查类skill给你做参考你可以直接抄走改改--- name: frontend-review description: 按团队规范对前端代码React/Vue进行审查。当用户要求“审查代码”“review PR”“检查组件实现”时触发。重点关注可维护性和性能不做风格唠叨。 --- # 前端代码审查 ## 适用场景 - 用户提交React或Vue组件代码要求审查 - PR合并前需要把关 ## 审查流程 1. 先看组件职责组件是否只做一件事命名是否体现职责 2. 检查状态管理useState/useEffect是否过度使用能否抽离 3. 检查性能列表渲染有无key大计算有无memo事件绑定有无重复 4. 检查可访问性按钮有无aria-label图片有无alt 5. 检查样式是否用了设计系统token有无硬编码色值 ## 输出格式 - 按“问题-影响-建议”三段式输出 - 每个问题标注严重级别P0阻断合并/P1建议修改/P2可选优化 ## 检查清单 - [ ] 组件职责单一 - [ ] 无遗漏key和危险dangerouslySetInnerHTML - [ ] 无可疑的any类型 - [ ] 无硬编码样式值 - [ ] 所有交互元素可键盘操作 ## 禁区 - 不要纠结代码风格偏好单引号双引号这类 - 不要在没有profiler数据时断言“这里性能有问题”这个示例看起来简单但它把“什么样的审查结果是合格的”写得很具体。AI照着执行输出质量比没有skill时高出一大截因为它的注意力不再散乱。3.5 用AI帮你写skill以及版本迭代技巧一个反直觉但特别好用的技巧是让AI帮你写AI的skill。做法是把你过去几段做得比较成功的任务对话丢给它让它提炼流程、总结踩坑点生成一版SKILL.md草稿。你再把草稿放回工具里实测几轮把不满意的地方直接告诉AI让它改。迭代技巧有三点都是我被坑过之后总结的skill目录一定要纳入git管理每次大改留个commit出问题随时回滚。维护一个CHANGELOG或者版本说明哪怕是几行字一个月后你就知道为什么要这么写。定期做“冒烟测试”准备一个固定的小任务每次改完skill先跑一遍确认基本功能还在。这比在真实任务里出错了再排查高效太多。4. 三个典型场景的skills实战拆解4.1 数学建模含华为杯把竞赛套路变成默认动作数学建模是skills发挥威力最明显的场景之一。参加过华为杯、国赛这类比赛的朋友都有体会三天时间真正的难点不在“会不会建模”而在“流程能不能跑完”。读题、查数据、清洗、建模、求解、写论文、做图表任何一个环节卡壳都会拖垮全局。建模比赛的流程高度固定这简直是为skills量身定做的。我给参赛组配置过三件套赛前检查skill内容是环境检查清单Python版本、numpy/pandas/sklearn是否齐全、LaTeX模板是否就位、数据目录结构是否规范。比赛开始那天直接触发它半小时内确认一切就绪不用焦虑“是不是忘了装什么”。数据探索skill华为杯这类比赛的数据量通常不小上来就建模必翻车。skill里写死流程先看数据字典和缺失值、再做分布和相关性分析、把结论汇总成一份markdown报告然后再进入建模阶段。论文排版skill把往年的格式规范、摘要结构、图表编号规则、参考文献格式写进去。到了最后半天大家都在手忙脚乱排版的时候你有AI照着skill自动生成符合格式的LaTeX框架这一项就能省出小半天。建模比赛场景还特别适合用AGENTS.md把三个skill串起来进入项目就在AGENTS.md里写“比赛期间每日工作前先查看skills/checklist/SKILL.md”。这样整个团队用一个工具所有人的动作都是标准化的。4.2 前端开发从“能跑”到“规范交付”前端开发大概是skills需求最旺盛的领域网上搜“前端开发skills”热门帖子一大把。原因不难理解前端项目规范多、技术栈杂、团队的隐性约定特别多。我自己比较受益的是一个组件生成skill。以前让AI写一个表格组件它每次给的代码风格都不一样有时候用函数组件、有时候又写成class样式一会儿CSS Modules一会儿Tailwind我还得在提示词里反复纠正。后来我把团队的技术栈约束和组件书写规范做成skill里面写清楚“React 18函数组件、TS严格模式、样式使用设计系统token、props命名遵循XX规范”。从此让AI生成组件第一版就接近可以直接合并的水平。另一个值得做的是commit和代码提交规范skill。AI帮你改完代码让它顺手生成符合Conventional Commits格式的commit message、并且自动对照检查清单确认没有把调试代码提交上去这些都是纯文本流程skill写起来非常简单收益却很直接。4.3 AI漫剧/内容生产把创作手感变成可复制流程很多人以为skills只属于程序员其实内容创作领域同样吃这一套。AI漫剧AI生成漫画、动态短剧现在非常热这类生产的痛点特别典型单个镜头生成得好但整体一致性差。人物一会儿圆脸一会儿尖脸衣服颜色忽深忽浅剧情节奏全凭运气。这种场景里skill能干的活有两类。一类是设定卡固化把主角、配角的角色设定外形特征、服装配色、性格关键词写成结构化的设定卡文件每次生成画面描述词时skill强制AI先从设定卡里取数而不是自己发挥。另一类是分镜模板把“开场-冲突-反转-结尾”的节奏、每个镜头的时长、画面描述词的格式主体动作镜头光线风格写进skillAI批量生成分镜脚本时就能保持统一风格。我听过一个做漫剧的朋友说他每天生产100条素材以前全靠自己手写描述词累得不行。后来把三个skill一配人设卡、分镜模板、审核清单同样的工作量时间砍掉一半返工率降了七成。这就是skills在非编程领域的力量——它不挑行业只挑“有没有可复制的流程”。5. 好skill去哪找、怎么筛5.1 我平时会逛的skills来源GitHub是目前最主要的skills集散地但直接搜“skills”会搜出一堆无关内容。我常用的搜索组合是SKILL.md in:name直接命中带SKILL.md文件名的仓库。claude code skills、codex skills按工具名过滤能避开大部分噪音。在已知的高质量仓库里“顺藤摸瓜”很多合集仓库会在README里互相推荐这比搜索引擎靠谱。具体的来源我比较常看这几类官方和半官方示例Anthropic官方维护的skills示例仓库质量稳定特别适合用来学习“好skill应该长什么样”。superpowers前面提过的全家桶覆盖开发流程的方方面面适合系统性使用。工程向社区合集比如名字里带typesafe的全栈技能合集偏TypeScript和工程化方向前端同学值得关注。技术社区整理帖知乎、技术公众号、B站都有人按月整理热门的skills仓库。这类帖子的价值在于信息筛选缺点是有时效性收藏后记得回去看原仓库的更新状态。5.2 筛选四步法三分钟判断一个skill值不值得用装skill之前花三分钟做个筛查能省下后面好几个小时的排坑时间。我按重要性排序看四点第一description是不是够具体。这是最快的一票否决项。描述模糊的skill装上之后基本就是给AI添乱它会在不该触发的时候乱触发。第二正文有没有可验证的检查清单。只有一堆“请认真分析”“请确保质量”这种空话的直接跳过。真正有用的skill一定有“做完之后逐条自检”的清单。第三有没有禁区说明。好skill会主动告诉你“不要做什么”。如果全文都在说“要做什么”、完全不管边界很容易在真实任务里干出越界操作。第四看仓库的更新时间和代码活跃度。AI工具这半年迭代很快半年前写的skill很可能已经过时。一个一年没更新的仓库哪怕热度再高我也不会直接装而是把它当成“思路参考”。6. 常见问题与排坑实录6.1 skill装了不生效按顺序查这四个地方这是被问得最多的问题。按我说的方法从前往后查九成能解决先查目录位置。用户级和项目级放反了、或者放进了工具不认识的自定义目录最常见的错误。先确认工具文档里写的扫描路径再看你的文件在不在里面。再查目录层级。这可能是第二个高发区。很多仓库结构是repo/skills/xxx/SKILL.md直接clone后多了一层。用find . -name SKILL.md看一眼路径把SKILL.md调整到直接挂在skills目录下的技能文件夹里。然后查frontmatter格式。YAML语法错误、漏了name或description字段工具解析失败就直接跳过这个skill。建议用任何YAML校验工具先跑一遍。最后查描述触发词。description写得太抽象AI压根联想不到它。想办法把触发场景说得更具体。还有一个很容易被忽略的点改完skill之后重开一个会话再测。我自己就干过“改了半天以为没用结果只是旧会话还在跑旧配置”的蠢事。6.2 多个skill互相“打架”怎么办装多了之后会出现两个skill同时匹配同一个任务的情况。比如你装了一个“python代码生成”又装了一个“数据分析脚本生成”任务一来AI可能纠结用哪个或者两个都加载指令互相矛盾。解决办法有三招在description里写排除条件比如“仅当用户明确要求x时使用通用Python编码任务请使用另一个skill”。明确项目级优先于用户级。如果一个skill只在这个项目里用就放在项目级目录不要放用户级避免污染其他项目。合并同类项。两个功能重叠的skill保留一个更好的把另一个的独有内容并进去。skill数量不是越多越好精简到“每个高频任务恰好一个对应skill”是最理想的状态。6.3 清理与维护从tibo的整理思路说起skill装得越来越多之后整理就成了头疼事。社区里有个叫tibo的开发者分享过一套清理思路我看了之后结合自己的实践总结成三步第一步先审计再动手。别一上来就删文件夹。先统计一下哪些skill在最近一个月里真正被触发过哪些从来没有命中过。有些工具会记录skill的加载日志或者你可以直接逐个试探性触发一遍记录结果。第二步用“meta-skill”做交叉审计。这个思路很妙写一个临时skill让AI把你自己所有的skill目录通读一遍输出一份报告内容包括“重复覆盖的领域”“互相矛盾的指令”“描述过时的技能”。AI做这种通读归纳比人高效得多半小时能顶你一下午。第三步归档而不是删除。我专门建了一个~/.claude/skills_archive目录把不再用的skill移过去而不是直接rm。因为很可能三个月后你又需要它到时候从归档里挪回来比重新上网找、重新调教要快得多。另外我会在项目的AGENTS.md里维护一份skill索引表写清楚每个skill的用途和更新日期。看起来多了一步实际上维护成本很低但对团队的其他人来说这比让他们自己去翻一堆目录友好太多了。6.4 快速排查表把前面这些坑汇总成一张表遇到问题直接对照症状常见原因解决方法skill完全不生效skill目录位置不对或层级多套了一层查扫描路径用find命令确认SKILL.md位置有时生效有时不生效description触发条件太宽/太窄重写description列出明确触发词和排除条件改了没反应旧会话缓存重开会话再测两个skill同时触发描述重叠在description中加排除条件或合并skill输出质量不稳定skill正文大量空话没有检查清单重写正文补充可验证的检查清单和禁区项目里行为异常用户级和项目级skill冲突检查项目级目录是否有同名skill覆盖我自己用下来的体会是skills这玩意儿的价值不在于“装得多”而在于“用得准”。它本质上是在给AI积累你所在行业的隐性经验——那些文档里不写、但是老手都知道的规矩。写skill的过程其实是在逼你把脑子里的经验梳理成别人能看懂、AI能执行的流程。哪怕你最后只写了三个skill只要它们覆盖了你最高频、最痛的三类任务你的AI使用效率就已经跟大部分人拉开差距了。最后再分享一个小技巧我建议每个skill里都留一个“维护记录”小节写上最近一次改动的原因。这个习惯一开始很不起眼但等你一个月后回看会发现它是你迭代思路的最佳线索。当时记录下的“为什么改成这样”往往就是下一次优化的出发点。
