1. 从“skills”这个热词说起：它到底是什么，为什么突然火了
最近几个月，不管是在技术社区、AI 工具群，还是各种折腾效率工具的圈子里，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到：Claude、Agent Skills、SKILL.md、Claude Code、superpower skills、数学建模skills推荐、ai漫剧常用skills……这些词全都指向同一个东西——给 AI 智能体（Agent）装载的“技能包”。
说白了，skills 就是一套写给 AI 看的“操作手册”。它用结构化的方式告诉 AI：遇到某类任务时，应该按什么步骤做、调用哪些工具、注意哪些坑。你可以把它理解成给一个新员工发的 SOP 文档，只不过这个员工是 AI，而这份文档的格式是SKILL.md。
我最早接触这个概念是在折腾 Claude Code 的时候。当时想让 Claude 帮我处理一些重复性的代码审查工作，每次都要重新写一遍提示词，烦得不行。后来发现社区里已经有人把这类任务封装成了 skill，直接丢进指定目录就能用，那一刻的感觉就像发现了新大陆。再后来，superpower skills、codex nature skills、opencode skills这些不同平台和场景下的技能库陆续冒出来，skills 生态一下子就热闹了。
这篇文章我想从实操角度，把 skills 这件事讲透。不管你是刚听说Claude Code想试试水的新手，还是已经在用Claude但还没碰过 skills 的老用户，或者你是做数学建模、前端开发、AI 漫剧这类具体场景想找现成技能包的从业者，下面这些内容应该都能帮到你。我会重点讲清楚：skills 的核心结构长什么样、怎么从零写一个自己的 skill、怎么安装别人做好的 skill、以及我在实际使用中踩过的那些坑。
2. skills 的核心结构拆解：SKILL.md 到底怎么写
2.1 一个 skill 的最小构成单元
先看最核心的问题：一个 skill 到底由什么组成？答案比你想的简单——一个文件夹，里面放一个SKILL.md文件，再加上可选的辅助脚本和资源文件。
SKILL.md是整个 skill 的入口和说明书。它的格式是 Markdown 加 YAML frontmatter，结构大概长这样：
--- name: code-review-helper description: 对指定代码文件进行结构化审查，输出问题清单和改进建议 --- # 代码审查助手 ## 使用场景 当用户要求审查代码质量、查找潜在 bug 或提出改进建议时使用本技能。 ## 操作步骤 1. 读取用户指定的代码文件 2. 按以下维度逐项检查： - 变量命名是否清晰 - 是否存在未处理的边界条件 - 错误处理是否完整 - 是否有明显的性能问题 3. 输出格式：按严重程度分级列出问题，每条附带修改建议 ## 注意事项 - 不要自动修改代码，只输出建议 - 如果文件超过 500 行，先询问用户是否只审查关键部分这个结构看起来平平无奇，但每一部分都有它存在的理由。name和description放在 frontmatter 里，是为了让 AI 在决定是否调用这个 skill 时能快速判断。下面的正文则是给 AI 看的详细指令。
我试过把同样的内容直接写在对话里让 Claude 执行，效果远不如封装成 skill。原因在于：skill 会被系统预先加载到上下文里，AI 对它的“记忆”更牢固，执行时不容易跑偏。这就像你临时口头交代一件事，和写进工作手册里的区别。
2.2 为什么是 Markdown 而不是 JSON 或 YAML
有人可能会问：既然是给机器看的，为什么不用更结构化的 JSON？我一开始也有这个疑问，后来想明白了——skills 的使用者不只是机器，还有人。
Markdown 的好处是人和 AI 都能读。你写了一个 skill，同事想看看它干了什么，直接打开SKILL.md就能看懂，不需要额外的文档。而且 Markdown 天然支持自然语言描述，AI 对自然语言指令的理解能力已经足够强，没必要把所有东西都塞进严格的键值对里。
另一个实际原因是：skills 经常需要包含示例、注意事项、边界情况说明，这些内容用 JSON 表达会非常别扭。Markdown 的段落、列表、引用块刚好适合这种“半结构化”的表达。
2.3 辅助文件什么时候需要
不是所有 skill 都只有一个SKILL.md。当你的 skill 需要执行具体操作时，通常会搭配脚本文件。比如一个“批量重命名文件”的 skill，可能会包含一个rename.py，然后在SKILL.md里写明“调用同目录下的 rename.py 并传入参数”。
我的经验是：能用自然语言描述清楚的逻辑，就不要写脚本。脚本会增加维护成本，而且一旦环境变化（比如 Python 版本不同）就容易出问题。只有当任务涉及精确计算、文件操作、API 调用这类 AI 直接做容易出错的事情时，才值得写辅助脚本。
3. 从零手写一个 skill：完整流程和关键决策
3.1 先想清楚：这个 skill 解决什么问题
写 skill 最容易犯的错误是“为了写而写”。我见过有人把“帮我写周报”这种一次性任务也封装成 skill，结果用两次就扔了。一个好的 skill 应该满足两个条件：任务会重复出现，且每次的执行逻辑基本一致。
举个例子，我做前端开发时经常需要把设计稿的标注转换成 CSS 变量。这个任务每次的流程都一样：读取标注数据、按命名规范转换、输出变量文件。这种就非常适合做成 skill。而“帮我设计一个页面布局”这种每次需求都不同的任务，就不适合。
3.2 写 description 的讲究
description这一行看似简单，实际上直接影响 skill 会不会被正确触发。我踩过的坑是：description 写得太模糊，导致 AI 在该用的时候不用，不该用的时候乱用。
好的 description 应该包含三个要素：做什么、什么时候用、输出什么。对比一下：
- 差的写法：
description: 处理代码 - 好的写法：
description: 对 Python 代码进行 PEP8 风格检查和重构建议，当用户要求代码审查或提到代码规范时使用
第二种写法明确限定了语言（Python）、任务类型（风格检查和重构建议）、触发条件（用户提到代码审查或规范），AI 判断起来就准确得多。
3.3 操作步骤的粒度控制
写操作步骤时，粒度太粗 AI 会自由发挥，粒度太细又会让 skill 变得僵化。我的经验法则是：关键决策点写清楚，执行细节留给 AI。
比如写一个“数据清洗”的 skill，我会写明：
- 必须先检查缺失值比例，超过 30% 的列要询问用户是否保留
- 数值列和类别列要用不同的填充策略
- 输出清洗报告
但不会写明“用 pandas 的 fillna 方法，参数用 method='ffill'”。因为具体用什么库、什么参数，AI 根据实际数据情况判断可能比我预设的更好。
3.4 一个完整示例：数学建模辅助 skill
结合热搜词里“数学建模skills推荐”这个需求，我写一个实际可用的例子：
--- name: math-modeling-assistant description: 辅助数学建模竞赛，提供模型选择建议、论文结构规划和代码框架生成 --- # 数学建模辅助 ## 使用场景 用户正在准备数学建模竞赛，需要模型选型、论文框架或代码实现方面的帮助。 ## 工作流程 ### 第一步：问题分析 - 阅读题目，识别问题类型（优化、预测、评价、分类等） - 列出已知条件、目标函数、约束条件 - 如果题目信息不完整，向用户确认 ### 第二步：模型推荐 根据问题类型推荐 2-3 个候选模型，说明各自优缺点： - 优化类：线性规划、整数规划、遗传算法、粒子群优化 - 预测类：时间序列、回归分析、神经网络、灰色预测 - 评价类：层次分析法、熵权法、TOPSIS、模糊综合评价 ### 第三步：论文框架 按标准竞赛论文结构输出大纲： 摘要、问题重述、问题分析、模型假设、符号说明、模型建立与求解、模型检验、灵敏度分析、模型评价与推广 ### 第四步：代码框架 生成对应模型的 Python 代码骨架，包含数据读取、模型定义、求解、结果可视化四个部分。 ## 注意事项 - 不要直接给出完整论文，只提供框架和思路 - 模型推荐要结合题目数据特点，不要盲目推荐复杂模型 - 代码框架要包含注释，方便用户理解和修改这个 skill 我实际用过几次，最大的感受是：它把“从零开始想”变成了“在框架上填充”，效率提升非常明显。尤其是论文框架那部分，直接省掉了大量纠结结构的时间。
4. 安装和使用现成 skills：各平台操作指南
4.1 Claude Code 下的 skills 安装
Claude Code是目前 skills 生态最活跃的平台之一。安装 skill 的基本流程是：
- 找到 skill 的存放目录。在 Claude Code 中，通常是项目根目录下的
.claude/skills/或者用户主目录下的~/.claude/skills/ - 把下载的 skill 文件夹整个复制进去
- 重启 Claude Code 或者重新加载会话
这里有个容易踩的坑：目录层级。有些 skill 压缩包解压后会多一层文件夹，比如code-review-helper/code-review-helper/SKILL.md，这样 Claude Code 是识别不到的。正确的结构应该是skills/code-review-helper/SKILL.md。
另外，热搜词里有人问“claude code怎么手动装github上的skills”，答案就是：从 GitHub 下载仓库后，找到包含SKILL.md的那个文件夹，整个复制到 skills 目录下。如果仓库里有很多 skill，就挑你需要的复制，不用全装。
4.2 验证 skill 是否生效
装完之后怎么确认 skill 被正确加载了？我的做法是：直接问 AI。在对话里输入“你现在有哪些可用的 skills”，如果安装成功，AI 会列出已加载的 skill 名称和描述。
如果没生效，按这个顺序排查：
- 检查
SKILL.md的 frontmatter 格式是否正确（---不能少，name和description必须有） - 检查文件编码是否为 UTF-8
- 检查目录层级是否多了一层
- 检查是否有语法错误导致整个文件解析失败
4.3 不同平台的差异
除了 Claude Code，opencode skills、codex nature skills等平台也支持类似的机制，但目录位置和加载方式略有不同。共同点是：核心都是SKILL.md文件，差异主要在存放路径和触发机制上。
我的建议是：如果你主要用某个平台，就按那个平台的文档来。如果多个平台都用，可以把 skill 放在一个统一的仓库里管理，用脚本同步到各个平台的目录下。这样维护一份源文件就够了。
5. 常见问题与排查技巧实录
5.1 skill 不触发怎么办
这是最高频的问题。AI 没有按预期调用你的 skill，通常有三个原因：
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 完全不触发 | description 太模糊 | 重写 description，加入具体触发词 |
| 偶尔触发 | 与其他 skill 功能重叠 | 明确区分各 skill 的适用边界 |
| 触发但执行不对 | 操作步骤描述有歧义 | 细化关键步骤，增加示例 |
我遇到过一次典型情况：写了一个“生成 API 文档”的 skill，但 AI 总是用另一个通用的“写文档”skill。后来发现是两个 skill 的 description 都包含了“文档”这个词，AI 分不清该用哪个。解决办法是在 API 文档 skill 的 description 里加上“当用户提到 API、接口、端点时使用”，把触发条件收窄。
5.2 skill 之间冲突怎么处理
当你装了很多 skill 之后，冲突几乎不可避免。我的处理原则是：功能相近的只保留一个，或者明确划分使用场景。
比如同时装了“代码审查”和“代码优化”两个 skill，前者关注规范问题，后者关注性能问题。如果 description 没写清楚，AI 可能在该做性能优化时调用了代码审查 skill。这时候要么合并成一个 skill 用条件分支处理，要么在各自的 description 里写清楚“仅用于 XX 场景”。
5.3 性能问题：skill 太多会不会拖慢响应
会。每个 skill 的SKILL.md内容都会被加载到上下文里，skill 越多，占用的 token 越多，AI 的响应速度和准确性都会受影响。我的经验是：同时启用的 skill 控制在 10 个以内，不常用的及时禁用或移出目录。
热搜词里有个“tibo关于清理skills的方法推荐”，虽然我没看过具体内容，但清理思路无非就是：定期审查、合并重复、归档不用的。我自己的做法是建一个skills-archive文件夹，把暂时不用的 skill 移过去，需要时再移回来。
5.4 跨平台兼容性注意事项
如果你写的 skill 打算分享给别人用，要注意不同平台的兼容性。主要差异点：
- 文件路径分隔符（Windows 用反斜杠，其他用正斜杠）
- 脚本执行环境（Python 版本、依赖库）
- 特殊指令的写法（有些平台支持特定标记，换平台就失效）
我的做法是：尽量用纯自然语言描述，少依赖平台特有功能。这样写出来的 skill 通用性最强，换个平台基本都能用。
6. 进阶玩法：把 skills 组合成工作流
单个 skill 解决单个问题，但实际工作中往往需要多个 skill 配合。比如做一次完整的数据分析项目，可能涉及：数据清洗 skill、特征工程 skill、模型训练 skill、结果可视化 skill。
我的做法是写一个“元 skill”，在SKILL.md里定义整个工作流的步骤，每一步引用对应的子 skill。这样 AI 在执行时会按顺序调用各个子 skill，形成流水线。
这种组合方式的好处是：每个子 skill 可以独立维护和复用，工作流 skill 只负责编排。改一个子 skill 的逻辑，所有用到它的工作流都会自动更新。
不过要注意，组合 skill 的调试比单个 skill 麻烦。我的建议是先把每个子 skill 单独测试通过，再组装成工作流。否则出了问题很难定位是哪个环节的毛病。
7. 我个人的一些实操心得
写了这么多 skill，有几个体会特别深。
第一，不要追求大而全。我一开始写了一个“全能编程助手”skill，想把代码生成、审查、调试、文档全包进去。结果 AI 执行时经常混淆任务类型，效果还不如不装。后来拆成四个独立 skill，每个只做一件事，反而准确率高得多。
第二，description 值得反复打磨。我有个习惯：写完 skill 后，用不同的问法测试十几次，看触发率如何。如果发现该触发的时候没触发，就回去改 description。这个过程很枯燥，但效果立竿见影。
第三，版本管理很重要。skill 也是代码，改坏了要能回滚。我用 Git 管理 skills 目录，每次修改都提交，出问题随时回退。这个习惯帮我省过好几次事。
第四，别忽视社区的力量。热搜词里提到的superpower skills、typesafe ai skills github这些，都是社区沉淀下来的优质资源。与其自己从零写，不如先看看有没有现成的，在别人的基础上改比从头造轮子快得多。
最后分享一个小技巧：如果你不确定某个任务适不适合做成 skill，先手动做三遍。如果三遍的流程基本一致，那就值得封装；如果每次都不一样，说明这个任务还没形成稳定模式，再等等。这个判断方法我用了很多次，基本没出过错。
