最近一直在折腾 AI 编程工具里的 skills 机制从最初好奇“这跟插件有什么区别”到现在自己写了一套前端开发技能库、还在给华为杯建模比赛的朋友定制了数学建模技能包踩了不少坑也摸到了一些规律。如果你也在用 Claude Code、Codex 或者 OpenCode 这类 CLI 编程助手打开 GitHub 想装个 skills 却发现不知道往哪放、不知道格式是什么、装完还不生效这篇就是写给你看的。我会把 skills 的原理、手动安装方法、编写规范、推荐技能库来源、常见问题排查一次讲透附上我实测过的配置和踩坑记录。1. 先搞懂 skills 到底是什么机制1.1 它不是插件也不是 MCP很多人第一次看到 skills 这个功能第一反应是“这不就是插件吗”。我在最初也这么想过但实际用了两个星期之后可以负责任地说skills 和插件、MCPModel Context Protocol是完全不同的东西理解错了会直接导致你用不好它。插件是程序级别的扩展它运行在自己的运行时里有自己的生命周期和 API。MCP 则是给模型提供的外部工具调用协议模型可以通过 MCP 服务器去查询数据库、操作文件、调用外部服务。而 skills 是为模型本身准备的“能力说明书”——一组特定的指令、示例、工作流程和约束规则以 Markdown 文件的形式存在用来引导模型在特定场景下按最佳实践干活。打个比方MCP 是给模型配了一把螺丝刀skills 则是告诉模型“你拿到这把螺丝刀之后该怎么拆这块电路板先拆哪里后拆哪里拧到什么程度要停”。工具解决的是“能做什么”的问题skills 解决的是“怎么做好”的问题。1.2 为什么突然到处都是 superpower skills、nature skills最近热词里频繁出现 superpower skills、nature skills、cola skills、typesafe ai skills这些基本都是社区里做出来的 skills 合集。它们的出现有明确背景Claude Code、Codex 这类工具的能力已经够强了但在具体场景下模型的行为不够稳定——同样是写前端代码模型可能这次用 Tailwind、下次用 CSS Modules同样是做数学建模模型可能这次想到用层次分析法、下次又用灰色预测完全没有章法。skills 出现的意义就是把这种随机性压住。你把它当成一套“动作库”或者“操作 SOP”模型读完 skills 之后会按照你定义的方案、风格、步骤去输出。社区里比较火的 superpower skills 一开始就是整理了大量通用技能比如代码审查、需求分析、项目规划后来大家发现这种做法极其有效于是各种垂直领域的技能包就雨后春笋般冒出来了。1.3 SKILL.md 与渐进式披露机制要理解 skills 的工作方式必须知道它遵循一个核心规范叫SKILL.md。每个技能本质上就是一个文件夹里面至少有一个SKILL.md文件这个文件的头部有一段 YAML frontmatter用来声明技能的名称、描述、适用场景等元数据。模型在运行时会先扫描这个文件根据描述判断当前任务是否匹配这个技能匹配到才加载对应的指令内容。这里有个很关键的设计思路叫渐进式披露Progressive Disclosure。一个技能如果一上来把所有细节全部塞给模型那上下文窗口会被大量消耗。所以 SKILL.md 里面通常只写概要、触发条件和最核心的步骤具体的完整指令、模板、代码规范放在同目录下的其他文件中比如references/子目录或者scripts/子目录由模型按需读取。我试着把 SKILL.md 理解成一份“目录”模型先看目录觉得需要看某一章就翻到那一页。这个机制决定了 skills 的编写方式不要把所有内容平铺一定要分层、分文件。2. 手动安装 skills从 GitHub 到本地的完整操作2.1 先确认你的工具版本和 skills 目录结构很多人在“手动装 skills”这件事上翻车就是因为不知道技能文件到底该放在哪个目录。不同工具的默认路径略有不同但我用过的 Claude Code、Codex、OpenCode 基本都是基于.claude/skills或~/.codex/skills这样的目录约定。以 Claude Code 为例它的 skills 目录通常在项目根目录的.claude/skills/下或者全局用户目录的~/.claude/skills/下。前者是项目级技能只有当前项目能用后者是全局技能所有项目都能用。Codex 的情况类似我习惯在~/.codex/skills/下存放全局技能。手动安装其实就两个动作下载技能文件夹、放进正确的技能目录。比如从 GitHub 上找到一个名为frontend-architect的技能仓库它的目录结构应该是这样的frontend-architect/ ├── SKILL.md ├── references/ │ ├── react-optimization.md │ └── tailwind-guidelines.md ├── scripts/ │ └── check-performance.py └── assets/ └── templates/把它整个文件夹复制到目标 skills 目录后重启会话有的工具会自动热加载但我不建议依赖热加载重启一下最稳然后在对话里描述你遇到的前端架构任务模型应当能自动加载对应的 SKILL.md。2.2 命令行一键安装与手动安装的取舍现在很多技能库提供了安装脚本比如常见的# 使用 npx 安装远程技能库以某个知名库为例 npx skills add 用户名/仓库名称 # 或者使用工具自带的安装命令 claude skills install 用户名/仓库名称命令行安装的好处是省事会自动处理目录、依赖和更新。但我个人更推荐在两种情况下手动安装一是你只需要技能库里某一个技能、不需要全部二是你想对技能内容做本地定制。比如我从 superpower skills 里只挑了三四个技能手动复制而不是全部拉下来这样上下文开销更小模型行为更可控。手动安装的路径其实就是从 GitHub clone 仓库然后cp -r或者rsync进目标目录。这里有一个关键排查点装完之后先确认 SKILL.md 是否在技能文件夹的第一层目录。很多人手动拉下来后发现嵌了一层子目录比如skills-main/superpower-skills/xxx-skill/SKILL.md如果不调整层级工具扫描不到技能就永远不生效。提示装完技能如果发现模型完全不理会先别怀疑技能写得不好检查路径层级和 SKILL.md 是否位于最外层这是我实测下来概率最高的翻车原因。2.3 环境变量与白名单配置部分工具要求技能目录在白名单里否则不会加载。Claude Code 较新版本支持通过--settings或配置文件指定技能目录。我用的方式是显式设置一个环境变量来覆盖默认目录export CLAUDE_SKILLS_DIR$HOME/.claude/skills如果你用的是 Codex可以看它的文档里面有没有CODEX_SKILLS_DIR之类的环境变量。这类配置看似琐碎但一旦漏了装再多技能也是白搭。几何级数的挫败感就在这种小细节上排查时务必耐心检查一下环境变量。3. 怎么写一个自己的 SKILL.md3.1 核心元数据name、description、when_to_use要弄清楚怎么写 skills建议先拆开一个成熟技能的 SKILL.md 看看。核心的几个字段我来逐一解释这些字段直接决定模型会不会在对应的场景使用你的技能。YAML frontmatter 里最不能省的是name、description、when_to_use三个字段。其中description和when_to_use就是模型检索时的匹配依据。模型不会在每次对话中都把所有技能完整读一遍它通常是扫描元数据判断当前任务“像不像”某个技能的使用场景。如果你的描述写的太窄匹配不到太泛则容易误触发。举个例子我给数学建模写的一个技能when_to_use写的是当用户提出数学建模任务、竞赛题目分析、模型选择、论文排版等问题时使用。而description则写成“数学建模全流程辅助技能涵盖问题分析、模型选型、数据预处理、论文写作适用于数学建模竞赛和科研建模场景”。这样模型在对话中看到“华为杯”、“国赛”、“建模思路”这类词会比较准确地匹配到它。3.2 SKILL.md 的正文章节怎么排正文部分是技能的核心指令。我的经验是把 SKILL.md 控制在一个合理的长度范围内过长的技能会让模型迷失重点。一般来说 200 到 400 行是一个比较健康的区间把细节拆到外部文件里而不是全堆在主文件里。我常用的一种结构如下# 技能名## 核心原则写清楚这个技能遵守的最重要三条规则## 工作流程给模型一个明确的步骤序列比如建模题先做问题重述、再做假设分析、接着模型建立、求解、检验## 输出规范规定模型输出的格式、头注、章节编号## 参考指向同目录下references/里的详细文档比如我做的一个“前端页面开发”技能核心原则之一就是“所有组件先写 TypeScript 类型定义再写实现”输出规范里要求样式方案必须使用 Tailwind 类名而不是手写 CSS这样模型就不会每次风格飘忽。这些规则写得越明确效果越好。3.3 记忆机制与 PROGRESS.md一旦技能开始运行你可能希望模型在多次会话里保持状态。如果它是做代码重构中间涉及很多文件修改模型在上下文里并不可靠。这里就要用到技能记忆机制在技能目录下维护一个PROGRESS.md文件随着执行过程不断更新它。我的做法是这样的当技能被触发并且任务涉及多步操作时要求模型先读取PROGRESS.md了解进度每完成一个重要阶段就追加一段记录。这样做的好处是即使上下文被压缩或者会话中断重新启动后模型还能接上进度不需要用户重新描述一遍。注意PROGRESS.md 是技能自己的工作日志不是给人看的文档写的时候不要啰嗦记录结论、已改文件、待办事项就足够了。3.4 中文编写和英文编写怎么选很多社区里的技能都是英文写的直接拿来用问题不大但如果是自己编写我强烈建议用中文写。理由很简单这些技能的指令最终是在引导模型干活中文指令对中文任务的适配性更好触发准确率也更高。尤其你技能描述的适用场景是“数学建模”“前端开发”这种中文本土任务时中文元数据匹配到的概率明显高。当然有一种情况例外如果你的技能会被开源分发给全球用户用那必须中英双语或者全英文。我自己的一般做法是 frontmatter 里中英文各写一遍描述正文则以中文为主因为我的主要使用场景是中文对话。4. 推荐几个实测好用的 skills 资源与场景化配置4.1 superpower skills 与 typesafe ai skills 怎么选热词里反复出现的 superpower skills 是目前社区里知名度最高的技能合集内容覆盖代码审查、架构设计、调试、数据库建模等通用任务。它最大的优点就是通用性强、质量控制好不适合做超垂直的场景但作为日常开发的底子很合适。typesafe ai skills 则是从 TypeScript 生态切入强调类型安全适合做前后端 TS 项目的人。我自己的配置方案是全局只装 superpower skills 里的两三个核心技能比如代码审查和项目规划项目级再装 typesafe ai skills 里跟当前技术栈匹配的技能。这样既不会污染全局上下文又能保证每个项目用到的是最对口的规范。4.2 数学建模与华为杯定制技能包的思路数学建模是最近被问得最多的一个场景尤其是华为杯、国赛这类比赛。很多参赛者发现自己用 Claude Code 或 Codex 辅助建模时模型输出的结构不稳定这会直接影响论文的完整度。我的做法是定制一个数学建模技能核心流程固定如下问题重述与文献分析数据探索与预处理候选模型库匹配回归、分类、优化、预测等模型求解与灵敏度分析论文结构组织与排版每个阶段都在references/下有对应模板。比如模型匹配到建模场景后它会先读取model-selection.md里面用表格列了不同问题的推荐算法和适用条件模型会在这个框架内做选择而不是自己拍脑袋。经验竞赛场景的 skills 不要写得过于死板。我一开始把每个算法都写死了结果遇到灵活性高的题目反而限制了思路。改成“推荐 备选 适用边界”的结构之后效果明显好很多。4.3 AI 漫剧与其他内容创作场景的 skills 组合AI 漫剧的热度起来之后用 skills 辅助做剧本分镜、角色设定、对话生成的思路也开始流行。这种技能跟编程技能的区别在于它更强调叙事结构和风格一致性。比如你做一个“AI 漫剧编剧”技能SKILL.md 里要规定人物设定记录在哪里、分镜脚本的格式怎么写、对白风格怎么保持统一。我在这个场景下的配置是一个全局的“编剧工作流”技能包含故事梗概模板、分镜表格模板再给具体项目建一个项目级技能里面用 PROGRESS.md 记录已生成的剧情进度避免模型写着写着把主角性格写偏了。发布平台对内容有审核要求的话还需要在技能输出规范里写清楚“生成内容需符合公序良俗避免血腥暴力和不良暗示”实测下来比每次对话手动叮嘱要稳定得多。5. skills 开发实操经验与避坑记录5.1 模型基座差异对技能生效的影响很多人在 A 工具上写好的技能拿到 B 工具上完全不按预期执行。最典型的就是为 Claude 设计的技能丢给 Codex 用效果大打折扣。我试过把同一个前端开发技能在 Claude Code 和 Codex 里各跑一遍差异非常明显。原因在于底层模型的指令遵循能力不同对 Markdown 结构的解析优先级也不同。Claude 对“按步骤执行”的理解通常比较好即便是长篇技能也能基本遵循Codex 则更吃“明确的重点指令”如果技能太长它可能会抓不住关键约束。所以我给 Codex 用的技能往往会在 SKILL.md 最前面加一段“核心规则”加粗摘要确保模型无论如何都能先读到最重要的几条。5.2 上下文过载与技能文件精简这也是新手比较容易踩的坑。一开始我总想在技能里多放信息把能想到的规范全部写进去结果技能一触发模型读入一堆原本在当前场景用不到的内容上下文窗口被挤占反而导致核心任务的推理质量下降。后来我做了精简确保 SKILL.md 里的每一条指令都有明确的应用场景如果没有删掉。代码规范、组件库文档这类内容放在references/里让模型按需读取。实测下来一个任务的整体响应速度变快了模型也更守规矩了。写 skills 不是做百科全书而是做“刚好够用”的引导手册。提示写完技能之后可以通过减少技能目录大小来控制 token 消耗。比如把大图片、大模板从 assets 里移走只在引用时按需读取。一个技能文件夹尽量控制在几百 KB 以内其中命令脚本如果体积大用临时拉取的方式而不是内嵌。5.3 多次调优迭代的方法技能不是写一次就能用的。我的流程是写一版 → 找一个代表性任务跑一遍 → 看模型哪里不符合预期 → 改 SKILL.md → 再跑。这个循环通常要重复三四轮才能稳定下来。调优的时候重点关注两个点一是模型有没有正确触发技能二是触发之后有没有严格遵循输出格式。如果触发了但格式混乱那就在 SKILL.md 里把输出格式描述得更具体甚至给出一个示例。示例极其重要模型对示例的理解比对规则的理解要准确得多。我无论写什么技能都会在references/或 SKILL.md 末尾附一个完整的输出示例这一步的性价比是最高的。6. 常见问题排查与技能清理6.1 装完不生效的排查清单很多人装完技能发现模型完全没反应我这里整理一份排查清单按顺序检查可以解决绝大多数问题检查项操作建议常见结果技能目录层级确认 SKILL.md 位于技能文件夹根目录层级套深最容易失效路径正确性确认路径为工具约定的技能目录路径错了怎么加载触发描述检查 SKILL.md 中的描述与任务关键词的匹配度描述太泛或太窄都不行会话重启修改后重启会话或执行扫描命令热加载失效是常态环境变量确认技能目录环境变量无冲突变量覆盖导致加载别的目录权限问题检查技能文件夹是否有可读权限Linux 下权限设置错误很隐晦6.2 版本更新后技能失效的处理工具升级之后技能突然不生效这种情况我也遇到过。最常见的原因是新版本改动了 SKILL.md 的 frontmatter 字段要求比如原来when_to_use不是必填新版本要求在特定位置或要求新增标签字段。这时候去对应的更新日志里搜一下skills关键词看有没有 breaking change。处理经验是升级工具前先把自定义技能目录整体备份一份。万一失效对比升级前后的差异就很清楚。另外有些工具更新后会修改默认的技能目录名称比如从.claude/skills改成.claude/agents之类的不是技能的错是路径迁移了找到新路径把文件夹挪过去就行。6.3 技能文件越积越多聊聊清理方法论技能装多了之后模型的“选择困难症”会越来越严重。我去翻了社区里 tibo 关于清理 skills 的方法结合自己的实践总结了这么一套清理流程查看技能目录里每个文件夹的最后修改时间和使用频率把超过一个月没用过的技能标记为“待移出”移到备份目录不直接删除观察一周确认没有影响如果项目里没有因为移出技能而出现明显质量下降再正式删除这里有个反直觉的点某些写着“感觉会有用”的技能恰恰是最应该清理的。它在平时不会被触发但元数据扫描时依然会消耗时间偶尔还可能被误触发反而干扰模型判断。清理不是删除而是更精准地保留真正适合当前工作流的技能。另外建议技能命名前缀带上使用边界比如web-frontend-react、math-modeling-competition、storyboard-ai-comic这样在目录列表里一目了然也不会在语义上跟其他技能混淆。命名规范这种事情等到你装了二十个技能之后再回头整理会非常痛苦不如一开始就定好规则。7. 对 skills 后续扩展的一些想法经过这一轮高频使用和研究我个人对 skills 机制的看法是它会越来越像“编程助手的第二大脑”不只是给模型加规则而是把方法论沉淀成可复用资产。现在社区里出现各种合集其实背后就是在做知识资产化。未来如果出现更标准的技能分发中心、更完善的生命周期管理工具这个体系会更好用。最后再分享一个小技巧给你的技能统一加一个version字段每迭代一次就更新版本号。调优的时候这个字段帮了我大忙能明确对比出哪一版技能表现更好而不是凭感觉说“好像改版之后变差了”。写技能和写代码一样也需要可控的迭代记录。无论你是想给 Claude Code 装几个现成技能提升效率还是准备给 Codex 定制一套符合团队规范的技能库我都建议从一个小而具体的技能开始跑通全流程再逐步扩大。技能不在多而在精目录不在大而在准。希望这篇文章能让你少走一些我走过的弯路早点把 skills 真正变成你自己的“超能力”。