最近我几乎每天都被同一个问题轰炸skills 到底是个什么东西为什么大家都在提从 Claude Code 到 Codex从 GitHub 上手动装 skill 到自己写一套可复用的 AI skills再到数学建模比赛里该带哪几个——这名词听起来简单实际里面的细节远比想象中多。我算是比较早把 skills 用到生产环境的用户折腾了几个月装了卸、卸了写踩坑踩到怀疑人生。这篇就把我的完整经验整理出来skills 是什么、怎么装、怎么写、哪些值得收藏、以及你必须避开的坑。看完不说你能成为专家但绝对可以少走我走过的弯路。1. Skills 到底是什么一本随取随用的操作手册1.1 技能包不是“高级提示词”这么简单我给 skills 做过一个很形象的类比你给 agent 的提示词是一句口头吩咐而 skill 是一本放在手边的操作手册。口头吩咐说完就没了agent 记不住那么多细节你换个话题它就把你忘了操作手册则不同它会一直在那儿需要的时候翻一眼就能按套路执行。具体到文件层面一个 skill 就是一个目录目录里通常有一个 SKILL.md 作为入口文档还可能自带 scripts 辅助脚本和 references 参考资料。比如我常用的一个代码审查 skill结构长这样frontend-code-review/ ├── SKILL.md ├── scripts/ │ ├── check-deps.py │ └── find-todo.py └── references/ └── team-style-guide.md当 agent 判断当前任务和这个 skill 有关就会加载 SKILL.md 里描述的方法论、默认动作和输出格式再决定要不要调用 scripts 或 references。这个取舍很关键不是所有上下文都要一股脑塞给 agent而是按需加载。所以才说 skill 不是提示词的替代品它是提示词的结构化和工程化。1.2 description 决定 skill 会不会被“翻牌”SKILL.md 的开头是一段 YAML frontmatter里面最核心的两个字段是 name 和 description。name 是技能名description 决定这个 skill 在什么场景下被交给 agent。Claude Code 这类工具在判断要不要加载某个 skill 时靠的就是把用户当前任务和所有 skill 的 description 做一次语义匹配然后挑最合适的。这里就藏着一个大多数人没意识到的问题description 写得越具体触发越准确。举个例子如果你写“用于代码审查”那么所有涉及代码的任务都可能过来翻它的牌子触发率奇高但效果反而差。我会写成“当用户要求对前端 PR 或分支持行代码审查需要检查 TypeScript 类型、React 组件写法、CSS 规范、可访问性等问题时使用”。后者过滤掉了大量无关请求让 skill 只在真正该出现的时候出现。我可以很直白地讲同一个 skill触发效果差三倍往往不是正文写得不好而是 description 没打磨到位。1.3 不只 Claude Code很多工具都在用同一套范式热词里反复出现的 superpower skills、opencode skills、cola skills、typesafe ai skills本质上都是围绕“目录 SKILL.md 辅助脚本”这个范式做的社区扩展。Claude Code 是最早把 skills 作为一等公民的工具但 OpenAI Codex 和开源终端 agent opencode 也在快速跟进。各家在触发细节上有差异比如有的支持手动skill-name指定有的完全靠 description 自动匹配但底层设计语言高度相似。这意味着一个很实际的好处你学会写一个平台的 skill换工具时迁移成本并不高。真正要改的往往只是 SKILL.md 里的个别字段规则核心的正文方法论是可以复用的。所以我不太建议因为某个工具还没支持 skills 就一直观望这套机制大概率会成为未来 AI 编程助手的标配能力。2. 手动安装 GitHub 上的 Skills再也不用等别人打包2.1 安装前先搞清楚要放到哪个目录以 Claude Code 为例skills 的安装位置分两层个人级目录在~/.claude/skills/下面对所有项目生效项目级目录在当前项目的.claude/skills/下面只有当前项目生效。手动安装的核心操作就是把 GitHub 仓库里的某个 skill 目录搬到这两个位置之一。那为什么非要强调手动装因为虽然现在部分工具提供了类似claude skills add的自动安装命令但它通常只针对官方源或特定格式的仓库。GitHub 上大量社区 skill 是散装仓库有的是集合包有的是个人项目自动命令不一定识别得了。手动装虽然听起来原始但你能清楚地看到每个文件落在哪里后续排查问题也更方便。我自己装社区 skill 时几乎不依赖自动命令宁可自己复制目录至少我清楚装了什么、装到哪里。2.2 手动安装的完整操作步骤这里给出一套我实际验证过的流程在 GitHub 上找到目标仓库先看 README搞清楚它是整个仓库就是一个 skill还是把一堆 skills 放在某个子目录里。把仓库克隆到临时目录git clone https://github.com/example/awesome-skills.git /tmp/awesome-skills查看仓库结构找到 SKILL.md 所在层。以集合包为例常见结构是skills/frontend-dev/SKILL.md。把对应目录复制到安装位置。个人级就复制到~/.claude/skills/cp -r /tmp/awesome-skills/skills/frontend-dev ~/.claude/skills/重启当前正在运行的 Claude Code 会话执行/skills看看列表里是否出现刚才复制的技能名。如果你只想装一个 skill 而不是整个仓库也可以只进到对应目录再下载文件。我平时最常用的操作其实是mkdir -p ~/.claude/skills/frontend-dev cp /tmp/awesome-skills/skills/frontend-dev/SKILL.md ~/.claude/skills/frontend-dev/好处是不会把一堆你根本用不上的 skill 同时塞进全局目录触发时更干净。2.3 安装完怎么确认它真的生效了很多人以为重启就算装好了其实那只是第一步。真正靠谱的验证方法是给 agent 一个刻意针对该 skill 的任务看它是否主动调用了 SKILL.md 里的流程。比如你刚装了一个数学建模相关的 skill就丢一句“帮我按这个建模 skill 的流程分析下面这个问题”然后看回复里是否出现你写在正文里的步骤结构。如果没触发先检查两件事第一SKILL.md frontmatter 里的 name 是否符合工具的命名规范第二description 是否覆盖了你测试这句话的语义。八成问题都出在 description因为 agent 根本不知道这个 skill 是干嘛的自然不会加载。此时把 description 里加上“当用户需要……时使用”这类限定描述重新测试通常就过了。3. 手把手写一个能用的 Skills以「前端代码审查」为例3.1 SKILL.md 的 YAML frontmatter 怎么写一个能被正确加载的 SKILL.md开头必须是合法的 YAML 元信息。以代码审查场景为例我会这样写--- name: frontend-code-review description: 当用户要求对前端 PR 或分支持行代码审查需要检查 TypeScript 类型、React 组件写法、CSS 规范、可访问性等问题时使用。 ---name 一般用短横线命名目录名、文件名、name 字段尽量保持一致。description 则是前面强调过的重点写清“什么时候用 负责做什么”而不是笼统一句“帮助审查代码”。有些工具支持 license、allowed-tools 这类扩展字段但最基本的永远是这两项。你可以在工具升级后慢慢加字段一开始别贪多。3.2 正文不是给人看的文档是给 agent 看的标准作业程序写正文之前先调整心态SKILL.md 的目标读者是 agent不是同事。所以你该做的是把操作过程拆成 agent 能照着执行的步骤每一步都给验收条件必要的时候给反例。我写前端代码审查 skill 时正文大体分成三段读改动让 agent 先运行git diff main...HEAD拿到改动文件列表和 diff 内容。分类检查按照类型正确性、样式规范、组件 API 使用、可访问性四个维度逐项过一遍。输出结论把发现的问题分成严重、建议、风格三个级别每条带上文件名和行号。开头我会写明“不要直接给用户泛泛的代码风格建议必须基于实际 diff 内容”。这句话看着普通实际能挡住 agent 最典型的跑题行为。写正文时另一个核心原则是能列步骤就列步骤能给命令就给命令能限定输出格式就限定输出格式。你写得越具体agent 的发挥空间越小结果就越稳定。3.3 脚本和参考资料怎么组织当 skill 需要处理复杂逻辑时千万不要把所有内容硬塞进一个 SKILL.md。我见过一个反面案例有人把几千行规范原文直接粘进 SKILL.md结果每次触发这个 skill上下文窗口就被吃掉一大块。正确做法是让 SKILL.md 保持短小把重逻辑放到 scripts/ 目录正文里告诉 agent “先运行python scripts/check-deps.py根据输出继续分析”。把完整规范放到 references/ 目录让 agent 按需读取。这个设计能带来两个直接好处一是 SKILL.md 加载速度快agent 不需要每次都读几百 KB 的规范二是脚本和资料可以独立更新skill 的维护粒度更细。我自己开发的深层技能比如能跑数据预处理的建模 skill正文通常只有几十行脚本可能有几百行但运行效果反而比全塞文档里的 skill 要好。3.4 写完别急着发布先测一个迭代周期写完 skill 后我的做法是先放到项目级.claude/skills/下面在真实任务里连续用一星期。每跑一次就观察 agent 是否按流程走。哪一步不稳定就说明正文里的指令有歧义哪类无关任务频繁触发它就收紧 description。技能开发本质上是一个写 prompt 的工程化过程只不过你的 prompt 有了文件结构、版本管理和分享渠道。我早期一共写了六个 skills第一个版本基本都改了四五轮才稳定。这项工作没有捷径但回报也直接改完的 skill 会在之后每次触发时都给你省下大量重复沟通时间。4. 值得收藏的 Skills 类型与来源4.1 从热搜词里看大家在集火什么方向最近的热搜词很能说明问题前端开发 skills、数学建模 skills、AI 漫剧常用 skills、superpower skills、cola skills几乎每个方向都有对应生态。这些需求背后其实是同一种逻辑凡是重复性的、流程明确的多步任务都值得被包装成技能。前端开发 skill 沉淀的是团队规范和组件库习惯数学建模 skill 沉淀的是数据预处理、模型选型和论文排版AI 漫剧 skill 沉淀的是分镜脚本生成、角色一致性保持和配音提示词组合。这已经不是纯写代码工具的范畴了。我认识的一些非程序员也在把 AI 绘画和视频生成的固定套路写成 skills自己用完了还分享到社区。从这个角度看skills 的适用范围比我最初以为的要大得多它更像是一种通用流程封装格式代码只是第一批被封装的对象。4.2 高质量 skills 源从哪里找我的找技能源方法其实很土第一步在 GitHub 搜SKILL.md这个文件名第二步用awesome-claude-skills、claude skills collection这类 topic 词继续筛第三步看几个你信任的开发者维护的仓库顺着他们的收藏再往外扩散。热词里提到的 superpower skills、typesafe ai skills、cola skills、opencode skills你用关键词直接搜都能在 GitHub 看到对应仓库。判断一个 skill 值不值得装我的标准有三个最近有没有实质更新。超过一年没动的仓库大概率内部命令已经过时。SKILL.md 里的 description 是否具体正文是否有明确步骤和验收标准。是否带了可运行的脚本或清晰的输出格式而不是全篇都是口号式建议。如果仓库 README 花团锦簇但实际 SKILL.md 只有三行泛泛之词直接跳过不值得花时间。4.3 数学建模、竞赛场景的技能包怎么挑建模比赛的 skill 最近特别火热词里连“华为杯建模比赛好用的 codex skills”都出现了。这种场景下的技能包往往有几个共性数据预处理、模型方法建议、结果可视化、论文排版模板。挑的时候不能只看下载量关键要看 skill 的 SKILL.md 里有没有针对比赛评阅规则的隐性假设。比如有的默认用某个学术写作模板和你的使用习惯冲突那再强也用不顺手。比较可靠的方式是拿往届赛题样例去跑一遍。你给 agent 一个真实任务看它输出的分析流程和论文结构是否顺眼比看任何 README 都管用。竞赛类技能包通常会有很强的“个人风格”因为建模比赛本来就没有统一解法别人的套路不一定适配你的思路。因此我的建议是数学建模 skills 可以装三五个做参考但真正比赛时最好用自己调的版本别人包里的假设太多关键时刻会误导你的决策。5. 必须避开的坑清理、冲突与迁移5.1 skills 越装越多之后怎么清理我一开始见 skill 就装全局目录里一度堆了四十多个。结果是每次启动都要扫描一堆元数据偶尔还出现触发错乱。社区里 tibo 的清理方法给过我不少启发核心思路是这样的先按目录大小和最近修改时间排序找出那些装完就没被动过的再在会话里用/skills看最近三十天实际触发过哪些最后只留真正需要的其余全部删除。比如统计全局目录占空间可以跑du -sh ~/.claude/skills/* | sort -h然后逐个确认删除。这里有个我踩过的坑如果你装的 skill 带脚本删除目录前一定要检查这些脚本有没有被其他 skill 的正文引用。我就遇到过两个 skill 共用同一个scripts/preprocess.py的情况删了其中一个之后另一个立刻开始报错。共享脚本这事社区里没人提醒但只要你装的技能多了一定会撞上。5.2 多个 skill 互相抢触发怎么办最常见的问题是两个 skill 的 description 覆盖了同一类任务。比如“代码审查”和“前端代码审查”同时存在按哪个触发都说得通agent 就可能在两者间随机跳甚至两个一起加载。这种情况的结果轻则输出风格不一致重则两个 skill 里的规则互相打架推导出互相矛盾的建议。我的处理方式比较直白要么把小能力合并进大 skill要么把低优先级 skill 的 description 末尾明确写上“除非用户特别要求否则不要主动使用”。这不是什么官方推荐做法但实测下来触发稳定很多。毕竟对 agent 来说模糊的边界等于让它做选择题而明确的正负例清单可以避免选错。5.3 Claude Code、Codex、opencode 的差异与迁移细节虽然它们都在支持类似范式的 skills但细节差异仍然需要留意不然迁移时容易踩坑工具安装目录触发方式主要风险Claude Code~/.claude/skills/主要靠 description 语义匹配也支持手动指定全局目录装太杂触发准确率下降Codex项目级目录或对话内配置对话内配置模式相对固定字段规则和 Claude Code 不完全一致opencode配置目录下的 skills 文件夹更依赖显式调用手动指定场景更多自动触发能力弱于 Claude Code迁移时不要整个目录直接复制我的建议是先抽出一个最简单的 skill 做最小验证确认 SKILL.md 的 YAML 字段和路径规则都兼容再批量迁移。尤其要注意 name 字段是否需要和目录名严格一致有些工具管得很严不一致直接不加载。5.4 过期与失效 skill 的抢救策略skills 生态更新极快很多仓库作者当时写得很认真但过了几个月底层的 CLI 命令或第三方 API 变了skill 里写的步骤就全废了。遇到这种情况第一反应不应该是“删掉重找”而是打开 SKILL.md把过时命令替换成当前可用版本。这种修补方式通常比从零写更快因为整体思路还在只是实现细节要更新。如果修不动那就删。别心疼也别让失效技能继续躺在目录里干扰 agent 的触发判断。一个包含大量过时内容的 skill 在触发时会把错误步骤教给 agent比不装还恶劣。我自己每两个月会专门做一次“技能大扫除”把不用的、失效的、和现有工作流重复的都清理掉这套习惯让我的实际触发准确率高了不少。6. 从用到写一条不太累的学习路线6.1 先模仿再理解最后形成自己的写法很多朋友一上来就说“我要写一个惊为天人的 skill”我基本都会劝他先缓一缓。最有效的入门方式其实是先装五到十个高质量 skill逐个打开 SKILL.md逐行去思考它为什么要这么写 description、为什么要把某个步骤拆得那么细、出现什么情况时用到了 references。模仿是最好的学习等你读过几十个优秀的 skill 之后自己动手时会很容易找准节奏。我自己的经验是一开始写出来的 skill 特别“飘”因为总想覆盖所有场景。后来看多了社区大神的写法才明白好的 skill 都是收敛的description 精准正文步骤有限验收条件明确。它不是在展示作者懂多少而是为了让 agent 稳定输出一个合格结果。6.2 从你每天都在重复的事里找切入口写 skill 的选题策略不是追热点而是盯住自己的日常工作。问自己一个简单问题这周有哪些事我做了至少三遍而且每一步都不需要有太多临时判断如果有这就是一个非常适合封装成 skill 的流程。比如你是前端开发者天天处理页面和组件迭代那就把团队的设计系统、组件库约定、样式规范全沉淀成一个前端开发 skill如果你每次做数学建模都要先花两个小时清洗数据那就写一个数据清洗 skill把缺失值处理、异常值检测、分布分析全部固化成固定步骤。这类技能可能在网上没人下载但它对你个人生产力的提升是立竿见影的。毕竟 skill 的最终目的不是让别人 star而是让你自己在重复劳动中解脱出来。6.3 把多个 skills 组合成完整工作流进阶玩法是让多个 skills 形成上下游配合。比如“项目初始化”skill 负责脚手架和环境准备“前端开发”skill 负责日常编码规范“代码审查”skill 负责最终合入前的检查。三个技能按顺序触发就是一条完整的开发流水线。工具层面不需要专门做额外编程靠 description 的精准边界就能天然形成先后关系。我在一个实际前端项目里就是这么跑的agent 从初始化到提交代码每一步都会自动调用对应 skill行为明显比只塞一个巨型 skill 听话得多。唯一的额外成本是前几次跑通流程时会发现一些边界重叠需要微调描述或合并部分环节。但一旦稳定下来这套组合就会变成你的私有工作流比任何手工指定提示词都高效。最后再分享一点我个人感受skills 的价值在于把“我知道该怎么做”转成“agent 也能够按这个方法做”。它不复杂但需要你持续打磨。我的建议是从一个最小可用的技能开始不要想着一口吃成胖子装几个、写几个、踩几次坑你对这套机制的理解就会完全不同。
