最近这半年，我几乎把所有精力都花在折腾 AI 编程工具上，从 Claude Code 到 Codex，再到 OpenCode，每个都试了个遍。一开始以为这些工具的核心竞争力是模型本身，后来发现，真正让它们从"能用"变成"好用"的，反而是那些不起眼的 skills 技能包。今天想好好聊聊这个话题，把我的实践经验、踩过的坑、以及一套可以直接上手的技能包开发流程都分享出来。

如果你也在用 Claude Code、Codex 这类命令行 AI 编程工具，或者正在研究怎么让 AI 更稳定地完成特定任务，这篇文章应该能帮你省下不少时间。我会从 skills 到底是什么说起，然后逐步拆解它的安装、开发、推荐来源，最后附上我整理的问题排查经验。

先说个结论：skills 技能包就像给 AI 装了一套"专业领域的工作手册"，它本身不是代码逻辑，而是一套结构化的指令和上下文规则。你装得越精准，AI 的输出就越稳定，越接近一个真正了解你项目的资深同事。

1. 深入理解 Skills：AI 的"岗位说明书"

1.1 打破误区：Skills 不是插件也不是 Prompt 模板

我经常看到有人把 skills 和插件（Plugin）、MCP（Model Context Protocol）服务器、普通 Prompt 模板混为一谈，这其实是最大的认知误区。

简单来说，插件负责"让 AI 能调用某个外部工具"，MCP 负责"统一 AI 与外部系统的通信协议"，而 skills 负责的是"告诉 AI 在这种情况下应该怎么做才算专业"。你可以把 skills 理解成一套 SOP（标准作业程序），而不是一把扳手或一个 API 接口。

举个例子，你给 AI 装一个"代码审查 skill"，这个 skill 内部不会去调用任何静态分析工具，它提供的是：

• 审查时应该关注哪些维度（安全性、性能、可读性、边界条件）
• 输出报告时应该用什么模板（严重级别、问题定位、修复建议）
• 哪些场景下应该拒绝自动修复，只做提示

这本质上是在约束 AI 的行为范式，而不是给它新的能力。理解这一点非常关键，因为后面你自己写 skills 的时候，思路会完全不同——你不需要去考虑"怎么让 AI 调工具"，你考虑的是"怎么让 AI 像一个有经验的人那样思考和表达"。

1.2 Skills 为什么突然火了

从 TypeSafe AI 提出第一个可复用的 SKILL.md 开始，到 Superpowers Skills 在 GitHub 上引起关注，再到 Claude Code、Codex 在今年陆续原生支持 skills 目录，这个生态的爆发速度非常快。

背后有两条核心逻辑：

第一，大模型的上下文窗口再大，也不可能把所有领域的最佳实践都塞进一次对话里。通过本地加载 skills 文件，AI 可以在任务开始前"阅读"相关领域的操作方法，用很小的 token 成本换取极高的行为一致性。实测下来，一个 300 行左右的 skill 文件，加载成本不过几千 token，但能让 AI 在后续数小时内的输出质量保持稳定，这是单纯靠提示词堆砌根本无法实现的。

第二，skills 是天然可复用的。你写完一个"数据清洗 skill"，不只是你自己能用，整个团队、甚至整个社区都能用。GitHub 上已经出现了大量开源的 skills 仓库，从编程开发到数学建模，从内容创作到数据分析，几乎覆盖了各个场景。

我个人体会最深的是：以前给 AI 布置任务，每次都像在"开盲盒"，同样的需求，它这次这么做，下次那么做，完全没有稳定性。引入 skills 之后，至少 80% 的任务变成了"标准化交付"，这对工作效率的提升是革命性的。

1.3 主流平台的 Skills 生态现状

不同工具的 skills 实现方式有所差异，我用过一段时间后，总结出了各自的定位：

这里有个很实用的经验：如果你写了一个 skill，想让它在多个工具里通用，尽量把核心内容放在一个纯 Markdown 文件里（比如 SKILL.md），然后用各平台自己的目录结构去引用它。不要为了某个平台写一堆特定配置，那样反而失去了复用性。

2. 手把手：怎么手动安装 GitHub 上的 Skills

2.1 安装前需要知道的三件事

很多新手一上来就急着把仓库 clone 到本地，结果装完发现根本没法用，问题通常出在三个地方。

第一，确认你的工具版本是否支持 skills。比如 Claude Code 在某个版本之前只能通过插件系统加载技能，原生 skills 目录是后来才加的。我建议先执行一下版本检查命令，确认所在版本支持以后再做下一步。

第二，确认 skill 的目录结构是否规范。一个标准的 skill 必须有入口文件（通常叫 SKILL.md），并且在文件头部包含 YAML frontmatter，声明 name 和 description 字段。如果没有这些元数据，工具无法识别这个目录是一个 skill，装进去也是白装。

第三，确认 skill 的依赖环境。有些 skills 需要特定命令行工具（比如 jq、ffmpeg、node），有些需要网络访问特定的 API。安装之前最好看一下 README 里的依赖说明，否则运行时会频繁报错。

2.2 完整安装流程：以 Claude Code 为例

我先以 Claude Code 为例，演示手动安装一个 GitHub skill 的完整流程。假设我们要安装的是某个知名的前端开发 skills 包。

第一步，进入你的项目根目录，创建 Claude Code 的配置目录。如果项目还没有这个目录，手动创建一个即可：

mkdir -p .claude/skills

第二步，把目标 skills 仓库 clone 到临时目录，或者直接下载需要的 skill 文件夹。GitHub 支持手动下载单个文件夹，这里推荐一个很实用的方法——用svn export或者直接用 GitHub 的在线目录下载工具，当然最稳妥的还是完整 clone 后复制：

git clone https://github.com/某用户/某-skills-仓库.git /tmp/skills-temp

第三步，查看仓库结构，找到你想要安装的那一个 skill 子目录。比如仓库结构可能是这样的：

某-skills-仓库/ ├── README.md ├── code-review/ │ ├── SKILL.md │ └── review-template.md └── frontend-dev/ ├── SKILL.md └── rules/ └── vue-guidelines.md

第四步，把对应目录复制到项目的.claude/skills下：

cp -r /tmp/skills-temp/frontend-dev .claude/skills/

第五步，回到项目根目录，启动 Claude Code，随便发起一个相关任务，观察 AI 是否自动加载了这个 skill。通常 AI 会在思考过程中引用 SKILL.md 里的内容，或者在回答开头提到"根据技能包的规范，我将……"之类的话。有这种反应就说明安装成功了。

2.3 Codex 与 OpenCode 的安装差异

Codex 的安装流程与 Claude Code 类似，只是目录名要改成.codex/skills。但有一个关键差异——Codex 对 SKILL.md 头部 YAML 的 description 字段有更严格的要求。它推荐使用第三人称描述，并且尽量包含可触发的关键词。举个例子：

--- name: frontend-review description: 用于前端代码审查，关注 Vue/React 项目的性能、安全、可访问性。当用户要求 review 前端代码、检查组件质量或优化交互时可以触发使用。 ---

这段描述里的"review 前端代码""检查组件质量""优化交互"都是触发词。AI 会根据任务语义检索对应的 skill，触发词写得越准，命中率越高。

OpenCode 则更加轻量，它基本遵循通用的 skills 目录规范，但有一个额外约定：如果 SKILL.md 里写了allowed-tools字段，OpenCode 会优先在该字段声明的工具集内选择调用，这个设计很适合做一些受限场景的定制。

2.4 安装失败的典型症状与对策

在实际操作中，最常见的安装失败症状有以下几种：

• 症状一：AI 完全无视 skill，回答内容和以前一样。这多半是因为 description 字段写的太笼统，或者触发词没有覆盖用户的表述习惯。
• 症状二：AI 报错"Unknown skill"或者"Skill not found"。这说明目录结构不对，工具没有扫描到你放的技能目录。
• 症状三：skill 加载了，但执行到一半因为缺依赖中断。这是没看 README 的典型结果，先把依赖装好再试。

我自己吃过最大的亏是：把整个仓库直接塞进了 skills 目录，而没把单个 skill 子目录作为最小单位。结果工具扫描到一堆嵌套的 SKILL.md，行为变得非常奇怪。后来才明白，每个 skill 目录必须保持扁平结构，里面只能有一个 SKILL.md 入口，其他辅助文件都是被它引用的资源。

3. 从零开发一个自己的 Skills：核心环节全拆解

3.1 SKILL.md 的标准结构与编写心法

如果你打算自己写 skill，最重要的一件事就是掌握 SKILL.md 的标准结构。做到了然于胸，后面所有的灵感都可以直接落成文件。

标准结构分三块：YAML frontmatter、正文指令、参考资源清单。

YAML frontmatter 是最先被 AI 读取的部分，它决定了这个 skill 什么时候被触发。name 字段很简单，description 字段则需要仔细打磨。我之前写过一个教训：第一次写 description 只写了一句"用于文本润色"，结果任何涉及写作的任务都会触发它，干扰严重。后来改成"当用户需要改写、润色或压缩长文本，或者希望调整语气风格时使用，不适用于翻译和代码注释生成"，效果立刻精准很多。

正文部分是核心指令，要根据任务类型采取不同的写法。对于流程型任务，用编号列表列出每一个步骤；对于检查型任务，用 checklist 形式给出所有检查项；对于创作型任务，用案例对比来示范"好"与"坏"的差异。这里要特别强调：宁可写得啰嗦，不要写得含糊。因为你写的每一句话都会被 AI 当作硬性要求来执行，含糊的表述会让 AI 自由发挥，结果就不受控。

参考资源清单是可选的，但你如果希望 AI 每次执行时都能参考特定模板、代码库，最好以相对路径的方式把这些资源文件放进 skill 目录，然后在 SKILL.md 末尾用明确的语句声明"执行任务前必须阅读文件 xxx"。

3.2 设计一个"数学建模辅助" Skill 的全程示例

我拿自己用得最顺手的"数学建模辅助" skill 来做一个完整拆解，这个 skill 是从华为杯备赛开始写的，后来在多次实战中打磨完善，思路非常有代表性。

首先是 design（设计）阶段。我在写这个 skill 之前，先问自己三个问题：

• 这个技能主要服务哪类任务？（数学建模的赛题分析、模型选择、论文排版）
• 用户最常踩的坑有哪些？（乱选模型、不检验假设、论文结构混乱）
• 希望 AI 表现出什么样的行为范式？（先分析再建模、先验证再写结论）

想清楚以后，我搭建了这样的目录结构：

math-modeling/ ├── SKILL.md ├── templates/ │ ├── a4-paper-structure.md │ └── model-selection-guide.md └── examples/ ├── regression-case.md └── optimization-case.md

然后写了 SKILL.md 的核心指令，节选如下：

--- name: math-modeling description: 用于数学建模竞赛或课后建模任务。当用户需要选题分析、模型选择、数据预处理、结果验证、论文结构设计时使用。如果用户只是要求做简单的数据绘图，不需要使用本技能。 --- # 数学建模辅助指南 ## 执行流程 1. 与用户确认问题类型：优化类、预测类、评价类还是分类聚类类。 2. 如果用户提供了数据，先执行探索性数据分析（EDA），检查缺失值、异常值和量纲差异。 3. 基于问题类型推荐 1~2 个核心模型，并说明选择理由，不要超过 3 个候选。 4. 建立模型时必须同时给出假设检验方法。回归类模型需要检查多重共线性，优化类模型需要分析约束条件的可行性。 5. 结果输出统一包含三部分：模型表达式、参数含义、误差或敏感度分析。 6. 如果用户需要写论文，参考 templates/ 下的结构模板，输出章节骨架后逐节填充。 ## 禁忌 - 拒绝回答"推荐一个最牛的模型"这类问题，必须结合数据量和问题场景来决定。 - 不要滥用深度学习模型，当传统统计模型足够有效时优先使用传统方法。 - 永远不要跳过数据质量检查，哪怕是时间紧迫。

写完这一版之后，我真实跑了几个题目测试，发现 AI 有时候会绕过步骤 4 的假设检验，直接给出漂亮的模型公式。后来我在禁忌里又加了一条强约束："输出任何回归结果前，缺失 R²、F 统计量和残差诊断结论时，必须暂停输出并补充完整。"这才把行为稳定下来。

3.3 开发过程中容易犯的五个错误

第一个错误是野心过大，一个 skill 想覆盖所有场景。我最初想写一个"万能写作助手" skill，结果什么任务都处理不好，因为指令彼此冲突。建议初始设计尽量聚焦在单一任务族上，等稳定后再拆分子技能。

第二个错误是只写正向要求，不写约束条件。很多人的 skill 就是一堆"要怎么样"的清单，而那些"不要怎么样"的边界条件只字未提。AI 在没有禁忌约束的时候，倾向于自作主张，所以"禁止事项"和"例外条件"必须占一定篇幅。

第三个错误是资源文件用了绝对路径。一旦把 skill 分享给别人，或者换一台机器，路径就失效了。所有辅助文件都应该用相对路径引用，并且在 SKILL.md 里写明"本文件所在目录下的 xxx 文件"。

第四个错误是不做版本管理。SKILL.md 改了几版之后，自己都分不清哪个是有效的。我现在所有的 skills 都放在一个 Git 仓库里管理，每次修改都提交，并且用版本号标注字段记录更新内容。这个习惯帮我在迁移环境时省了大麻烦。

第五个错误是忽略跨平台兼容性。比如你写了一个需要调用jq的 skill，在 macOS 上没问题，但换到 Windows 环境就可能失效。发布或分发 skills 时，一定要在 README 里写清楚依赖工具和对应平台的安装方法。

4. 优秀 Skills 推荐：哪些技能包值得装

4.1 我整理的高口碑技能库

社区里已经有非常多的开源 skills 仓库，这里我按类别推荐一些我实测稳定、更新频繁的。

要说明的是，很多打包好的技能库并不是"装上立刻能用"，还需要根据你自己的项目特点做微调。比如前端开发技能包默认针对 React，你是 Vue 项目就一定得改一下里面的规则文件，否则很多建议会跑偏。

4.2 常用的 Skills 源网站和仓库

如果你想找更多现成的 skills，我推荐从这几个渠道入手。

第一个是 GitHub 全站搜索。直接搜"awesome skills"或"claude skills"等关键词，能找到大量汇总列表，很多列表的维护者本身就是重度的 AI 编程工具用户，筛选过的技能比盲搜好很多。我经常用的一个技巧是：按星标数排序，然后逐个查看最近几周的更新记录，只保留活跃维护的技能包。

第二个是 TypeSafe AI 的官方仓库。它的 skills 设计规范被很多平台认可，仓库里也有很多高质量的参考示例，适合用来学习标准写法。

第三个是各工具官方文档中的 skills 收录页。Claude Code、Codex 的官方文档都有专门的 skills 指南页，里面除了示例，还会说明平台特有的一些扩展字段，这是做跨平台适配的必备参考。

第四个是一些社区整理的"数学建模 skills"专题仓库。这类仓库通常集合了数据预处理、模型评估、图表生成等多个子技能，特别适合打比赛前一次性装好。我记得去年备赛时装了一套，三天里省下的时间足够多写两版论文摘要。

4.3 如何判断一个技能包是否靠谱

判断标准就三条。

第一条，看它的设计是否遵循"单一职责"。如果 SKILL.md 里既写代码审查又写数据库优化还写前端调试，这种大杂烩技能包最好避开，因为 AI 极容易相互干扰。

第二条，看它是否有具体的禁忌条款和边界声明。没有禁忌条款的技能包，只是把一些常识性要求堆在一起，对 AI 行为的约束力非常有限。

第三条，看它是否有配套的测试示例或典型案例。靠谱的作者会在 examples 目录里放几个"输入-输出"示例，你可以在自己的环境里复现，验证技能效果是否可预期。没有测试示例的技能包，效果很可能是"薛定谔的稳定"。

5. 常见问题与排查技巧实录

5.1 装了很多 Skills 之后 AI 变"笨"了？

这是一个非常普遍的现象，装了一堆技能包之后，AI 反而频繁跑偏、犹豫不决、甚至答非所问。我踩过一次大坑之后总结出原因：技能包互相覆盖，description 里的触发词重叠了。

解决办法是给每个技能包划分清晰的触发边界。具体做法分两步：第一步，运行一下你正在用的工具的 skills 诊断命令。Claude Code 和 Codex 都有列出当前加载技能的命令，通常还能看到每个技能的命中次数。第二步，对命中次数高但你不常用的技能，直接停用或移出目录；对经常误触发的技能，修改它的 description，加上更严格的排除条件。

举一个具体例子：我装了"中英文翻译"和"文案润色"两个技能包，结果每次写英文邮件时两个都会被触发，AI 一会儿翻译一会儿润色，输出乱七八糟。后来我把翻译技能的 description 明确为"当用户明确要求将文本从一种语言转换为另一种语言，且输入文本长度大于 50 词时使用"，把润色技能的描述加上"不适用于跨语言改写"，冲突立刻消失。

5.2 技能没生效时，怎么定位问题

我的排查顺序一向是"由外到内"。

先检查技能目录是否被工具扫描到。有些工具支持/skills这类斜杠命令查看技能列表，如果列表里没有你装的技能，说明目录结构不对。再检查 SKILL.md 的 YAML frontmatter 是否解析成功。YAML 是出了名的对缩进敏感，我有一次只是把 description 后面的冒号写成了全角冒号，整个技能就无法识别，花了半小时才找到问题。

接着检查描述语是否与你的任务匹配。你可以故意把问题描述得和 description 里的关键词高度一致，测试技能能否触发。如果仍不触发，就是 description 表达的问题；如果触发了但表现异常，问题出在正文指令。

最后检查辅助文件能否被正确读取。SKILL.md 里如果写了"参考 xxx.md"，确认这个文件确实存在于技能目录下，同时确认它没有依赖其他缺失资源。很多技能失效的原因不是主文件坏了，而是二级资源文件被移动或删除。

5.3 性能占用的顾虑要不要担心

有些人不敢装太多技能，怕每次对话都把所有技能内容加载进上下文，导致 token 消耗暴涨。

其实大多数主流工具在实现 skills 时都做了延迟加载，也就是先扫描所有技能的 description，再根据当前对话内容判断是否需要把某个技能正文完整加载进来。所以平时你装了 50 个技能，实际每次对话可能只加载 1~2 个正文，上下文开销远比想象中低。

但有一个例外：如果你的 description 写得太模糊，导致多个技能同时被触发，那就会同时加载多个正文，token 自然就上去了。这也是为什么我一直强调，description 的"排除性描述"比"包揽性描述"更重要。宁可让技能在某些边缘场景下不触发，也不要让它频繁误触发。

5.4 跨平台复用时需要注意的细节

如果你和团队同事用的工具不一样，或者你自己从 Claude Code 换到了 Codex，技能包跨平台复用时要注意三个细节。

第一个细节是 YAML 字段的兼容性。虽然大部分平台都认 name 和 description，但某些高级字段（比如 allowed-tools）在部分平台会被忽略，甚至可能因为未知字段触发报错。跨平台复用之前，先删掉平台特有的字段，只保留通用字段。

第二个细节是命令规范和系统差异。如果技能正文里写了很多 shell 命令，尽量使用跨平台的写法。比如用python -m pip而不是pip，用路径拼接说明而不是假定/usr/local/bin等固定目录。

第三个细节是触发语境的差异。同一个技能在 Claude Code 里表现良好，不代表在 Codex 里也一样。因为底层模型不同，对指令的服从程度和解析风格会有明显差异。我建议每个平台都保留一份微调记录，记录哪些描述在该平台下命中率更高，慢慢形成自己的一套适配笔记。

6. 关于 Skills 的后续扩展思路

聊了这么多实操细节，最后再分享一个我最近在尝试的方向，就是"技能包间的编排与联动"。

单个 skill 能解决的问题有限，但如果把多个 skill 串联起来，效果会非常惊人。比如我正在实验的一套"数据分析 + 图表优化 + 论文排版"组合：先让数据清洗技能处理原始数据，再让图表生成技能输出统一风格的图，最后让论文排版技能把图和表组织进标准结构中。每一个技能只负责一段环节，但它们通过主任务串成一条流水线，整个流程稳定性和执行效率比我之前的单一指令高了很多。

这件事的意义在于：skills 不只是一个个孤立的指令包，它本质上是一套"可以设计"的智能体工作流的最小单元。你把一个复杂的协作过程拆解成多个 skills，再通过主任务描述来编排它们的调用顺序，这其实就是一种轻量级的 AI Agent 架构搭建。不需要复杂的框架和配置，也不需要写代码，只要你会写 Markdown，就能完成整套编排。

还有一个小技巧值得分享：写 skill 时尽量留下"记录评审意见"的位置。AI 每次执行完任务后，让它总结出本次执行的不足之处，追加到 SKILL.md 的"常见问题"段落里。这样每次执行都会让技能包自动进化。我用这个方法跑了三个项目之后，技能包的质量已经完全不像是第一版的样子了。

最后说一个我自己的体悟：不要神化 skills，也不要轻视它。它本质上就是用可控的成本给 AI 立规矩。规矩立得越清晰，AI 的表现就越可预期。如果你现在还在重复地、费力地向 AI 描述每一个任务应该如何做，那我想告诉你，试着把这些指令沉淀成技能包，你会看到完全不一样的效率变化。