最近群里聊得最凶的一个词就是“skills”，不是传统简历上的那种技能，而是AI编程助手里的“技能包”。Claude Code、Codex、OpenCode这些工具陆续都支持了skills机制，GitHub上冒出一堆技能库，有人用它跑数学建模，有人拿它做前端开发，还有人靠它批量生成AI漫剧脚本。我花了两周时间把主流平台的skills安装、编写、排错全部过了一遍，这篇就把完整路线整理出来，从零讲清楚它到底是什么、怎么装、怎么写，以及踩过的坑。
这个内容适合正在用Claude Code或Codex、想给AI助手扩展能力的人，也适合准备参加数学建模竞赛、想搭一套自动化工具链的学生。不夸张地说，skills是2025年AI Agent领域最值得花时间研究的一层抽象，搞懂它，你就从“只会聊天的AI”进化到了“能指挥干活的外包团队”。
1. 先搞清楚：AI skills到底是什么
1.1 从一个命令说起
如果你用过Claude Code，一定见过类似这样的界面——输入框下面有几条命令，比如/init、/review、/compile，这些其实就是一个最简单的skill形态：把一段固定的指令、一套固定的检查流程，打包成一个斜杠命令。当我们说“装一个skill”，本质上就是往AI的工作目录里塞一个文件夹，里面放上说明文档和脚本，让AI在特定任务时按这套流程执行。
我拿一个实际场景说明白这事。以前你让Claude Code写个前端页面，它可能会自由发挥，有时候给你Tailwind，有时候给你纯CSS，风格完全随缘。但如果你装了一个frontend-dev的skill，它会自动遵守你预定义的规范：必须用TypeScript、必须走组件化、必须加响应式断点、代码完成后必须自查。AI还是那个AI，但它的行为被一套“专家规则”约束住了，输出质量一下就稳了。
1.2 skills和普通prompt的区别
很多人觉得skill不就是个复杂点的prompt吗？表面看确实像，但实质差很远。普通prompt是一次性的对话指令，你每次都要重新解释需求；skill则是一个可复用、可版本管理、可共享的工作流单元。它有固定的目录结构，有SKILL.md作为入口说明，可以挂脚本、挂参考文档、挂模板文件。它带来的是一种工程化的能力沉淀——你上个月调出来的最优工作流，可以打包成skill让团队所有人直接复用。
我见过一个最典型的场景是数学建模。华为杯、美赛这些比赛，三个人组队，一个人负责建模一个人写代码一个人写论文，但AI辅助的时候经常出现一个问题：每个队员都用自己的一套prompt去问AI，出来的结果五花八门。后来有人把完整的建模流程——从问题分析、假设建立、模型选择、代码实现到论文排版——封装成一组Codex skills，全队统一调用，AI的输出一致性立刻提升了一个档次。
1.3 一个skill的标准结构
以Claude Code和Codex兼容的规范为例，一个最简skill长这样：
my-skill/ ├── SKILL.md # 技能说明，AI读取的核心入口 ├── scripts/ # 可选，辅助脚本 │ └── check.py └── references/ # 可选，参考资料、模板 └── template.mdSKILL.md里面用YAML头信息声明技能名称和描述，正文写具体的执行步骤、规则约束、输出格式。AI在收到任务时，会通过描述判断“这个任务是否匹配该技能”，匹配了才加载，不匹配就忽略。
提示：
SKILL.md的名字是严格的，不能改成README.md或skill.md，AI代理主要按这个名字索引。我第一次写的时候就因为文件名不规范，折腾了半天没生效。
2. 手动安装GitHub上的skills：完整实操
2.1 安装前先确认三件事
GitHub上现在有大量现成的skills仓库，但不同平台的skill格式不一定互通。动手安装之前，先确认三件事，不然白费力气。
第一，确认目标平台的skills规范和加载路径。Claude Code的skills一般放在.claude/skills/目录下，Codex则通常读.codex/skills/或通过配置指定，OpenCode的路径又不一样。第二，确认skill仓库的目录结构——有的仓库本身就是单个skill，直接clone下来就能用；有的是聚合仓库，下面几十个skill子目录，你需要挑着复制。第三，确认SKILL.md里的frontmatter格式——Claude Code的规范是name和description字段，Codex有的版本要求name、description外加version，格式不兼容的skill就算复制进去也不会被识别。
我自己踩过最典型的一个坑：GitHub上有个热门的codex-nature-skills仓库，里面很多skill是按Codex早期规范写的，SKILL.md头部没有version字段。我把它原样复制到Claude Code里，结果完全不生效。后来逐行对比官方示例才发现，两家的frontmatter字段要求不一样。所以安装前花两分钟看一下仓库说明文件里的兼容性声明，比闷头复制靠谱得多。
2.2 Claude Code手动安装步骤
手动安装其实就四步，但每一步都有细节。以把一个叫modeling-competition的数学建模skill装到Claude Code为例：
第一步，clone仓库到本地临时目录：
git clone https://github.com/example/modeling-competition.git第二步，找到项目中的.claude/skills/目录。有些仓库把skills放在根目录的skills/文件夹里，有些放在.claude/skills/下，以仓库实际结构为准。打开目录看一下，确认里面是SKILL.md还是又一个嵌套目录。
第三步，复制到Claude Code的全局skills目录。macOS和Linux在这里：
cp -r modeling-competition ~/.claude/skills/modeling-competitionWindows则在%USERPROFILE%\.claude\skills\下。如果你只想给某个特定项目用，就放在项目的.claude/skills/里，效果是只在该项目下生效。
第四步，重启Claude Code会话，输入/skills或者直接问“你现在有哪些可用技能”，确认skill已经被索引。没有出现的话，八成是路径错了或者frontmatter格式不对。
2.3 Codex和OpenCode的装法
Codex这边稍微有点不一样。新版Codex CLI支持从~/.codex/skills/目录加载本地skills，也会自动读取项目的.codex/skills/。装法和Claude Code大同小异，但有个特别实用的功能——某些版本的Codex支持直接从GitHub URL安装：
codex skills add https://github.com/example/modeling-competition如果你用的Codex版本不支持这条命令，就老老实实走clone复制路线。OpenCode则把skills统一放在~/.config/opencode/skills/目录下，逻辑上跟前面两者一致，只是路径不同。
再说一句关于“skills下载”的常见困惑。很多人在网上搜索“skills网页版进入”“skills技能库网址”，其实是想找一个在线面板来管理技能。目前主流平台都没有成熟的可视化管理界面，最多也就是命令行里列个清单。我建议把skills当代码仓库管理，用Git来维护版本，更新、回滚都方便，比等官方出面板靠谱得多。
3. 值得安装的skill推荐清单
3.1 前端开发的几个神级技能
前端开发是skills生态里最成熟的方向之一。GitHub上搜索frontend skills能出来一堆仓库，但质量参差不齐。我实测下来值得装的有三类。
第一类是项目脚手架类skill，它会把新项目的初始化流程固定下来——自动问你项目类型、选技术栈、生成目录结构、装依赖、配好ESLint和Prettier。以前新建一个项目要手动敲十几条命令，现在一句话“按标准流程初始化一个React+TS项目”，skill会自动执行完所有步骤，还顺手帮你把README和.gitignore都建好。
第二类是UI审查类skill。这个是我最近才发现的宝藏，它会截图或者读取页面代码，按可访问性、响应式、视觉一致性、性能指标几个维度做代码审查，输出一份带优先级的问题清单。强烈建议前端团队统一装一个，代码评审的时候能省大量扯皮时间。
第三类是组件生成类skill，用来保证组件代码风格一致。比如规定所有组件必须用函数式写法、props必须写类型定义、样式必须走CSS Modules而不是全局类名。装了之后AI生成的代码会自动遵守团队规范，新人写出来的东西也不会跑偏。
3.2 数学建模和竞赛向的skills
华为杯、美赛、国赛这几年的AI辅助趋势非常明显。GitHub上已经出现了专为数学建模设计的skills仓库，最有代表性的是把完整竞赛流程拆成多个协作型skills的组合包。
我实测过一个组合，它包含四个skill：problem-analysis负责把赛题拆解成约束条件、目标函数和数据特征；model-selection根据问题类型推荐合适的数学模型并给出理由；code-implementation把模型转成可运行的Python代码，自动补全数据预处理和结果可视化；paper-writing则按照数模论文的标准结构生成LaTeX或Word模板，把图表、公式、参考文献的格式都预先排好。
用了这套skill之后，最大的变化不是AI写代码更快了，而是团队的思考过程被结构化了。以前三个人对题目理解不一样，讨论半天；现在每个人都用同一套skill去分析题目，输出的问题拆解结构是完全一致的，讨论效率明显提升。对准备华为杯的同学来说，提前把这类skills跑通，比赛期间确实能节省大量时间。
3.3 AI漫剧、内容创作类skills
别以为skills只能写代码，内容创作方向也已经有不少现成作品。AI漫剧这个热词背后其实也是一套skills：用AI生成分镜脚本、角色设定、提示词，再配合绘画模型出图。GitHub上有人把整套工作流封装成了skill，包括分镜模板、人物一致性描述模板、场景切换规则等等。
这类skill的核心逻辑是把“感觉”变成“规则”。一个漫剧创作者靠感觉描述分镜，每次输出的风格都飘忽不定；但一个well-crafted的skill会把镜头语言、叙事节奏、人物表情描述都结构化，AI每次生成的内容就更可控。内容团队如果想批量生产短视频脚本，同样可以做一个short-video-script的skill，把开头三秒抓眼球、中间反转、结尾引导关注的套路全部写进规则里。
4. 从零手写一个自己的skill
4.1 先想清楚四个问题再动手
写skill最大的误区是一上来就写SKILL.md。我自己的经验是，先花时间回答四个问题：这个skill是给谁用的？解决什么具体问题？触发场景是什么？期望的输出长什么样？
以我写的一个daily-standupskill为例——它让AI每天读取Git提交记录，自动生成站会汇报。定义目标时我写的是“减少团队站会准备时间，统一汇报格式”，触发场景是每天早上技术团队开工时，风险点是“AI可能误读提交信息导致汇报失真”。这四个问题想清楚之后，写SKILL.md就是水到渠成的事。
这里有个特别重要的设计原则：skill的适用范围宁窄勿宽。很多人写skill恨不得囊括所有场景，结果AI什么任务都往这个skill里套，输出反而更难用。好的skill就像一个好的函数——单一职责、输入输出清晰。
4.2 SKILL.md的写法细节
SKILL.md分两部分：YAML frontmatter和正文。frontmatter核心就是name和description两个字段，其中description决定了AI什么时候调用这个skill，一定要写清楚“适用于什么任务、不适用于什么任务”。
下面是一个可参考的最简模板：
--- name: daily-standup description: 读取Git提交记录生成站会汇报。适用于团队日常站会场景，不适用于代码审查。 --- # Daily Standup Skill ## 职责 - 读取最近24小时的git提交记录 - 按团队成员分组整理工作内容 - 标注阻塞项和风险点 ## 执行步骤 1. 运行 git log --since="24 hours ago" --pretty=format:"%an|%s" 2. 解析提交人、提交信息 3. 归类整理为：进行中、已完成、阻塞项 4. 输出Markdown格式站会汇报 ## 输出格式 ```markdown ### 今日站会（日期） **进行中**：... **已完成**：... **风险/阻塞**：...写正文时要注意指令的粒度。AI理解能力已经很强，但给它的步骤越明确，执行结果越稳定。我习惯把所有步骤写成“动作+命令+预期结果”三段式，比如“运行`git log`获取提交记录，解析其中的人名和提交说明字段，输出分组列表”。这样AI不会为了“创意”去过度发挥。 ### 4.3 scripts和references怎么组织 当skill需要执行复杂逻辑、处理文件、调用API时，把逻辑写进脚本，而不是让AI现场发挥。一个常见方案是`scripts/`目录下放Python或Shell脚本，`SKILL.md`里只写“运行scripts/analyze.py并读取输出”。 我自己的习惯是：一切有固定逻辑的操作都尽量脚本化。比如解析数据、调用外部API、批量重命名文件这些事，AI现场写代码也许能完成但每次风格都不一样，而且容易出错；写成固定脚本放进skill里，每次执行结果都是一致且可预测的。`references/`目录则用来放参考资料和模板，比如论文模板、代码规范文档、常见错误列表。AI在执行skill的时候会按需读取这些内容，等于给它配了一本操作手册。 ## 5. 常见问题与排查技巧实录 ### 5.1 装了skill但不生效，怎么排查 这是被问得最多的问题。装完skill没反应，90%是三个原因。第一是路径放错了，skill目录层级不对，AI根本没扫描到；第二是frontmatter格式有问题，`description`字段缺失或者不是字符串格式；第三是会话没有重启，AI没有重新索引技能列表。 按这个顺序排查最快：先用官方命令列出已加载的skills，比如Claude Code输入`/skills`，Codex用`codex skills list`。如果列表里压根没这个skill，就是路径或格式问题，检查目录名、检查YAML格式是否合法。如果列表里有但行为上没生效，问题多半出在`description`写得不够准确，AI判断这个任务和skill不匹配，所以不调用。这时候要重新打磨description里的触发条件描述。 ### 5.2 skill打架了怎么办 多个skill同时匹配同一个任务的情况很常见。比如你有`frontend-dev`和`react-component`两个skill，让AI写一个React组件的时候两个都可能被触发，结果AI一会儿遵守这个的规则一会儿遵守那个的，输出行为不稳定。 解决办法是给skill限定明确的边界。在`description`里写明触发条件，比如`react-component`专门负责“单个组件文件的新建与修改”，`frontend-dev`负责“整个前端项目的规划和架构”。这样重叠区域缩小，AI的匹配也更精准。实在有冲突，就删掉一个，别舍不得。 ### 5.3 清理和瘦身的实用方法 GitHub上调研热词的时候看到有人专门讨论“清理skills的方法”，这确实是个被忽视的痛点。装了几十个skill后，每次AI加载时都要花时间扫描索引，响应变慢是一方面，更重要的是AI的选择困难症会加重——候选skill越多越容易匹配错。 我的清理策略是定期收编。每个月把那些一次都没被触发过的skill挑出来，要么删掉，要么把多个同类的合并成一个聚合skill。还有一个实用习惯：全局skills目录只放通用性强的，项目级的就放在对应项目的`.claude/skills/`或`.codex/skills/`里，互不污染。Claude Code里可以直接`rm -rf`不想要的skill目录，但推荐先把它移到备份目录观察两周，确认不影响日常工作再彻底删除。 ## 6. 一些关于skills生态的个人观察 研究skills的这两周，我最大的感受是：这个机制把“AI提示工程”从聊天记录里解放了出来，变成了可版本管理、可分发、可协作的工程资产。坏处是，GitHub上技能库的质量鱼龙混杂，很多skill就是把几个大而全的prompt塞进去，既没有清晰的触发边界也没有可复用的脚本，装多了反而拖累效率。 我个人在实际操作中的体会是：与其追逐热门skills列表，不如把这个机制当成一套优化自己工作流的框架。你日常反复在做的事情——做周报、搭项目、写脚本、跑分析——都可以先手动把流程跑顺，再固化成一个skill。自己在真实场景里打磨出来的skill，永远比网上下载的通用包好用。 另外一个小技巧分享给刚开始接触的人：去翻一下你现在主力AI工具的官方文档里关于skills的章节，不同版本之间的规范差异比想象中大，社区里很多教程都是基于旧版本写的，照着操作很可能对不上。官方文档通常很短，但会写清楚路径、格式、版本要求，花二十分钟过一遍，能省掉之后几个小时的折腾。 最后说句实在的，skills这个方向还在快速演进，今天写的规范可能过俩月就变了。但核心思想——把AI的能力调用标准化、产品化——是不会变的。早点上手，等到生态成熟的时候你已经积累了一堆趁手的技能包，跑在很多人前面了。
