从提示词到Skills：AI编程从“聊得好”到“干得对”的实战指南

最近这段时间，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。扫描到的每个skill，AI会看到它的名字和description字段。真正开始对话后，模型根据用户当前的请求，对照这些名字和描述，判断“这个任务和哪个skill匹配”，匹配上了，才把那个skill里的具体内容加载进上下文。

这个设计背后是一个很实在的工程考量：上下文窗口是有限的，也是花钱的。如果把几十个skill一次全塞进上下文，既浪费token，还会让模型注意力被无关内容干扰。按需匹配就像图书馆不把所有书摊在桌上，你问“怎么做红烧肉”，管理员才把菜谱递给你。所以你在写skill的时候，description写得好不好，直接决定了它会不会在正确的时间被“想起”。

1.3 skills、MCP、AGENTS.md：它们不是一回事，也别拿来互相替代

跟skills经常一起被提起的还有两个词：MCP和AGENTS.md。我见过不少朋友把它们混为一谈，结果配置了半天发现完全不是自己想要的效果。

拿表格说清楚：

它们可以配合使用：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不少，最后收敛出一套固定的正文结构，五个块，基本能覆盖绝大多数场景：

1. 适用场景与目标：这个skill在什么前提下生效，最终要交付什么。
2. 执行流程：分步骤，每步写清楚输入、操作、产出。
3. 输出规范：交付物的格式要求、位置、命名方式。
4. 检查清单：让AI在结束时逐条自检，防止漏步骤。
5. 禁区与反例：明确“不要做什么”，比如“不要修改用户未授权的文件”“不要使用外部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先从设定卡里取数，而不是自己发挥。另一类是分镜模板：把“开场-冲突-反转-结尾”的节奏、每个镜头的时长、画面描述词的格式（主体+动作+镜头+光线+风格）写进skill，AI批量生成分镜脚本时就能保持统一风格。

我听过一个做漫剧的朋友说，他每天生产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 快速排查表

把前面这些坑汇总成一张表，遇到问题直接对照：

我自己用下来的体会是，skills这玩意儿的价值不在于“装得多”，而在于“用得准”。它本质上是在给AI积累你所在行业的隐性经验——那些文档里不写、但是老手都知道的规矩。写skill的过程，其实是在逼你把脑子里的经验梳理成别人能看懂、AI能执行的流程。哪怕你最后只写了三个skill，只要它们覆盖了你最高频、最痛的三类任务，你的AI使用效率就已经跟大部分人拉开差距了。

最后再分享一个小技巧：我建议每个skill里都留一个“维护记录”小节，写上最近一次改动的原因。这个习惯一开始很不起眼，但等你一个月后回看，会发现它是你迭代思路的最佳线索。当时记录下的“为什么改成这样”，往往就是下一次优化的出发点。