从去年底开始AI 编程圈子里出现频率最高的一个词就是 skills。你可能已经在不少仓库里见过.claude/skills、.codex/skills这类目录也可能在社交平台上刷到过给 Claude Code 装上一套技能之后写前端快多了之类的分享。我最近一直在折腾 skills从 GitHub 手动装别人写好的到拆解学习、自己改写、自己新建再到因为装了一堆技能把对话上下文搞崩各种坑都踩了一遍。这篇把完整经验整理出来写给刚开始接触 skills、想通过技能库提升 AI 使用效率的开发者、学生和内容创作者——无论你已经用上这些工具还是正在观察读完应该能少走不少弯路。1. skills 到底是什么为什么大家都在聊1.1 一个技能包解决的是什么问题先把最本质的问题说清楚skills 在 AI 编程工具里承担的角色很像老员工给实习生准备的一本岗位操作手册。实习生临时接活你口头交代两句他大概率回你一个中规中矩的答案但你如果甩给他一本手册里面写清楚遇到这类需求怎么拆解、用什么工具、有什么红线、完成后按什么标准自检他交出来的东西质量会完全不一样。skills 就是那本手册。具体到实现形态常见做法是在项目目录或者全局配置目录下建一个名字清晰的文件夹里面放一个SKILL.md作为主入口旁边还可以带references/、templates/、scripts/之类的附属资源。AI 会在对话开始或任务匹配时扫描这些技能按需把内容注入到上下文里。它的目的不是改变 AI 的基础能力而是把你会做变成你知道在这个项目里应该怎么做——后面这一点恰恰是大多数人使用 AI 时效率差距的真正来源。我印象很深的一个例子是前端开发。没有 skill 的时候让助手帮我写一个页面它经常会给出很通用的方案默认组件库、默认目录约定看起来没毛病但放进真实项目里往往要大改。后来我给项目配了一个专门描述前端开发习惯的 skill写明组件库版本、命名规范、页面目录结构、以及禁止直接改哪些文件再让它写页面时几乎可以一次性命中规范。这个对比让我彻底理解了skills 解决的是稳定地输出高质量结果的问题而不是能不能输出结果的问题。1.2 为什么不直接在提示词里写规则刚开始接触 skills 的人都会冒出同一个疑问这些规则不也能写进提示词吗为什么还要单独搞一套文件夹原因主要有三个。第一是上下文窗口的稀缺性。大模型的上下文是有限资源如果你每次开会话都贴两千字项目规范真正留给任务计算的额度就被占掉了。skills 是按需加载的AI 先根据用户请求和技能描述做匹配匹配上的才注入匹配不上的一行都不占干净利落。第二是复用和分享。提示词粘在聊天框里人走茶凉skills 记在文件里换机器、换项目、提交到 GitHub、分享给同事都是实实在在的文件操作。你可以给一个 skill 做版本管理用了几个月发现某个规则过时了改一行文件就生效不用翻聊天记录找之前的提示词文本。第三是让工具的记忆不再是黑盒。打开AGENTS.md、再打开 skills 目录你能一眼看清当前项目约定了什么团队协作时这比你记得我上次让你不要用某个框架靠谱得多。你可以把AGENTS.md理解为常驻记忆把 skills 理解为可调用的专项手册两者配合才能发挥最大作用。1.3 一个 skill 由什么组成从结构上看一个标准 skill 通常包含这几块元信息区name、description写在SKILL.md开头的 YAML 区域。description是 AI 判断什么时候该用这个技能的依据写得好不好直接决定触发率。正文指令区说明适用时机、执行步骤、输出格式、质量标准和禁止事项。引用资源references/放详细文档或范例templates/放可直接套用的模板scripts/放辅助脚本正文里用相对路径引用这些文件。所以装一个 skill本质就是把一套经验和规则下载到本地让 AI 在需要时读一遍。理解了这点后面不管是手动安装还是自己写思路都会顺很多。像前端开发 skills这类垂直技能放到前端项目里就是项目团队的最佳实践沉淀像数学建模 skills这类竞赛向技能放到公开仓库里就是可以分享给队友的解题作战手册甚至做 AI 漫剧、短视频脚本的人也可以把分镜规则、角色一致性提示词、镜头语言规范做成 skill生成脚本时自动匹配。这就是为什么各种行业的人都在开始碰 skills。2. 动手之前先想清楚技能放全局还是放项目2.1 主流工具的 skills 目录长什么样不同 AI 编程工具对 skills 的支持深度不一样但设计思路大同小异。以社区里讨论最多的 Claude Code 为例约定俗成的目录是项目级放在.claude/skills/下全局级放在用户目录的.claude/skills/下。每个 skill 以目录为单位目录名就是技能名目录里必须有SKILL.md。Codex 和 OpenCode 也有类似的技能机制社区里常见的做法是.codex/skills/和.opencode/skills/但不同版本细节有差异。动手之前第一件事永远是查一下当前版本的官方文档别拿一个月前的经验硬套新版本。这里多提一句很多开源仓库直接叫skills/不带工具名后缀是因为作者想做成跨工具通用的。实际用的时候你可以把这类通用技能分别复制到不同工具的 skills 目录下或者通过工具的导入机制安装。判断一个技能是不是跨工具通用看它正文里有没有写死某个工具专属的命令或格式如果全文只是规则 建议 模板那基本通用。2.2 全局目录和项目目录怎么分工我自己的分工原则很简单全局放能力向的技能项目目录放业务向的技能。能力向技能指的是跨项目都成立的能力。比如代码审查技能不管你在哪个仓库它都会告诉你先看安全再看性能再读可读性比如测试用例编写技能告诉 AI先列边界条件再补正常路径还有 Git 提交信息规范让它按 Conventional Commits 格式写 commit。这类技能放到全局所有项目都能用收益最大。业务向技能指的是跟某个具体项目强相关的约定。比如你们项目用某个内部 UI 组件库、有特定的环境变量映射、上线前必须跑某条命令这类内容放到项目目录里跟着仓库走同事 clone 下来也能看到。放全局反而会污染其他项目导致 AI 在无关场景里也试图套用这套规则。有个容易忽略的点全局技能优先级通常低于项目技能但两者都可能被加载。我建议全局技能数量控制在 5~8 个项目技能控制在 2~3 个。装得太多AI 会出现选择困难多个 skill 的 description 互相重叠时它不知道该调哪个。后面第 5 章会专门讲这个问题。3. 从 GitHub 手动装一个 skills 的完整流程3.1 先学会判断哪些 skills 值得装GitHub 上 skills 仓库多如牛毛质量天差地别。我装过几十个最终留下来的没几个。现在筛选时主要看这几项筛选维度具体标准为什么重要仓库活跃度最近一年有没有更新记录skills 语法和工具版本迭代快老旧写法容易失效star 与 issuestar 数不是唯一标准重点看 issue 里有没有人反馈不生效大量未解决 issue 说明作者可能已经弃坑目录结构是否符合skill名/SKILL.md的标准结构结构不规范会直接导致加载失败description 质量描述里是否说明了触发场景和适用人群描述模糊的技能基本废了一半依赖复杂度是否依赖特定目录、固定脚本路径依赖越多换环境越容易出问题实操上我的习惯是先搜仓库不急着 clone点进去看两样东西SKILL.md的 YAML 描述写得认不认真以及目录里有没有实际案例。描述认真的作者通常会写当用户要求某件事时使用不适合什么场景这类明确边界有实际案例的说明作者自己真的跑通过。3.2 三种常见的安装方式这里以 GitHub 上的 skills 仓库为例说三种我实际用过的安装方式。第一种git clone 整个仓库然后把技能目录复制到本地 skills 目录。适合安装大型技能库比如社区里很火的 superpower skills——它本质是一整套互相协作的技能集合。操作上你先把仓库 clone 到本地临时目录再看它的目录结构决定是整体安装还是只挑几个技能。如果你是首次接触我建议先整体装一遍跑起来再慢慢删不用的。# 以 Claude Code 为例假设技能库克隆到了 ~/tmp/superpower-skills mkdir -p ~/.claude/skills cp -r ~/tmp/superpower-skills/skills/* ~/.claude/skills/第二种从 GitHub 网页下载某个仓库的 ZIP 包解压后只保留需要的技能文件夹。这种方法适合你只想用某个技能库里的两三个技能。比如我看到一个仓库里有数学建模相关 skill但其他技能用不上就下载 ZIP解压后把对应目录复制进~/.claude/skills/。注意解压后经常会出现仓库根目录/技能目录两层甚至三层嵌套复制的时候要看清目标应该直接就是技能目录。第三种只复制单个 SKILL.md 文件。有些技能特别轻量正文就是十几个步骤加上几个示例没有附属资源。这种直接把SKILL.md放进一个同名目录里就行。但要注意如果正文里引用了相对路径的资源文件只复制主文件会导致资源丢失所以我一般先确认一下正文里有没有引用再决定要不要单文件安装。无论哪种方式装完都要验证。验证方法很简单重启当前 AI 会话让它列出可用技能不同工具的命令不一样Claude Code 里是/skills确认目标技能出现然后打开一个新对话用 description 里提到过的触发词提一个需求观察它有没有真的使用对应规则。实测中最多的问题就是装完不重启会话导致不识别这不怪技能怪我自己急。3.3 大型技能库安装后的瘦身问题superpower skills 这类全集式技能库装起来爽用起来容易出问题。因为里面的技能数量可能超过二三十个每个 skill 的 description 都很宽泛一起加载后 AI 每次对话都要做大量匹配结果经常是命中了一个不精确的技能输出反而不如不装。我自己装完 superpowers 的第一周代码审查技能几乎每次都被误触发改了几次 description 才消停。所以我现在装大型技能库遵循装完立刻瘦身原则先整体 clone再逐个打开SKILL.md看 description把明显用不到的开始前冷静一下只保留真正常用的五六个。而那些描述互相交叉的技能比如两个都讲代码质量改进我会合并成一个。这个习惯帮我省了很多上下文空间也让 AI 的命中率明显提升。4. 自己动手写一个 AI skill从 0 到 1 的完整示例4.1 SKILL.md 的文件结构与 frontmatter 写法自己写 skill 这件事真没想象中难。一个最小的 skill 长这样my-skill/ ├── SKILL.md └── references/ └── example.mdSKILL.md开头是 YAML frontmatter两个字段最关键--- name: my-skill description: 当用户需要【做某类任务】时使用。适合【特定角色/场景】不适合【反向场景】。 ---name相当于是技能名description是 AI 决定何时加载的唯一依据。这里有个写描述的技巧把触发场景、目标对象、明确行为写全把反向不适用场景也写进去。AI 不是靠目录名理解你的技能而是靠这段描述做语义匹配。描述写得太抽象比如用于数学建模AI 在普通代码问答时也可能乱触发写得更精确比如当用户提出数学建模题目、需要模型选型或写数模论文时使用命中率会高很多。frontmatter 之后是正文一般分这几个小节适用时机什么情况用、什么情况别用。执行步骤按顺序列出具体操作流程。质量标准完成后的验收标准。禁止事项明确不能做的事。4.2 实例一个数学建模比赛 skill 怎么写我拿竞赛场景写个简化示例这个结构任何领域都能套--- name: math-modeling description: 数学建模题目解题与论文写作辅助。当用户提出建模问题、需要做模型选择、写数模论文、准备建模竞赛时使用。 --- # 数学建模竞赛辅助 ## 适用时机 - 用户给出建模赛题需要拆解和求解 - 用户需要从多类模型优化、统计、机器学习等中选择合适方案 - 用户需要完成数模论文或思考论文结构 ## 工作流程 1. 问题重述把赛题拆成目标/约束/数据/交付物四要素 2. 数据预处理先检查缺失值、异常值、量纲差异再选模型 3. 模型选型根据数据量和问题类型推荐模型并给出选择理由 4. 模型求解优先用 Python 生态常见库代码要可运行 5. 结果评价做灵敏度分析和误差分析不要把结果说死 6. 论文结构化输出按摘要/问题分析/模型建立/求解/模型评价的套路组织 ## 质量标准 - 所有代码能直接运行依赖标注清楚 - 关键结论必须有数据支撑不能凭空断言 - 模型分析要包含为什么选它它有什么局限 ## 禁止事项 - 不得伪造或虚构实验数据 - 不得跳过数据预处理直接建模 - 不得把灵敏度分析省略成一句话这个 skill 我实际用过给朋友参加竞赛帮了不少忙。你会发现它做的不是替 AI 思考而是把一套参赛者应该有的解题纪律注入进去。数学建模这种任务最大的风险不是 AI 不会算而是它算到一半偷懒比如不检查缺失值就直接跑回归。skill 里的禁止事项就是用来踩住这个刹车的。4.3 从一份规则到完整技能库的迭代路径不少人第一次写 skill 会犯一个毛病一股脑把能想到的规则全塞进去。结果就是技能正文又长又散AI 加载后也抓不住重点。我自己迭代 skill 一般分三个阶段v1 先写触发描述 五条以内核心步骤。这个阶段目标是让技能能用、能被触发。规则少不代表坏至少不会把 AI 绕晕。v2 补禁止事项 一个真实示例。禁止事项是 AI 输出质量最直接的提升点示例则能让它照着模式走。这一步做完技能通常就有实战价值了。v3 再把大段细节移到references/或templates/里。比如数模 skill 的完整论文提纲移到references/paper-template.md正文里只留按论文模板输出几个字。这样正文短、匹配精准、加载不占太多上下文需要细节时 AI 再按需读文件。这条路径走下来你会发现自己对怎么给 AI 下指令的理解都会上一个台阶。因为写 skill 本质就是在做把模糊经验转成结构化规则这件事。5. 常见问题与排查技巧实录5.1 装了好几个技能怎么确认它在不在 / 它有没有生效验证顺序很重要别一上来就怀疑是技能文件写得不对。先看基础再看触发检查项操作常见结果目录是否被识别在工具里查看 skill 列表列表有名字 → 目录没问题文件是否完整查看SKILL.md是否在正确层级frontmatter 报错 → 往往缺结尾---触发是否准确用 description 中的关键词发起对话技能没有反应 → 看描述是否太窄或太宽是否被其他技能干扰临时禁用其他技能目录再测生效了 → 说明 description 重叠需要合并是否在旧会话测试确认是重启后的新会话旧会话可能没重新加载技能列表这里面最容易踩的坑是技能明明装了但在旧会话里测半天没反应其实新会话就好了。另一个常见坑是 YAML frontmatter 格式写错比如少了结尾的---或者 name 里带了空格。格式问题最隐蔽因为 AI 不一定报错它只是默默忽略这个文件。5.2 技能太多导致上下文爆炸怎么清理我说过技能是按需加载但按需不等于按需的全部细节。如果同时存在五六个 description 表达相近的技能AI 可能把多个技能都加载进去上下文和注意力的浪费非常明显。表现就是对话越来越笨明明很简单的请求它也要费很大劲。我之前在社区看见过 tibo 分享的一套路清理思路后来一直按这个思路执行每季度做一次技能审计把过去三个月一次都没触发过的技能全部移除或归档。具体操作分三步从工具日志或者对话记录里统计技能命中次数哪些技能从没被触发过。没触发的原因分两类一类是场景确实用不到直接删掉另一类是 description 写得太偏导致识别不到这种先改描述再给一个季度试用期。把暂时舍不得删的统一移到一个disabled-skills/目录下相当于归档。想恢复就移动回去没必要一次性删干净。清理完的标准是全局技能列表一眼能扫完每个技能的 description 边界清晰不出现好像这个也能干那个也能干的重叠感。我的经验是对个人使用来说8 个精悍技能的效果好于 30 个花哨技能这不是保守是真测出来的。5.3 从社区下载的 skills 有哪些坑第一就是盲装脚本。有些 skills 会带scripts/里面是自动化脚本装之前一定用编辑器打开看一眼。看什么看它有没有要求执行系统命令、有没有硬编码路径、有没有从网络拉取内容。倒不是说社区有恶意而是很多人就是本地跑通了随便传依赖环境的脚本在你机器上可能产生预期外行为。装完先手动跑一遍脚本再交给 AI 调用这个习惯能防住大多数麻烦。第二是格式老旧。GitHub 上很多 skills 是几个月前写的当时支持的语法和目录约定可能跟当前版本不同。安装后如果发现不识别不要急着改自己的配置先回仓库看看 issues 里有没有人提当前版本用不了如果有大概率要等作者更新或者自己照着当前文档改 frontmatter 字段。新的工具版本迭代很快昨天能用的写法今天就可能被标记为 deprecated。第三是改完不知道哪来的维护问题。你从不同仓库各抽了几个技能过段时间可能忘了它们是干嘛的。我的习惯是在每个 skill 目录里加一个README.md寥寥几行来源仓库、安装日期、我修改了什么、上次使用时间。维护成本极低但排查哪个技能在作怪时这套索引能帮你省下大量时间。6. 去哪找 skills、怎么系统性入门6.1 GitHub 搜索关键词与资源方向很多人在社区问skills 技能库网址常用 skills 源网站其实答案就在 GitHub 里。搜索关键词比问别人靠谱至少你可以自己判断质量。我常用的搜索词有这么几个方向claude skillsClaude Code 专属技能搜到的大多带.claude/skills结构。codex skillsCodex 方向的技能集合最近也开始流行起来。awesome skills聚合仓库类似 awesome 系列会按类别整理一堆技能。superpower skills社区里知名度很高的整套技能库偏通用向。typesafe ai skills做类型安全方向的人可能会感兴趣偏工程实践。cola skills、codex nature skills这两类命名风格我最近频繁刷到属于特定人群开始攒技能库的信号搜一下能看到不少野生的个人技能集。提醒一句话不要只看 star 数。GitHub 上 AI skills 生态还很新很多优质技能仓库的 star 数并不高反而是个人博客或者 issue 里推荐的更实用。判断标准永远是打开SKILL.md看三分钟我觉得它解决的是不是我真遇到的问题。6.2 从抄到写一套适合自己的学习路线我自己的学习路线大概经过四个阶段分享出来供参考。阶段一拆解别人写的 skill。找一个 star 高、结构干净的仓库把每个SKILL.md当成范文读重点看 description 怎么写的、正文怎么组织、禁止事项列了什么。不用急着理解每句话先建立标准长什么样的感觉。阶段二复制并微调。把某个通用技能复制进来把里面如何写代码的大原则改成我们项目怎么约定的细节。这个过程会逼你思考原文为什么要写某句话。阶段三从自己的痛点反推。观察自己平时用 AI 最常遇到的失败场景比如它总是忽略异常处理它给的答案不符合我们论文格式。把这些痛点整理成技能规则用 5.2 节的迭代路径写出 v1。阶段四给技能做减法。到这一步你已经能写很多 rule 了接下来要学的反而是一直删减只保留少了它 AI 就会犯错的部分。删掉那些加了也不影响结果的废话技能的质量才算真正立住。至于如何学习 skills 技能这个更通用的问题我的答案其实很朴素找一个小项目给 AI 写三个技能用两周回来再看别人的技能你会突然看懂之前看不懂的细节。这跟学编程一样看懂别人的代码和亲手写过代码完全是两种体验。AI 漫剧方向的朋友如果想做分镜技能角色一致性技能同样可以按这条路线走先拆解现有生成工具的参数和常见失败案例再把经验写成规则最后脚本化、模板化。说点个人的实际操作体会。我最终保留的全局技能其实只有七个但从它们身上得到的收益远超当初安装的三十几个。现在每次新开一个项目我会顺手花五分钟写一个项目专属 skill记录这个项目最常出错的三个点。三个月下来这些五分钟技能已经攒成了一本覆盖我自己工作习惯的手册。市面上能下载的 skills 再多最后真正离不开的往往是你为了解决自己问题而写的那几个。这也算这两年 AI 工具浪潮里我觉得最值得复制的一种玩法。