★ FEATURED ARTICLE 先交代一下背景。大概半年前我还把 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 是给员工接上的外部系统权限比如能查数据库、能调 APIAgent 是整个员工的躯壳——有自主决策和行动的能力而 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让模型能真正去读你指定的仓库、发起 PRSkills 解决的是模型知道该怎么把事情做对的问题它提供的是方法论和规范。一个是手脚一个是大脑的流程记忆。举个例子。你让 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 上的 SkillsClaude 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你会回来感谢现在动手的自己的。
阅读完成 · 觉得有帮助？
