最近在几个技术群里聊AI编程工具，我发现大家问得最多的已经不是“怎么配API”或者“用哪个模型”，而是“你装了什么skills”。从Claude Code到Codex再到OpenCode，这些命令行AI助手的生态里突然冒出一层叫skills的东西，有越来越多的人把它当成衡量一个工具值不值得长期用的标准。我刚开始接触的时候也一头雾水，觉得不就是一套提示词嘛，值得这么大张旗鼓去讲？后来真正用起来才发现，这玩意儿跟普通提示词完全不是一个量级。这篇就把skills这件事从头到尾捋一遍：它到底是什么、怎么从GitHub手动装上、怎么自己动手写一个、哪些场景的skills最值得装，以及踩坑之后怎么清理。
先说清楚它适合谁。如果你已经在用Claude Code、Codex、OpenCode这类工具写代码、做分析、搞内容，那你属于直接受用的群体；如果你还没上手但打算入坑，那这篇也能帮你理解“AI技能库”的玩法，避免一上来就被各种术语劝退。核心就一句话：skills的本质，是给AI准备的一套可复用的工作方法包，让它拿到任务时不再凭空发挥，而是照着一套成熟流程来干活。
1. 先把Skills这件事讲明白
1.1 为什么工具们都开始搞“技能体系”
我在第一次听说skills的时候，脑子里冒出来的问题是：之前不都是靠聊天里那段system prompt在控制AI的行为吗？为什么还要单独搞一个目录、一套文件格式？这个疑问很有代表性，因为很多人对AI助手的理解还停留在“对话框里扔一段长指令”的阶段。
实际用一段时间就会发现，靠对话里的临时指令有几个硬伤。第一，指令写得太短，AI容易跑偏；写得太长，每次聊天都要重新粘贴，体验一团糟。第二，指令本身没法带“附件”，比如一个前端脚手架模板、一套论文写作框架、一组数学建模的固定步骤，这些内容塞进提示词会让上下文爆炸，而且AI很难持续稳定地遵循。第三，团队协作的时候，每个人手里一套自己的prompt，根本没有统一标准。
skills解决的就是这“最后一公里”的问题。它把提示词、流程规范、参考文档甚至辅助脚本打包成一个独立目录，AI在遇到特定类型任务时主动读取并执行。一个skill可以带上脚本跑数据处理，可以带上模板生成标准化报告，也可以只是把一套检查清单写清楚，让AI按顺序来。说白了，就是把优秀工程师脑子里那套“接到任务之后怎么拆解、怎么执行、怎么验收”的方法，固化成一个AI也能读懂的说明书。
1.2 Skills的目录结构与加载原理
理解了定位之后，再来看技术实现就非常清爽了。以Claude Code为例，skills的存放目录一般是~/.claude/skills/下面，每个技能一个独立文件夹，文件夹里必须有一个SKILL.md文件，这个文件就是技能的“总纲”。
一个标准的最小结构大致长这样：
~/.claude/skills/ └── my-skill/ # 每个技能一个目录 ├── SKILL.md # 主文件，定义技能元信息与执行流程 └── assets/ # 可选：参考图片、模板文件、脚本SKILL.md的开头是一段YAML格式的frontmatter，声明技能的名称和触发描述，后面接Markdown正文，写具体的执行步骤。加载的时候，AI会根据用户当前的任务描述，去匹配每个技能frontmatter里的description字段，如果匹配上，就把整个skill目录里的内容读进上下文，然后按照正文里的流程来执行。
这里有一个很多人不知道的细节：description不是给用户看的，是给AI看的。它写得好不好，直接决定AI能不能在正确时机想起这个技能。你如果写得太泛，比如“用于数学建模”，那AI遇到任何跟建模沾边的问题都会呼它；写得太窄，比如“用于华为杯B题第二次预选赛”，那AI基本永远也触发不了。好的description写法，是把触发场景、用户可能的表达方式、任务边界都描述清楚。
1.3 Skills和普通提示词、插件的区别
要彻底理解skills，最好把它跟另外两个概念放一起对比：普通prompt和传统插件。
普通prompt是一次性的、在会话里即时生效的指令，它没有固定的载体，换个会话就没了。skills则是一个持久化的、有结构的“知识包”，它活在磁盘上，可以复制、分享、版本管理。你可以把一个skill发给同事，对方放目录里就能用，这种可移植性是普通prompt完全不具备的。
传统插件则更重量级。插件通常需要独立开发语言、编译构建、处理依赖，有完整的生命周期管理。以Claude Code为例，插件（plugin）往往是一段完整的MCP服务或者命令行工具，能力边界更宽，但开发成本也高。skills的定位正好卡在中间：比prompt更结构化，比插件更轻量，不需要写任何代码就能创建，同时又能调用脚本。一个顺手的分工是：需要跟外部系统交互、操作浏览器、访问数据库的，上插件；需要在对话内做判断、梳理流程、套模板出结果的，上skills。
这个定位决定了skills的上手门槛非常低——会写Markdown就能写skill，不需要会TypeScript，不需要了解API认证，甚至不需要写一行代码。
2. 从GitHub装上现成的Skills
2.1 手动安装：克隆、复制、放对位置
网上一搜“github skills”能翻出成百上千个仓库，最烦人的是很多项目都宣称“一键安装”，结果实际还是要依赖某个包管理器或者网络条件。这里把最通用、最可靠的手动方式写清楚，不管你是Claude Code、Codex还是OpenCode，思路都一样。
第一步，先找到你用的工具认哪个目录。Claude Code认~/.claude/skills/，Codex的新版本认~/.codex/skills/，OpenCode认的是它配置目录下的skills文件夹。如果你用的是某个团队定制的版本，也可以先跑一遍帮助命令，或者直接查一下官方文档里“skills directory”的关键词。
第二步，把GitHub仓库克隆到本地。注意，不要克隆整个仓库之后整个丢进去，绝大多数技能仓库根目录下会有很多文档、示例、历史版本，直接复制根目录会让AI读取一堆无关内容。正确做法是进入仓库，找到那个包含SKILL.md的具体文件夹，只把这个文件夹复制到你的skills目录下。
我用Claude Code举个实际例子，假设我要装的仓库是awesome-skills，里面有一个叫frontend-review的技能目录：
# 把整个仓库克隆到临时目录 git clone https://github.com/example/awesome-skills.git /tmp/awesome-skills # 只复制需要的技能目录 cp -r /tmp/awesome-skills/frontend-review/ ~/.claude/skills/frontend-review/ # 检查目录结构是否正确 ls ~/.claude/skills/frontend-review/ # 输出里应该能看到 SKILL.md有些仓库不提供git地址，只给了zip下载入口，那也一样，下载后解压，把包含SKILL.md的那层文件夹挪进skills目录即可。这个方法看起来笨，但最稳，不受任何环境依赖影响。装完之后不用重启工具，新开一个会话就能生效。
2.2 去哪找高质量的Skills：源网站与筛选标准
GitHub上skills仓库多到爆炸，但质量参差不齐。我常用的几个获取渠道是这样：GitHub搜索是最权威的，搜索关键词用claude skills、awesome-claude-skills、codex skills、opencode skills；还有爱好者整理的技能索引站，比如一些“awesome系列”的README页面，会把社区里热门的技能按前端、后端、写作、数据分析分类列出来，这种索引页比漫无目的搜好很多。
另外几个名字在社区里经常被提到，值得单独说明。superpower skills是一套偏大的技能合集，里面覆盖了从头脑风暴、代码评审到文档撰写的一大堆场景，安装方式既有CLI也有手动clone，手动装的时候要特别注意它整个仓库里有很多层目录，你只需要把具体的sub-skill目录复制出来，别整个仓库塞进去。typesafe ai skills是主打TypeScript/类型安全方向的skill集合，写TS的时候特别好用。还有一个叫cola skills的合集，定位是“干净、组件化”，技能之间的耦合度低，适合作为你研究技能写法的参考源码。还有codex nature skills，是针对Codex工具优化的技能集，有些技能对文件系统操作做了比较深入的自动化，在数学建模、数据处理场景里口碑不错。
筛选的时候我习惯用这三条标准：第一，看仓库最近的更新时间和issue区，超过一年没更新的基本说明作者已经弃坑，里面的命令和路径大概率过期。第二，看SKILL.md的frontmatter写得是否认真，一个连description都写得敷衍的技能，正文质量很难保证。第三，看它是否依赖“魔法命令”或者不明确的依赖安装，好的技能应该能开箱即用，最多依赖Python或者Node这种基础运行时。
2.3 安装完的验证与版本管理
装完不等于完事，一定要验证。验证方法很简单：新开一个会话，用接近技能description里描述的措辞提出一个任务，看AI的输出有没有明显走那套流程。比如你装了一个“前端性能检查”技能，那就把项目里任意一个元的组件文件丢给AI，让它“按照技能规范检查性能问题”。如果AI直接开始按SKILL.md里的步骤逐条过，那就说明触发成功了；如果AI完全无视你装的东西，继续自由发挥，那多半是description写得不行，或者路径放错了。
再说版本管理。不少人遇到过一个尴尬场景：昨天用的好好的技能，今天更新了一下模型，输出突然变得不可控。这时候第一反应不该是删技能，而是看技能是不是用了某个模型特定的行为假设。我在维护多个技能时的习惯是，在skill目录里放一个CHANGELOG.md，每次调整都记录改动；重要技能用Git仓库管理，方便随时回滚。给所有技能一个统一的“版本观”很重要：技能是活的，要跟着模型迭代慢慢调，不能装完就当一劳永逸。
3. 自己动手写一个Skills
3.1 SKILL.md的结构与写法拆解
学习skills最好的方式不是看教程，是拆一个好用的skill。二三十个热门仓库看下来，你会总结出一个共性结构：frontmatter区、目标区、执行流程区、检查清单区、参考样例区。
frontmatter区一般长这样。
--- name: math-modeling-assistant description: 当用户需要建立数学模型、求解优化问题、撰写数学建模论文时使用。适用于华为杯、国赛、美赛等建模场景，也适合日常数据预测与决策优化。 ---这里有个经验之谈：name用连字符小写命名，description尽量模拟用户会说的话。比如“帮我建个模型预测一下销量”“这题怎么建模”“写一段建模论文的摘要”，这些表达都该出现在description里，AI匹配命中率会直线上升。
正文部分，第一步写“目标”。不要写空话，直接写这个技能完成什么、不做什么。目标是给AI划定边界的，防止它发挥过度。第二步写“执行流程”，用有序列表把步骤拆开，每步配上必要的说明；第三步写“检查清单”，让AI在输出之前自查一遍；第四步放参考样例，等于给AI提供行为模板。
3.2 参数占位符与命令规范
技能里经常需要接收用户输入，比如一个建模任务里的约束条件、一个前端组件的props定义。这些动态内容怎么在静态的SKILL.md里表达？答案是约定式的参数占位符。
比如我写数学建模技能时，会在执行流程里写：
请先提取用户需求中的以下参数：
- 问题背景：{{question_background}}
- 决策变量：{{decision_variables}}
- 约束条件：{{constraints}}
- 优化目标：{{objective}}
AI读到这一节，就会在对话里主动向用户追问这几个参数。这个看起来简单的技巧，是所有高质量技能的通用做法。它本质上就是把“让AI自己乱猜”变成“让AI结构化提问”。
规范方面，三个建议值得采纳：一是流程步骤编号要清晰，AI很擅长照着编号走；二是有命令就写成可执行的代码块，禁止在文字里模糊描述“可以跑一下那个脚本”；三是禁止技能内部引用外部API时直接写死秘钥，环境变量通过占位符传进去，不然技能分享出去就出大问题。
3.3 实操案例：用量化建模的思路写一个技能
直接给一个能用的例子，我看后台咨询量比较高的是数学建模场景，正好也有同学问“华为杯建模比赛好用的codex skills怎么选”，那我就写一个math-modeling-assistant技能作为示范。
目录结构：
~/.claude/skills/math-modeling-assistant/ ├── SKILL.md └── assets/ ├── paper_template.md └── checklist.mdSKILL.md的正文核心部分：
# 数学建模辅助技能 ## 目标 - 帮助用户把实际问题转化为数学模型 - 提供常用模型的选择建议与求解思路 - 辅助生成建模论文的结构化段落 - 不负责直接代写整篇论文，不编造数据 ## 执行流程 1. 理解问题背景，提取关键实体、数据与约束 2. 与用户确认模型类型，优先推荐以下方向： - 预测类：回归、时间序列、灰色预测、神经网络 - 优化类：线性规划、整数规划、多目标优化 - 评价类：层次分析法、TOPSIS、模糊综合评价 3. 定义变量与假设，输出模型表达式 4. 给出求解思路，包括工具选择（Python、MATLAB、Lingo） 5. 根据论文模板生成摘要、问题分析、模型建立、模型求解、灵敏度分析等章节 ## 检查清单 - [ ] 所有变量是否有明确定义 - [ ] 假设条件是否与问题相符 - [ ] 是否有量纲统一 - [ ] 结论是否与数据逻辑一致因为有了这个技能，AI在接到建模任务时会自动按这个流程走，而不是一股脑从线性回归开始编。你会发现它给出来的问题解读、变量定义明显比普通对话严谨很多，这就是流程固化的价值。
3.4 测试技巧：如何判断一个技能写得好不好
写完技能之后，第一件事不是急着用，是拿三个不同水平的测试用例去试。测试用例要覆盖“标准情况”和“边界情况”。标准情况就是用户按照你预想里最常规的方式提问，看技能能不能顺利跑完；边界情况是用户提出的任务特别模糊，或者特别复杂，这时候技能能不能引导对话走向结构化，比标准情况更考验质量。
还有一个很有效的自测方法：把技能全文打印出来（或者誊到另一个文件里），假装自己是个实习生，照着这个文档能不能完整执行任务。如果文档里到处是“根据情况判断一下”“按常规处理”这类模糊表述，那AI也会懵。技能文档写得越具体，AI的执行稳定性越高。
我自己调试技能的时候会反复改description和正文，每改一次就跑一次测试，这种“写——测——改”的循环跑下来，一个技能大概要迭代三轮才敢正式拿进工作流。
4. 场景化Skills推荐与实战
4.1 前端开发场景：组件审查与重构
前端开发者是最早拥抱skills的一批人，因为前端工作流特别标准化：拿到设计稿，还原组件，写交互，做性能优化，检查兼容性。一套好的前端技能能把这套流程完全自动化。
我常用的一个组合是：一个叫“component-review”的技能负责审查组件，一个叫“refactor-plan”的技能负责生成重构方案。使用的时候我会直接说“帮我审查一下这个按钮组件的问题”，AI就会读取组件代码，结合技能里的检查清单，从可访问性、语义化、props设计、性能渲染等角度逐项过。输出结果不是泛泛而谈，是每条都有具体的代码片段和修改建议。
前端skills的推荐方向我也总结过：首要是代码规范类，能把团队lint规则和PR检查固化进去；其次是性能分析类，能针对React、Vue项目的渲染逻辑给出优化点；再次是样式与设计系统类，能根据design token生成组件。注意别装太多能力重叠的技能，比如一个仓库里同时装了“代码审查”和“代码质量检查”，两个技能的description非常接近，AI匹配时就容易随机触发其中一个，行为不稳定。
4.2 数学建模与竞赛场景
竞赛场景下，AI技能的定位不是替你做题，而是把“解题流程”标准化。我当年参加华为杯的队友要是有一套好的skills，熬夜比例至少减少三分之一。
数学建模最实用的技能组合是三个：建模辅助（就是我上面示例那类）、论文生成、数据可视化。论文生成的技能我会单独说一句：它应该包含竞赛论文每个章节的写作规范和常用句式，让AI能按摘要、问题重述、模型假设、模型建立、模型求解、灵敏度分析、模型的评价与推广这个结构输出。可视化技能则要内置常用图表类型的选择逻辑：什么时候用折线图、什么时候用热力图、什么时候用三维曲面图，配合Python代码模板，稳定性极高。
Codex用户问得比较多的是“华为杯建模比赛好用的codex skills”，我实测下来，Codex在读取本地数据文件和处理脚本方面比较顺手，搭配能自动扫描数据目录、生成探索性分析报告的技能，效率提升很直观。核心经验是：竞赛场景的skill正文一定要包含“提交前检查清单”，让AI在最后阶段逐项检查格式、变量命名、图表编号、参考文献引用，这个做法能避免大量低级扣分。
4.3 内容创作场景：AI漫剧与视频脚本类
AI漫剧、短剧脚本这类内容创作场景，跟我前面讲的代码场景差别很大，但对skills的需求同样旺盛。内容创作者常用的一套技能长这样：角色设定技能，负责生成角色的性格档案、关系图谱、口头禅；分镜技能，负责把一段剧情拆成分镜表格；审核技能，负责检查脚本前后逻辑是否自洽。
这类技能的目录里往往会放assets/静态资源，比如角色立绘参考图、分镜模板、台词风格对照表。SKILL.md正文像在教一个新编剧怎么写脚本，每一条都明确到“这一屏是近景还是远景，台词控制在几个字以内”。有了这样的技能，AI产出的漫画脚本才不是干巴巴的对话流水账，而是真的有镜头感、有节奏的成品。
内容创作者刚开始用skills时的一个常见误区是，把技能当成“一键生成完美内容”的魔法。实际它更像一个工作台：AI按你的流程把初稿搭出来，你在上面做判断和修改，效率高，质量稳，但思路和审美还是你的。
4.4 OpenCode、Codex等工具的差异化适配
不同工具对skills的实现有细微差别，但核心逻辑是通的。我用下来的对比感受写个表格，方便你对照。
| 工具 | 技能目录 | 特点 | 适配建议 |
|---|---|---|---|
| Claude Code | ~/.claude/skills/ | 生态最成熟，社区技能最多 | 优先从社区合集里挑 |
| Codex | ~/.codex/skills/ | 对脚本执行和本地文件操作更积极 | 适合数据处理、自动化类技能 |
| OpenCode | 配置目录下的skills文件夹 | 轻量、灵活，支持多种模型后端 | 自己写的技能在这边调试最快 |
另外常有人搜“skills网页版进入”，这里统一说清楚：目前主流几个工具都没有统一的网页版技能管理后台，别指望打开一个网址就能可视化安装。大家说的“网页版”，通常是指GitHub网页上浏览技能仓库、看README、手动复制目录。管理skills这件事，本质还是文件操作，用命令行或者编辑器都比网页方便。
5. 常见问题与排查技巧实录
5.1 技能加载失败或者完全不生效
这个是最常见的问题，我帮人排查过无数回，九成情况都是路径放错了。尤其安装合集类仓库时，很多人把技能目录多套了一层，导致AI翻遍了整个目录树都没找到SKILL.md。判断方法很简单：直接进技能目录列一下文件，如果看到的是仓库README、LICENSE这些文件而不是SKILL.md，那就是层数不对。
另一个高频原因是description写得跟用户提法不匹配。比如你装了一个描述为“用于前端代码性能优化”的技能，但你问“帮我看看这个页面为什么卡”，AI把“卡”归到了运行时问题而不是性能优化，技能就触发不了。解决办法要么改description加上“卡顿”“加载慢”“性能差”这些口语化触发词，要么就把技能名称里带的关键词留在输出里，让AI能关联上。
5.2 技能之间互相冲突怎么办
同时装多个技能之后，最头疼的是AI“突然变了一个人”。前天还能正常产出，今天同样的输入，输出风格完全不同。这种情况多半是某个技能的description写得过于宽泛，导致AI在与你对话的几乎每一个任务里都会把它加载进来，技能里的流程就会强加在日常输出上，看起来就是“AI被劫持了”。
排查方式是这样：先查看当前对话里到底加载了哪些技能，然后再逐个排查。找到有嫌疑的技能，把它的description往精确方向改，让它的触发范围收窄。还有一个小小的排查技巧：当你判断不出是哪个技能影响AI行为时，把skills目录临时改名，起一个新会话，如果输出恢复正常，再二分查找具体技能。
5.3 清理无用Skills，给AI瘦身
跟绝大多数人的直觉相反，技能不是装得越多越好。因为AI在匹配技能时，如果候选太多，选择错误的风险会直线上升，而且上下文窗口被一堆用不上的技能描述占着，响应质量反而下降。
我处理技能库的思路是：把技能分成“常驻”和“按需”。常驻技能控制在三到五个，都是你日常高频使用且流程稳定的；按需技能单独放一个目录，用到的时候再手动指给AI，用完移出。维护的时候每隔一两个月就顺手清理一次：超过半年没用过的技能先移到备份目录，备份两次都没被想起来，就直接删除。
很多人问我有没有推荐的清理方法，其实核心原则就一条：给AI减负跟给人减负一样，桌面干净了，找东西才快。我现在的做法是直接维护一个README.md索引文件放在skills根目录，里面列清楚每个技能的用途、最后使用日期、是否推荐保留，一切一目了然。
5.4 一条保底建议：把写Skill当成写给自己看的文档
最后分享一个我个人在反复踩坑之后沉淀下来的习惯：写skill的时候，默认读者不是那个聪明的AI，而是三个月后你自己。你回忆一下，三个月前你精心设计的一套“完美流程”，现在拿起来还能不能一眼看懂？技能文档最忌讳的是把关键信息藏在自己脑子里，默认AI会“理解你的言外之意”。AI是真的会一字不差照做你写的文档，所以你写出来的每一条含糊，都会变成输出里的每一次偏差。
我现在写完一个新技能，会强迫自己先把SKILL.md朗读一遍，读不通顺就说明流程有跳步；再把所有可能引发歧义的地方加粗标出来，最后请一个没用过这个技能的同事直接照着文档跑一遍。这个流程看起来麻烦，但它帮我避免过太多次“看起来跑通了、换个人就不行”的尴尬。
对于已经掌握基础玩法的人，我建议下一步可以尝试把技能的触发边界做得更精细，比如让技能针对不同模型版本输出不同风格的方案；也可以试着在skill里集成本地脚本，把重复性劳动进一步自动化。这个方向是目前社区里最活跃的部分，也是我觉得最值得投入时间的方向——毕竟AI的能力会持续迭代，但你自己沉淀下来的工作方法，才是真正越用越值钱的东西。
