玩AI编程这段时间，我踩过最大的坑就是：每次新开一个项目，都得把同样的背景、同样的规则、同样的工作流给AI重新讲一遍。直到我把目光投向了一个叫skills的东西，情况才真正变了。GitHub上现在随手一搜就是一堆skills仓库，前端开发的、数学建模的、AI漫剧脚本的，整个生态已经热得发烫。但说实话，网上关于skills的信息挺杂的，教你怎么装的有，教你怎么写的有，但能把原理、实操、避坑串起来讲清楚的不多。这篇文章就是我自己的全套经验，从概念到手动安装GitHub上的skills，再到动手写一个能用的skill，最后是常见的坑和清理维护方法，一次说透。
1. skills到底是什么，它和提示词的区别在哪
先说个结论：skills在很大程度上是“提示词”的进化形态，但它不是简单地把提示词攒成一个文件。早期我们用AI写代码，习惯是把项目背景、技术栈、约束条件、期望输出格式一股脑写进system prompt或对话上下文里。这个做法在单次对话里没问题，但只要换一个会话、换一个项目，一切归零，又得重新搬运一遍上下文。更麻烦的是，提示词越长，AI的理解就越容易跑偏，有些规则会被稀释，有些会被遗忘，效果极其不稳定。
skills解决的正是这个问题。它的本质是一套结构化的、可复用的“专业能力包”，里面不仅有指令文本，还可以附带示例、模板、检查清单、脚本工具，甚至是决策流程。Claude Code、Codex CLI这类AI编程工具会通过一个约定的目录结构加载skills，让AI在开始干活之前先“读一遍手册”，然后带着这套手册去执行任务。换个更贴近生活的比喻：提示词相当于你在咖啡馆口头交代店员“我要一杯少糖去冰的拿铁”，而skills相当于给了店员一本完整的饮品SOP手册，里面写着配方、杯型、温度标准、出品检查表。后者当然稳定得多。
还有一个很关键的区别是触发机制。普通的提示词是你每次手动粘贴进去的，而skills是可以被AI自动识别和调用的。很多工具支持在skill的元数据里写明“这个skill适用于什么场景”，AI会先判断当前任务属于哪一类，再决定要不要加载对应的技能包。这有点像给AI装了一抽屉的工具，它自己看着办。你现在问我推荐哪个方向先入门，我的意见很明确：如果你是做前端开发的，先去找几个前端相关skills来用；如果你在备战华为杯这类建模比赛，那数学建模skills是刚需。因为这类场景通常任务链路长、规范要求高，最能体现出skills的价值。
2. 一个skill的内部结构，手把手拆给你看
很多人在GitHub上看到一个skill仓库，clone下来之后发现里面有几个目录和Markdown文件，但不太清楚每个东西是干嘛的。这里我拿一个典型的skill目录结构来拆解，所有基于Claude Code/Codex体系设计的skills，万变不离其宗：
your-skill-name/ ├── SKILL.md # 技能主文件，包含元信息与核心指令 ├── references/ # 参考资料，可以是文档、论文、代码样例 ├── scripts/ # 可执行脚本，辅助AI完成重复性工作 ├── templates/ # 输出模板，约束最终交付物的格式 └── examples/ # 示例输出，给AI一个“仿写”的参考这里最核心的就是SKILL.md这个文件。它一般分成两个部分：YAML格式的frontmatter元数据和正文指令。frontmatter里常见字段有name（技能名称）、description（这个技能干什么、适合什么场景）、allowed-tools（允许调用哪些工具），这些字段是给AI的“索引卡片”，决定了它在什么时候被想起。正文部分则是一段完整的操作指导，AI会把这段内容当成最高优先级的工作手册。
举个具体例子，一个“代码审查skill”的SKILL.md可能是这样：
--- name: code-review description: 用于对代码变更进行系统性的审查，发现逻辑错误、安全隐患与性能瓶颈，适用于PR评审或提交前自检。 --- # 代码审查流程 1. 先阅读diff，理解变更目标 2. 按以下维度逐项检查： - 逻辑正确性：边界条件、异常分支 - 安全性：注入、越权、敏感信息 - 性能：循环嵌套、重复计算、不必要的IO 3. 每个问题按严重程度标注：Critical / Warning / Suggestion 4. 输出审查报告，采用 templates/review-template.md很多新手犯的错是只写了“请你审查代码”一句话，剩下的全靠AI自由发挥。这当然也能用，但不同会话里的发挥水平差距极大。好的SKILL.md必须把“怎么审、按什么顺序审、用什么格式输出”全部固定下来，让AI每次的结果都稳定在一个水准线上，这才是skill存在的意义。
另外说一下references和scripts这两个目录，它们是让skill从“会说话”变成“会干活”的关键。references里面放的是需要被引用的背景知识，比如团队内部的编码规范、项目的架构文档，AI会根据任务需要去查阅。scripts则更硬核，比如一个“批量重命名文件”的skill可以在scripts里放一个Python脚本，AI只需要生成调用命令，脚手架和逻辑都在脚本里。这样就把AI的长处（理解意图、分解任务）和代码的确定性（执行结果一致）接合起来了。
我个人的经验是：写skill不要一开始就追求大而全。先从一个你每周都会重复的任务开始，把它写成skill，跑通一轮，再慢慢加references和scripts。第一次就试图把复杂业务全塞进去，只会得到一个臃肿又难调的东西。
3. 手动安装GitHub上的skills，其实就三步
关于“Claude Code怎么手动装GitHub上的skills”这个问题，我见过太多教程写得云里雾里，实际上手你会发现特别简单，核心就是“把仓库clone到工具能扫描到的目录”。不同的工具有不同的默认扫描路径，但思路统一。以Claude Code为例，项目级skills放在项目根目录下的.skills/文件夹里，全局skills放在用户配置目录下的skills文件夹里。Codex这边的常见路径是~/.codex/skills，项目级则是项目目录下的.codex/skills。
操作流程如下：
- 找到你想安装的skill仓库，复制Git地址
- 打开终端，进入对应生效目录，执行clone命令，并清理仓库外层文件夹
- 检查skill目录下是否存在SKILL.md，确认frontmatter格式正确
实际命令大概是这样的：
# 进入项目级skills目录（以Claude Code为例） cd /path/to/your/project/.skills # 克隆远程仓库 git clone https://github.com/某个用户/某个skill仓库.git # 有些仓库自带版本号或多余外层目录，clone完确认一下结构 ls -la这里有个小坑很容易被忽略：有些skill仓库clone下来之后顶层文件夹和URL后缀不一致，或者里面嵌套了好几层目录，结果工具扫描不到。你需要保证的是“在skills目录下的直接子目录里能找到SKILL.md”，路径不能太深。比如.skills/superpower/learn-skill/SKILL.md这种就属于路径过深，工具大概率识别不了，需要手动整理目录结构。
装完之后怎么确认成功了？两个方式：一是直接在对话里让AI“列出你当前可用的skills”，它会把扫描到的技能包名字给你；二是用这个skill实际跑一个任务，看它的行为是否有明显变化。如果AI给出的回答和没装之前一模一样，那大概率是没被加载，优先排查路径和SKILL.md格式。
对于opencode这类新工具，安装逻辑大同小异。它们的配置中心化程度更高，一般都支持在配置文件里显式声明skill路径。我的建议是：一次性把所有工具的skills目录都统一到同一个文件夹，然后在各自的配置文件里指向这个公共目录。这样你换工具的时候不用重装一遍，维护成本低很多。
还有一点要提醒：从GitHub上装skill之前，一定先看一眼仓库的星标和更新时间，简单读一下SKILL.md确认质量。现在skills生态处于野蛮生长期，有不少“看起来很厉害但实际就是几行废话”的劣质包，装多了不仅占用上下文窗口，还会干扰AI的正常判断。宁缺毋滥。
4. 从0写一个skill：以数学建模场景为例
数学建模skills之所以火，是因为建模比赛的项目周期极短、流程极标准化：审题、问题分析、模型假设、建模求解、结果检验、论文写作，每一环都有很强的套路。把这些套路沉淀成skill，等于把一支冠军队伍的作战方式交给了AI。我用华为杯和国赛的需求来举例，给你完整演示一个skill的开发过程。
先定义这个skill的目标：输入一道建模题目，输出一套完整的“解题作战流程”——包括选题分析、模型匹配建议、数据预处理指引、求解工具推荐、论文大纲。这个目标已经足够具体，可以开始写SKILL.md。
frontmatter部分要写清楚触发场景：
--- name: mathematical-modeling description: 适用于数学建模竞赛（国赛、华为杯等）解题全流程规划，包括问题重述、模型选择、求解策略、论文写作指导。 ---正文部分，我按“先框架后细节”的原则来组织：
- 问题重述与分类：判断题目属于优化类、预测类、评价类还是机理分析类，不同类型的模型偏好不同
- 数据预处理：缺失值处理、异常值检测、标准化方法选择
- 模型选择：提供一张决策表，把问题类型、数据量、精度要求映射到候选模型
- 求解与验证：敏感性分析、误差指标、可视化要求
- 论文结构：摘要、问题分析、模型假设、模型建立与求解、模型评价、改进方向
写到这里你会发现，好的SKILL.md其实是一份“决策树+Checklist”。它不给AI一个死板的答案，而是给它一套在不确定中做判断的规则。比如“当数据量小于200条时，优先考虑统计模型而非神经网络”，这比“请选择合适的模型”有用一百倍。
如果要在实战中用这个skill，还可以配合一个example文件，放一份往年优秀论文的摘要，让AI模仿它的句式结构来撰写摘要。AI写摘要的水平高度依赖样例的风格，references目录里放三到五篇不同的摘要风格示例，输出质量会明显稳定下来。
开发完成之后一定要测试。我自己一般的做法是拿往年试题跑一遍流程，看AI是否真的按SKILL.md里的步骤走。如果它跳过了某一步，说明正文里那一步写得太含糊，需要补细节。测试完记得把测试结果和调整过程写进CHANGELOG，方便后续迭代。
同理，AI漫剧场景的skill也是这个套路，只不过把“模型选择”“求解验证”换成“分镜脚本生成”“角色一致性描述”“画面提示词转换”。创意类skills的编写诀窍是给足格式模板，让AI在固定的结构里发挥有限的创意，而不是放飞自我。
5. 常用的skills推荐，按场景选不踩雷
现在GitHub上的skill仓库数量已经多到看不过来了，我按自己的实际使用频率，给你整理一份按场景分类的清单，作为选型参考。
| 场景 | 推荐方向 | 作用 |
|---|---|---|
| 前端开发 | 组件生成、代码审查、重构建议 | 保持代码风格一致，减少重复劳动 |
| 数学建模 | 全流程作战、模型匹配、论文润色 | 比赛周期压缩到极限时的救命稻草 |
| AI漫剧/短片 | 分镜脚本、角色一致性、提示词转换 | 把零散创意变成可执行的制片流程 |
| 通用工程 | 日志分析、Bug定位、性能优化 | 处理跨项目的日常工作流 |
| 学习型 | 概念讲解、项目拆解、代码导读 | 用AI辅助快速上手陌生技术栈 |
这里要专门说一个热度很高的词：superpower skills。它本质上是一套经过精细设计的skills集合，强调不改变工具本身的能力，而是通过skill给AI“加buff”，比如让AI学会更聪明的追问、自动拆解复杂任务、自主检查输出质量。我的体验是，这类通用型skill比较适合作为起步配置，能明显提升AI的“默认发挥水准”，但它解决不了垂直领域的专业问题，所以垂直方向还是需要专门技能包。
使用skills还有一个常见误区是装太多。AI编程工具的上下文窗口是有限的，虽然现在各家都在扩大上下文，但每个被加载的skill都会占用一定空间。当你同时加载了十五个skill，后续对话的有效上下文就被挤压了，AI反而容易变得迟钝。我目前的习惯是：项目级只保留和当前任务强相关的3到5个，全局级保留不超过10个，其余的按需再装。
如果你关注过“tibo关于清理skills”的思路，你会发现他讲的核心其实是“技能库卫生学”：定期检查哪些skill一周内没被触发过，哪些skill输出的内容总是被删改，哪些skill与其他skill存在指令重叠。这类skill直接禁用或删除，不要心软。留着它们不会带来任何安全感，只会让AI做判断时多出很多干扰信号。清理技能库和清理衣柜是一个道理：把不穿的衣服全部送走，剩下的每一件都是能打的。
6. 踩坑实录与排查方法，都是真金白银换来的
最后聊聊实际操作里最常见的几个问题，每一个我都自己碰到过，而且都花了不少时间才定位到根因。先把它们整理成一张速查表：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| skill完全没生效 | 目录路径不对或SKILL.md不在直接子目录 | 检查目录层级，确保SKILL.md在skills目录的下一级 |
| 只有部分指令生效 | frontmatter格式错误 | 用YAML解析器验证元数据，注意缩进 |
| AI输出质量比手动提示词还差 | skill内容与任务目标不匹配 | 重写正文，聚焦任务边界，删掉废话 |
| 加载后对话变卡 | 同时加载太多skill | 精简技能数量，只留强相关的 |
| 与现有工具链冲突 | allowed-tools写得不合理 | 检查元数据中的工具声明，收窄权限 |
先说说最坑的frontmatter解析问题。YAML格式对缩进和冒号空格极其敏感，很多时候你看着没问题，解析器直接静默失败，或者把description字段读成了空字符串。我踩过一次：description里写了一句很长的话但忘了加引号，结果工具扫描时完全忽略了这个skill，查了半天才发现是这个引号的问题。现在我的习惯是写完SKILL.md之后，先在本地用Python跑一下yaml.safe_load，确认能解析通过再放进skills目录。
另一个高频问题是“skill与需求错位”。比如你装了一个“重构辅助”的skill，它的description写着“适用于Python项目优化”，你却在一个JavaScript项目里反复调用它。AI可能会尝试套用Python的编码规范来审查JS代码，然后给出大量无用建议。这不是AI笨，是skill的触发机制本身依赖description里的语义匹配，你给的信息太宽泛，它自然容易“拿错剧本”。所以选型时一定要看description写的是不是你的场景，而不是看到“重构”两个大字就装进来。
还有一类问题是上下文污染。有些skill写了一大堆套话，AI每次加载都要先“读”一遍这堆没有营养的内容，真正用于思考的空间就变少了。我在排查“AI变呆了”的问题时，把skills逐个停用做对比测试，最后发现就是其中某个大而全的通用skill在拖后腿。它的本意是让AI每次回复前做十项自查，结果每一项自查都在消耗推理资源，最后产出的答案反而更保守、更平庸。这个教训很深刻：skill的设计目标应该是“让AI在正确的方向上少走弯路”，而不是“让AI每一步都战战兢兢”。
最后再说一个维护技巧：学会看日志。Claude Code和Codex在运行时会输出诊断信息，包括加载了哪些skill、每个skill的触发命中情况。养成定期查看日志的习惯，你会对自己技能库的“使用率”有非常清楚的认识。那些三个月都不触发一次的skill，在下次整理时直接清理掉，这就是我在反复试错后验证过的最有效的管理方式。
根据我个人经验，skills这套玩法目前还处于快速迭代期，工具支持的细节、目录规范、分发方式都在不停演进，但这个方向不会变——给AI沉淀可复用的工作流程，让它越用越贴合你的习惯。最值得投入时间的，不是疯狂收藏别人的技能包，而是把你手头重复了无数遍的那个流程，拆成规则、写成SKILL.md、跑通它。这个过程本身，比任何现成的技能包都值钱。
