先交代一下背景。大概半年前，我还把 Claude Code 当成一个普通命令行 AI 来用，问一句答一句，它稍微偷个懒我就在旁边干瞪眼。后来一位做前端的朋友看了我终端里的配置，说了一句让我印象很深的话："模型能力没毛病，是你根本没给它装技能。" 他说的是 Skills——这个最近在 AI 编程圈里被反复讨论、甚至已经被一些团队当作"第二大脑"来维护的东西。我花了两周时间把 GitHub 上能翻到的 Skills 仓库基本都过了一遍，从手动安装、自己编写，到清理踩坑，今天把这些经验一次性整理出来。这篇内容适合所有正在用或者准备用 Claude Code、Codex、opencode 这类 AI 编程工具的人，不管你是纯前端、偏后端的全栈，还是拿 AI 做数学建模、做内容生产，看这一篇基本够用了。
1. Skills 到底是什么：从"会聊天"到"会干活"的那层壳
先说结论：Skills 本质上是给 AI 模型的一包"岗位说明书"。它把某个领域的工作流程、判断标准、输入输出规范、注意事项全部写进一个结构化的文件里，让模型在遇到对应任务时，能按这套流程去执行，而不是靠临场发挥。我第一次看到 SKILL.md 文件时心想，这不就是高级一点的 prompt 吗？后来发现完全不是一回事。
1.1 为什么 Skills 这个概念突然火起来
传统 prompt 是一次性的、对话内生效的。你今天写了一个"帮我做代码审查"的 prompt，明天新开一个会话，模型就把这件事忘光了。哪怕你把它存成模板，也得手动复制粘贴，而且一旦你的审查标准更新了，所有旧的会话记录、历史模板全部作废。Skills 解决的是这个"可复用 + 版本化 + 自动触发"的问题。
我把它们的关系这样类比：Prompt 是员工随口交代的一句话；MCP 是给员工接上的外部系统权限，比如能查数据库、能调 API；Agent 是整个员工的躯壳——有自主决策和行动的能力；而 Skills 是员工入职时拿到的那本《岗位手册》。手册里写了：你负责什么、遇到什么情况走什么流程、输出物长什么样、踩过哪些坑要避开。模型每次面对一个任务时，会先浏览一遍可用的 Skills 元信息，如果任务描述匹配上了某个 Skill 的 description，它就会把完整的 SKILL.md 内容加载进上下文，然后照着手册干活。
这个机制最初是 Anthropic 在 Claude Code 里引入的，后来 opencode、Codex 这些工具也陆续兼容了类似格式。社区热度从 2025 年下半年开始直线上升，到 2026 年初，GitHub 上已经冒出了几十个成体系的 Skills 聚合仓库。为什么这么火？因为大家发现了一个残酷的事实：同样的底层模型，装没装 Skills 的体验差距大到像两个产品。没装的模型经常"说大话、办小事"，装了合格 Skills 的模型则像一个真的在该领域沉淀过几年的老手。
1.2 Skills、Agents、MCP 三者之间的边界
很多人问我，Skills 和 MCP 是不是一回事？我的理解是：MCP 解决的是"模型能不能触达外部世界"的问题，它提供的是连接器，比如一个 GitHub MCP Server，让模型能真正去读你指定的仓库、发起 PR；Skills 解决的是"模型知道该怎么把事情做对"的问题，它提供的是方法论和规范。一个是"手脚"，一个是"大脑的流程记忆"。
举个例子。你让 AI 帮你修一个前端打包报错。如果只有 MCP，模型可以自己去读日志文件、搜代码，但它可能像无头苍蝇一样东翻西翻；如果装了"前端调试 Skills"，它在动手前会先按 SKILL.md 里的步骤：确认报错信息上下文、检查依赖版本、复现最小场景、定位缓存问题，然后才动手改。前者是给一个聪明但没有经验的人一堆工具，后者是给一个聪明且有标准作业流程的人一堆工具——效率差距是数量级的。
另外一个容易混淆的概念是 Agent 和 Skill。Agent 本身是一个可以自主规划、调用工具的完整程序，Skill 只是它可调用的一本手册。同一个 Agent 可以装几十本不同领域的手册，按任务类型触发。这也是为什么社区里会出现"superpower skills"这类整合包——把调试、测试、文档编写、架构设计等几十个 Skills 打包到一起，装完之后 Claude Code 就像一个全能型员工。
2. 动手写一个 Skills：目录结构、SKILL.md 写法与前端开发示例
理解了原理之后，最快的学习方式是自己动手写一个。Skills 的编写门槛实际上非常低，你不需要会什么复杂框架，只需要掌握一个文件格式：Markdown，加上一点 YAML 开头的元信息。我下面拿一个前端开发场景做完整示例，你可以照着改。
2.1 一个 Skills 的标准目录长什么样
绝大多数兼容 Skills 机制的工具，约定的目录规则是这样的：在技能目录下建立一个以技能名命名的文件夹，里面放一个 SKILL.md 作为主文件，还可以附带脚本、模板、参考文档等资源文件。技能名建议用短横线命名法，比如 frontend-debugging、latex-report，不要用空格和中文（虽然部分工具支持中文名，但跨工具兼容性差）。
frontend-debugging/ ├── SKILL.md ├── scripts/ │ └── reproduce_error.sh └── templates/ └── bug_report_template.mdSKILL.md 是核心，其余文件都是辅助。模型读到 SKILL.md 后，如果需要执行脚本或查看模板，会用相对路径去引用同目录下的资源。这意味着你完全可以把一个团队内部的代码规范、配置模板、甚至常用修复片段都放在这个目录里，版本管理也方便。
2.2 SKILL.md 的元信息与指令写法
SKILL.md 最前面是一段 YAML frontmatter，用两组 --- 包起来。里面至少要包含 name 和 description 两个字段。name 是技能的唯一标识；description 非常关键，因为模型是靠它来做"该不该加载这个技能"的判断，写得太笼统会该触发时不触发，写得太具体又会频繁误触发。我的经验是：描述里要写明触发场景、输入要求、输出物，最好带上几个明确的关键词。
--- name: frontend-debugging description: 用于排查前端构建与运行时报错。当用户提供 Vite/Webpack 构建错误、浏览器 Console 报错、依赖版本冲突、样式异常等问题时使用。可按需输出根因分析、最小复现方案和修复补丁。 ---正文部分就是给模型的指令，用 Markdown 写。我写 Skills 到现在总结出一个原则：正文里少讲空话，多给可执行的判断逻辑。比如"遇到构建错误时，先判断是依赖问题还是配置问题，再决定是否检查 lock 文件"，这比"仔细分析错误并修复"有用得多。还可以在正文里明确禁止事项，防止模型乱来，比如"未经用户确认，不得直接修改 package.json 中的依赖版本"。
2.3 做一个前端调试 Skills 的完整示例
下面是我实际在用的一个简化版前端调试 Skills 正文结构，你可以直接参考：
# 前端开发技能：构建与运行时错误排查 ## 触发条件 - 用户报告 Vite/Webpack/Rollup 构建失败 - 浏览器出现运行时异常（Console 报错、白屏、资源加载失败） - 依赖安装后版本冲突 ## 排查流程 1. 先完整读取报错信息，提取错误类型和关键文件路径，不急于给结论 2. 查看项目 package.json 与 lockfile，确认依赖声明与实际安装版本是否一致 3. 复现条件分析：区分是生产构建失败还是开发服务器环境问题 4. 若是编译错误，先定位到具体包和 loader，搜索该包已知 issue 5. 输出修复方案时给出最小改动 diff，并说明改动理由 ## 输出规范 - 根因分析不超过 200 字 - 修复方案必须附带验证步骤，例如执行构建命令或启动 dev server - 若涉及依赖升级，先评估 breaking changes ## 禁止事项 - 禁止未经确认直接修改 lockfile - 禁止删除报错相关代码而不解释原因 - 禁止在没有复现步骤的情况下给出修复结论这份说明书虽然只有几十行，但加载之后，模型的行为立刻变得"有章法"。你会发现它不再上来就改代码，而是先要日志、看依赖、问复现场景。这个变化正是 Skills 的价值所在。
顺便说一句，如果你不是搞前端的，而是做后端、做运维、做数学建模，写法完全一样，只是把排查对象换成你自己的领域。比如数学建模的 Skills，正文里就写透"数据清洗流程、特征工程顺序、模型对比方式、LaTeX 论文排版规范"，一样好用。华为杯这类建模比赛之所以很多人推荐装 Codex Skills，就是因为比赛拼的其实是"谁能把一套成熟的建模方法论固化给 AI 执行"。
3. 手动安装 GitHub 上的 Skills：Claude Code 与 Codex / opencode 两条路径
看再多 Skills，不如自己装一个试试。现在 GitHub 上大量的 Skills 仓库，有的已经打包好可以直接下载，有的需要从源码安装。我以最常用的两类工具为例，把整个流程拆开讲清楚。
3.1 安装前要弄清楚的三件事
第一，你的工具版本是否支持 Skills。Claude Code 较新版本基本都已经原生支持；Codex 的情况复杂一点，早期的版本只支持狭义的自定义命令，接近 Skills 机制的"完整 SKILL.md 支持"是后来才逐渐铺开的；opencode 是最早一批兼容 Skills 的社区工具之一。建议你先查一下自己用的版本，再决定走哪条安装路径。
第二，要把"用户级"和"项目级"分开。用户级 Skills 目录里的技能，对当前账号的所有项目都生效；项目级 Skills 目录只在当前项目下生效。我的习惯是：通用技能（代码审查、前端调试、文档编写）放用户级；垂直特定项目的技能放项目级，这样换项目不会互相污染。
第三，特别提醒一点：安装任何第三方 Skills 之前，一定要打开 SKILL.md 看一眼。因为 Skills 本质上是"指令注入"，里面写什么 AI 就会照着执行什么。如果某个仓库里的 SKILL.md 暗示你在不安全的网络环境下做某些操作，或者要求模型忽略自身的安全对齐规则，这种技能装了就是定时炸弹。我在后文还会细说。
3.2 Claude Code 手动安装流程
以最常见的 Claude Code 为例，手动安装 GitHub 上的 Skills 实际上就是三步：找到目标仓库、下载到正确目录、验证命名规范。
第一步，定位 Skills 的安装目录。用户级目录通常是~/.claude/skills/，项目级目录是项目根目录下的.claude/skills/。如果目录不存在，手动创建即可，权限用普通用户权限就行，不需要 sudo。
第二步，从 GitHub 获取技能内容。如果仓库本身就是一个 Skills，直接克隆或下载解压到上面的目录；如果仓库是一个聚合了多个技能的 monorepo，则把里面每个技能子目录复制到 skills 目录。这一步最稳妥的做法是下压缩包，避免把整个 git 历史都拉进来，拖慢以后启动时的扫描速度。
第三步，确认命名。进入 skills 目录后，你会看到一个又一个以技能名命名的子目录，每个子目录里必须有一个 SKILL.md。如果缺失，模型不会识别。验证方法很简单：在 Claude Code 里问一句"你现在能使用哪些技能"，如果它在回复里列出来你刚装的技能，说明安装成功。
从 GitHub 上找技能还有一个常见问题：很多仓库是国外托管平台托管的压缩包，下载时如果你恰好访问不稳定，容易下一半失败。我的土办法是：换一个网络节点重试，或者直接在浏览器里打开仓库页面手动下载 zip，再传到终端所在的环境。与其在终端里等超时，不如走一次浏览器下载，这招对国内用户尤其实用。
3.3 Codex / opencode 等其他工具的安装差异
Codex 的情况要单独说。目前 Codex CLI 的 Skills 目录约定和 Claude 类似，通常是在~/.codex/skills。但 Codex 对 SKILL.md 的解析器实现和 Claude Code 不完全一致，有些 Claude 上能正常用的语法特性（比如嵌套引用、复杂条件判断），在 Codex 里可能不生效，反过来也是。所以你在跨工具复用一份 Skills 时，不要假定"一次编写、处处运行"，而是要在目标工具里实测一遍。
opencode 则更激进一点，它对 Skills 的支持分成了两个层面：一个是兼容标准的 SKILL.md 加载机制，一个是它自己的一套"agent 配置"体系。如果你只是想把 GitHub 上现成的 Skills 装进 opencode 用，路径通常是~/.config/opencode/skills。装完之后可以在 TUI 界面里通过相关命令查看技能是否被识别。
另外，我之前提过 Typesafe 公司在 GitHub 上开源了他们内部的 AI Skills 仓库，那一套专门针对 Scala/TypeScript 后端开发场景，结构非常标准，适合当作"高质量参考实现"来读。如果你刚开始学写 Skills，我强烈建议你去翻一翻他们的写法——人家的 description 写得既精确又有层次，示例也给得相当扎实，照着学比你闭门造车快得多。
4. 去哪里找优质 Skills：源网站、聚合仓库与筛选标准
Skills 生态起来得快，一个直接后果是"有量无质"。GitHub 上随便搜 skills 关键词能出来几千个结果，但其中很大一部分是拿模板批量生成的劣质技能，正文全是正确废话。我踩了不少坑之后，总结出一套找技能和筛选技能的方法论。
4.1 值得收藏的 Skills 来源
第一优先级是官方渠道。Anthropic 自己维护过一个 Skills 官方示例库，里面包含了几个经典的参考实现，质量极高，适合当作标准来阅读；此外它们还发布过一个面向普通用户的 Skills 网页版入口，直接在网页上查看和复制技能，对非开发者非常友好，这也是"skills网页版进入"这个热搜词的来源。而 Typesafe 的 GitHub 仓库则是后端领域的优质范例；如果你关注"typesafe ai skills github"，直接去它们组织账号下翻找即可。
第二优先级是社区聚合仓库。GitHub 上以 awesome-claude-skills 为代表的一批汇总项目，会把 GitHub 上的高星技能分门别类列出来，包括技能名、适用工具、维护状态。这类仓库的优点是信息密度高，缺点是更新滞后，有些技能链接已经失效了还在列表里。我个人觉得 star 数只能当一个粗暴的参考，不能完全信，因为早期开源社区的 star 数和技能真实质量并不总是正相关。
第三优先级是垂直领域大佬的独立仓库。比如 AI 编程圈的知名开发者 obra，他的 superpower skills 项目就是把一整套工程效能技能打包发布的，里面包含 TDD 开发流、深度调试、文档驱动开发等十几个子技能，几乎每个都值得细读。再比如"codex nature skills"，就是针对 Codex 这个工具专门打磨的、偏代码自然化重构和可读性维护方向的技能集合，这套东西在维护老项目时非常好用。
4.2 怎么判断一个技能靠不靠谱
我摸索出一个四步筛选法，分享出来给大家参考：
- 第一步，看 description 的具体程度。一个合格的技能描述，应该写明触发条件、处理对象、输出规范。如果 description 只是"帮助开发者提高效率"这种废话，直接跳过。
- 第二步，看 SKILL.md 正文里有没有"判断逻辑"。靠谱技能会给模型明确的决策树和改进路径，比如"如果 A 情况出现则走 X 分支；如果 B 情况出现则走 Y 分支"。只有空泛原则、没有可执行规则的技能，装了也是白装。
- 第三步，检查引用资源。如果技能附带脚本、模板，就看一下这些东西是不是真实存在、路径对不对。很多劣质技能在正文里声称会调用脚本，实际脚本文件根本没传。
- 第四步，关注维护状态和版本兼容说明。看仓库最后一次提交时间、是否标注了兼容的 Claude Code 或 Codex 版本。老实说，这个生态变化很快，三个月不维护的技能很可能因为底层解析规则变动而失效，但是至少作者有没有在管这个事，从提交记录上一眼能看出来。
4.3 组合一套场景化技能包：以数学建模为例
比单点找技能更重要的是"组合技能"。因为真实工作任务很少只依赖单个技能，它往往是几个技能协作的结果。这里我拿"数学建模比赛"这个热门场景来拆解。华为杯、国赛美赛这类比赛的参赛者，现在很多人都在用 Codex 或 Claude Code 辅助做数据分析、建模和论文写作。我见过很合理的技能组合是这样的：
- 数据处理类 Skills：负责读取 CSV、清洗缺失值、异常值检测、类型转换。
- 特征工程与模型选择类 Skills：内置常见的模型适用场景判断，比如什么时候用线性回归、什么时候上树模型、什么时候考虑时间序列分解，并给出 sklearn/statsmodels 的代码框架。
- 可视化类 Skills：负责按图表类型生成 matplotlib/plotly 代码，并统一配色和字体规范，保证直接能放进论文。
- 论文排版类 Skills：负责把结果输出成 LaTeX 表格、插入公式、处理三线表格式。
这个组合里每一个技能单独拿出来都不复杂，但组合起来的效果是：你只需要把原始数据丢给模型，说一句"跑一个完整分析并出论文片段"，它就会按流程走完清洗、建模、结果解读、排版输出。原本大半天的工作能压缩到一两个小时，而且流程可控、结果可复现。如果你也在准备建模比赛，我建议你按这个思路去组装自己的技能包，而不是东装一个西装一个。
5. 只装不清理的代价：版本兼容、上下文膨胀与正确清理方案
最后一个部分我想重点说说清理。因为太多人只顾着装技能，装了一堆之后发现 AI 反而变"笨"了，然后得出"Skills 不过如此"的结论。这其实是冤枉了 Skills，问题通常出在你没有管理技能的习惯。
5.1 装了不生效？先查这三处
装完技能发现模型毫无反应，80% 的情况是以下三个原因之一。第一是目录位置放错了，尤其容易发生在用户级和项目级搞混的时候。第二是目录名称不规范。Claude Code 要求技能目录不能有奇奇怪怪的字符，我见过有人把目录命名为"my skills v2 (final)"，结果怎么都不触发，改成"my-skills-v2"立刻就好了。第三是 description 写得太窄或太宽，导致触发条件不匹配。
如果上面三处都没问题，那就要考虑是不是解析器版本差异。同一份 SKILL.md，在 Claude Code 里表现正常，换到 Codex 却失效，多半就是某个语法标记不被兼容。这时候没有捷径，只能逐行检查 SKILL.md 里的特殊语法，去掉目标工具不支持的部分。
5.2 上下文被挤爆的代价
这是最隐蔽的一个问题。很多人以为技能是"用的时候才加载"，但实际上工具在启动时会扫描所有技能的元信息（name 和 description），把它们加载到上下文里做匹配。当你装了上百个技能，哪怕每个 description 只占几十个 token，扫描阶段也要占用几千甚至上万 token。而且模型在匹配技能时会产生额外推理开销，如果描述之间还有语义重叠，它甚至会选错技能。
真实场景下我见过最夸张的例子：一个同事装了差不多 200 个技能，结果模型经常在对话开始就把好几个技能全部加载进去，上下文窗口被占掉一大块，原本能处理的长代码文件反而放不下了。这就像你桌子上堆了几十本《岗位手册》，新员工一进门每种手册都翻两页，真正干正事的时候已经累了。
5.3 定期清理的正确姿势
聊到清理，很多人第一个想到的就是直接把 skills 目录删掉。我的建议是别这么粗暴。应该把"清理"当成一个定期的管理动作，按下面的节奏来做：
- 每两个月做一次全量盘点：打开用户级和所有活跃项目的 skills 目录，逐个技能问自己一个问题："最近三周我用过这个技能吗？"没用过的迁到一个备份目录里，而不是直接删除。
- 用日志和会话记录作为判断依据。Claude Code 的会话日志里会记录实际加载了哪些技能，你可以统计一下真实命中率，那些从未命中的技能基本可以送进冷宫。
- 清理之后验证一次：清完先别急着干活，开一个新会话，问模型现在可用技能有哪些，确认没有把正在依赖的某个关键技能误删。
- 注意项目级技能的影响。你在一号项目里装的某个垂直技能，如果你把它同步到了二号项目，而二号项目根本不需要它，它也会每天被扫描、占资源。清理时要按项目维度区分，不能只扫用户级目录。
我在实际项目中把技能数量从 80 多个精简到了 20 个左右，体感非常明显：模型响应速度更快了，技能触发准确率也高了不少。那种"好像装了很多但一个都用不对"的焦虑感，一下子就没了。
说到最后，我自己特别深的一个体会是：Skills 这个机制真正教给我的，不是怎么给 AI 写指令，而是怎么把一件事的"做事方法"从直觉变成结构。你为了给 AI 写一本岗位手册，被迫把脑子里的经验整理成清晰流程、判断标准和禁区条例，这套东西最后 AI 在用，你自己也在用。哪怕有一天你换了一个完全不兼容 Skills 格式的工具，这套思维方式也不会浪费。如果你刚开始折腾 Skills，我的建议是：先装三五个高质量的上手，感受一下"有技能"和"没技能"的差别，然后试着把你最熟悉的那项工作写成第一个 SKILL.md，你会回来感谢现在动手的自己的。
