最近几个月我几乎把 Claude Code 和 Codex 当成了日常主力开发工具但有个问题困扰了我很久每次换个项目都得把技术栈、目录结构、代码风格、提交规范这些内容重新在提示词里交代一遍。后来在社区里看到有人聊 skills说是能把这种重复劳动彻底干掉我就开始折腾了。这篇文章就是我从零开始理解、安装、编写 skills 的全过程记录包括怎么从 GitHub 手动装一个现成的 skills 到本地怎么写一个能真正干活而不是花架子的 SKILL.md以及前端开发、数学建模这些场景里怎么挑到好用的现成技能包。1. Skills 的本质它和普通提示词最核心的差别在哪里1.1 一个被反复测试验证出的边界我先说一个自己折腾很久才想明白的结论在一个 AI 编程工具里加一句提示词和挂载一个 skills完全是两码事。提示词是“这一次对话你听我的”skills 是“你从此具备这种处理能力”。我刚接触的时候也觉得不就是把一堆指令挪到文件里吗直到我做了个对比实验。同一批任务A 组用超长 system prompt 把规则写在对话上下文里B 组把同样的规则整理成一个 skill 文件。结果 A 组的模型在对话进行到中段时已经开始忽略后面那几条规则了而且上下文窗口被大量规则说明占掉留给实际代码的空间明显变少。B 组的情况是模型在需要的时候才把 skill 内容拉进来日常对话上下文里很干净规则执行也更稳定。这个实验之后我才真正理解skills 的核心价值不在于“写什么”而在于“什么时候被加载”。1.2 触发机制与 SKILL.md 的文件组织现在主流 AI 编程工具Claude Code、Codex、opencode 这些的 skills 机制底层都是同一套逻辑一个 skill 就是一个文件夹文件夹里必须有 SKILL.md 文件文件头部是一段 YAML frontmatter里面至少要有name和description两个字段。模型就是靠 description 判断什么情况下该激活这个 skilldescription 写得越精准触发就越可靠。--- name: csv-merge-helper description: 当用户需要合并多个CSV文件并处理列名映射、去重和编码问题时使用。适合10万行以内的表格数据。 --- # CSV 合并助手 正文部分这就好比你是给实习生一份工作手册封面必须写清楚“碰到什么情况翻这本手册”而不是让实习生把整本手册背下来。skill 目录里除了 SKILL.md通常还可以放 references 子目录存参考资料scripts 子目录放可直接执行的脚本。一个只包含文字的 skill 和附带真实脚本的 skill干活能力差距非常大——前者只能让模型“假装”验证后者能让模型真的跑一遍脚本并把结果反馈出来。1.3 结构对了字段才能精准触发很多人把 skills 和 prompt 模板混为一谈这个理解太窄。我见过一个 LaTeX 排版 skill里面带了一个编译检查脚本模型遇到论文排版任务时会把 .tex 文件实际编译一遍报错信息直接回传。这是纯提示词根本做不到的。skills 的组织结构决定了它能承载的不只是“说话方式”还包括可执行逻辑、领域知识库、操作规范。所以评估一个 skills 好不好用第一件事是看 SKILL.md 的结构和 description 的写法而不是看它功能名字多响亮。description 里如果写着“当用户需要写代码时使用”这种又大又空的触发条件装了也是浪费位置因为几乎每个任务它都会跳出来抢触发权。2. 手动安装 GitHub 上的 Skills从 clone 到正式挂载的完整链路2.1 怎么从 GitHub 快速定位一个靠谱的仓库GitHub 上搜awesome-claude-skills、awesome-codex-skills这类关键词能找到不少汇总仓库。先别急着装用三个标准筛一遍第一仓库里有没有成规模的 SKILL.md 文件如果一个仓库主要是纯 README 宣传页基本没有实际可用的内容第二是不是一个 skill 对应一个独立文件夹那种把所有技能堆在一个大目录里、靠 README 说明来区分的后期会非常难维护第三随便点开几个 SKILL.md看 description 写得是否具体。快速浏览描述是判断是否可用的核心。比如“帮助用户进行前端代码审查”和“当用户需要审查 React 组件代码关注性能、可访问性和状态管理问题时使用”后者明显更可落地。前者模型不知道什么时候该用后者一碰到相关任务就会触发。2.2 全局生效还是项目级生效克隆完成后要决定装到全局目录还是项目目录。以 Claude Code 为例全局目录是~/.claude/skills/skill-name/项目级目录是.claude/skills/skill-name/。全局目录适合那些你天天用的通用能力比如代码审查、commit 信息规范、文件操作辅助项目级目录适合和当前项目强绑定的规则比如项目的代码风格、特定框架的生成规范。Codex 和 opencode 的目录约定不太一样路径上会换成各自的隐藏目录和 skills 文件夹但逻辑完全一致。如果你不确定某个 skill 到底装全局好还是项目好记住一个原则多项目通用就全局单项目专属就项目级。装混合了容易出问题我自己就遇到过同一个 skill 在全局和项目里各有一份改项目那份后发现全局那份的旧逻辑也在生效查了半天才反应过来。2.3 手动安装的实操命令下面以 Claude Code 为例完整走一遍手动安装的流程。# 进入你想要存放技能仓库的目录 cd ~/workspace # clone 一个汇总了多种 skills 的仓库 git clone https://github.com/your-collected/skills-repo.git # 创建全局 skills 目录如果之前没有的话 mkdir -p ~/.claude/skills # 把仓库里某个你需要的 skill 文件夹复制到全局目录 cp -r ~/workspace/skills-repo/csv-merge-helper ~/.claude/skills/ # 检查复制后的文件结构是否完整 find ~/.claude/skills/csv-merge-helper -type f复制完之后打开一个新的 Claude Code 会话直接用自然语言描述一个属于这个 skill 适用范围的任务观察模型是否触发它。如果是那种描述里带关键字触发类的 skill比如“处理 CSV 合并”你就直接给它一个合并三个 CSV 文件的任务看它是否主动调用。实测下来新会话几乎不需要额外配置就能生效关键是文件路径放对别把 SKILL.md 直接丢在 skills 根目录下那样不会被识别。2.4 我帮人排查安装时遇到最多的几个坑手动安装的坑我基本都踩过列几个高频的第一YAML frontmatter 解析失败。最常出现在 description 里写了换行、冒号、引号等特殊字符或者从网页复制内容时带了不可见字符。SKILL.md 文件必须用 UTF-8 编码保存文件名也不要有中文和空格。第二skill 内部引用的脚本路径失效。很多 GitHub 仓库里的 skill 脚本用的是相对路径一旦你把整个文件夹复制走脚本引用就会断。复制之后先查一眼 scripts 目录里有没有require、import、./路径这种引用有的话要改写成相对于 skill 目录的路径。第三多个 skill 的 description 触发条件重叠。模型容易选错甚至同时加载多个。装了两三个功能类似的 skill 后注意回头检查各自的 description最好是错开场景描述。我遇到过装了一个“代码审查”和一个“前端代码审查”结果一个后端任务把两个都激活了输出格式互相打架。第四网络不稳定导致 clone 的文件不全。这种问题看着像配置错误实际是拉取中断。遇到 skill 一直不触发先看本地文件大小和远端仓库差别大不大不完整就重新拉一遍。3. 手写一个能用的 AI Skills从零开始搭建的五步法3.1 第一步把 description 写成“触发说明”而不是“功能介绍”自己写 SKILL.md 最容易犯的第一个错误就是 description 写得太泛。拿我最开始写的一个数据分析 skill 举例我写的是“帮助用户处理数据文件”结果模型在几乎所有涉及文件的对话里都尝试调用它。改成“当用户提供 CSV 或 Excel 格式的数据文件且需要清洗、统计汇总或格式转换时使用”触发率一下子准了很多。description 的本质是给模型看的调度信号。它不需要文学色彩需要的是精确的适用场景、输入条件、甚至数据量级范围。越具体模型越容易在正确的时候把它拉出来。3.2 第二步正文按“输入-处理-输出”三段式搭骨架SKILL.md 的正文不只是一段描述它是模型在执行任务时实时读取的指令。我最推荐的写法是分三大块输入要求、处理流程、输出规格。输入要求里写清楚模型开始干活前必须先收集哪些信息处理流程里写具体步骤和禁止事项输出规格里规定交付格式和校验标准。还是用 CSV 合并这个例子来说明正文怎么写## 输入 收集以下信息 - 待合并文件的路径 - 不同文件列名不一致时的映射关系 - 是否需要全局去重 - 输出文件的命名要求 ## 处理流程 1. 用 Python 脚本读取所有 CSV统一编码为 UTF-8 2. 按映射关系规范化列名 3. 执行去重统计重复条目数量 4. 合并后写入新 CSV ## 输出 - 合并后的文件路径 - 摘要报告总行数、去重数量、字段列表 - 不要输出原始数据全文只输出报告摘要这个结构的好处是模型不需要自己猜“用户到底要什么”按流程走一遍就能产出稳定的结果。我写过一个教训早期版本把输出规格写得很随意模型有时候返回完整数据表有时候只给一句话说“已经合并完成”完全没法用。把输出规格钉死了之后两次运行的结果质量就基本一致了。3.3 第三步正面示例和负面约束同等重要模型是例子驱动型的给一个输入输出对的示例比写十句“请务必注意”都管用。在 SKILL.md 里加一段“示例”区域展示一个完整输入和对应输出的例子模型在生成时就有了参照对象。同时不要忽略负面约束。比如“不要在报告中贴原始数据只提供聚合结果”“如果文件编码无法识别直接报错而不是猜测”。我发现负面约束往往比正面要求更能有效防止模型自由发挥因为模型的默认行为就是尽可能详细地展示信息你要明确地把它挡回来。3.4 第四步本地调试的重要手段——新会话验证改完 SKILL.md 之后别在原来的对话里测试。模型的会话上下文里还保留着旧版本的记忆你改了文件它也可能还在用旧指令。一定要开一个新会话用最直接、最枯燥的方式描述一个属于该 skill 适用范围的任务观察触发情况。调试时我会做一个测试用例目录里面放几种不同类型的输入比如正常数据、带缺失值的数据、空文件分别验证模型的行为是否符合预期。这个习惯帮我抓住了不少问题比如某些 skill 在输入文件为空时直接崩掉而不是给出友好报错。要记住skill 的使用场景里必然有边界条件测试的时候一定要把这些边界情况跑一遍。3.5 第五步用 git 管理你的整套 skills自己的 skills 越来越多之后管理就成了大问题。我的做法是把 ~/.claude/skills 目录直接做成一个 git 仓库每次改动提交一次。这么做的好处是某次改完发现不如以前好用时可以直接回滚到上一个提交不用靠记忆恢复。每次新建一个 skill我会顺手更新自己的技能清单 README写上这个 skill 是干什么的、适用范围和限制。这个习惯坚持下来之后就算三个月没碰某个 skill翻一眼 README 也能立刻想起来当初为什么写它。4. 那些值得收藏的 Skills 源网站与场景化选型建议4.1 几个我常逛的入口和检索策略GitHub 是最大的 skills 资源池。我用的最多的检索策略是搜awesome-claude-skills、awesome-codex-skills这类 awesome 系列汇总这些仓库更新频率高而且经过社区筛选质量比直接搜关键词高不少。另外我也会关注一些经常分享 skills 的作者订阅他们的仓库跟着版本迭代走。市面上还有个套路是一些框架或组织会在 GitHub 上维护自己的官方 skills 集合比如 typesafe ai 这类偏类型安全的工程化项目GitHub 上能找到仓库。这类官方维护的技能包通常文档质量高、接口清晰适合当学习样例看。我的建议是先把开源汇总仓库里的热门技能装几个体验一遍再用“读了 10 个 skill 之后自己动手写 1 个”学习效率最高。4.2 前端开发场景下的 Skills 挑选逻辑前端开发是我日常用得最多的领域所以单独聊聊。相关的热搜词里一直有“前端开发skills”说明很多人都在找。装之前先想清楚前端开发的痛点在哪里组件生成、设计还原、性能优化、可访问性检查、代码审查。以 React 项目举例我会建议装这几类 skill第一React 组件生成 skill它的关键价值在于能输出符合项目目录规范的组件文件第二代码审查 skill好的审查 skill 会从性能、可访问性、状态管理三个维度进行检查第三可访问性检查 skill尤其适合做面向政企的项目能提前拦截很多合规问题。挑选标准只有一个看 description 是否提到具体框架、具体路径和具体检查维度。那种只写“帮助优化前端代码”的基本没什么用。4.3 数学建模与竞赛场景华为杯、国赛里的 Codex Skills 组合数学建模是另外一个搜索需求很密集的场景尤其是华为杯这类建模比赛时间紧、任务重非常吃工具效率。我看到热搜词里有“华为杯建模比赛好用的codex skills”这里分享一套我比较推荐的组合。数学建模的完整流程一般包括数据清洗与缺失值处理、探索性数据分析、特征工程、模型构建与调参、结果可视化、论文排版。对应到 skills我强烈建议按下面这个组合装表格数学建模场景 skills 组合建议建模阶段推荐的 skills 类型选型要点数据处理数据清洗与缺失值处理 skill要支持自动识别缺失值比例和数据类型建模蒙特卡洛模拟与采样 skill适合华为杯常见的不确定性分析题建模整数规划与优化建模 skill适合交通调度、资源分配类问题可视化出版级图表规范 skill需要配套真实绘图脚本能输出规范配色论文LaTeX 论文模板 skill必须附带编译检查脚本否则容易排版翻车这里额外强调一点Codex 这个工具本身偏向本地执行代码所以给 Codex 装 skill 时优先选那些带真实 Python 脚本的。比如“出版级图表规范”这种 skill如果只有文字描述模型也就是教你怎么调 matplotlib 参数如果带脚本它能直接扫描你的绘图代码并输出修改建议实用度直接翻倍。4.4 第三方打包类 skills 的取舍建议现在市面上有一些类似 superpower 这样把大量 skills 打包成一个扩展包的东西。这类包的优点是安装一次就拥有一大堆能力适合快速体验和提升首次使用的新鲜感。缺点是触发冲突很多几十个 description 挤在一起模型经常调错。我个人的建议是打包类扩展可以装但用一周后就要做一次“取出精华”的动作——把你真正高频使用的那几个 skill 拆到独立的全局目录里然后把打包扩展禁用。最终长期保留的应该是你反复在用、验证过触发稳定的那一小撮。5. 学习路径与日常维护从“装会”到“用得顺”5.1 最短路径的学习顺序关于“如何学习skills”这个话题我看到网上有各种五花八门的教程但我觉得真正有效的路线很短就三步第一步先不写只读。去 GitHub 上找 10 个星标高的 skill把 SKILL.md 逐个读完。不要光看结构要观察 description 的用词习惯、正文分节方式、示例怎么给。这一步花一个晚上就能完成但对后面自己写非常有帮助。第二步抄写再改写。找一个功能简单、结构清晰的 skill亲手敲一遍然后改造成适合自己场景的东西。比如找一个 CSV 处理的 skill把它改成处理 Excel 的。这个“抄写”的过程会逼你理解每个字段的作用。第三步在真实工作流里强制使用。不要只装不用。给自己定一个规则至少一周内在实际开发中三次以上主动触发自己写的 skill。用过之后记录哪里不顺手再回改。这一轮的迭代价值比前面所有学习都大。5.2 什么时候该清理一个 skills网上关于“清理skills的方法”也有不少讨论比如流传比较广的 tibo 那份清理指南。我结合自己的实践总结出三个清理信号第一个信号是装了一个月但触发率极低。如果这个 skill 在你的日常会话里从来没出现过那基本说明要么是你根本不需要这个能力要么是 description 写得让它永远没机会被激活。第二种情况应该改 description第一种情况应该删。第二个信号是两个 skill 的 description 重叠严重。你会观察到模型反复在两个 skill 之间横跳或者同时加载导致响应混乱。这种情况保留更具体、你更常用的那个删掉另一个。第三个信号是维护成本超过了收益。skill 里依赖的外部脚本频繁失效因为环境变化每次都要改这时候不如把这部分逻辑写成一个普通的脚本工具而不是继续当“技能”挂载。5.3 我用下来的几条维护习惯管理一个长期使用 skills 库我逐渐固定下来几件事目录命名统一用小写单词加中划线比如csv-merge-helper避免大小写混用给模型触发带来干扰。每个 SKILL.md 的 frontmatter 里加version字段。这纯粹是给自己看的回滚时特别有用。每季度做一次全量复查把所有 skill 的 description 重新读一遍删掉过时的合并重叠的。这个习惯让我现在的技能库总数一直控制在 15 个以内但每个都真正有用。注意全局和项目级两份 skill 不重复。同样能力的 skill 在不同层级各装一份会让模型在触发时产生内部竞争。5.4 一个值得长期坚持的小习惯最后分享一个我自己坚持了很久的小动作。每次新装一个第三方 skill我做的第一件事不是拿去干正事而是专门开一个新会话用“最粗暴直白”的方式触发它——直接输入“帮我合并这两个 CSV 文件”这种不加任何修饰的指令看它是否会被正确激活。如果连这种明显的关键字任务都不能稳定触发那大概率是 description 写得有问题趁早删掉或者自己改。这个习惯帮我拦下了不少看起来光鲜、实际根本不能用的技能包。目前在用的这套 skills 管理工作流已经帮我把重复性的项目初始化、代码审查、论文排版这些琐事省下了大量时间。如果你也在折腾 skills按上面的顺序走一遍——先懂机制再学安装后动手写最后定期清——基本不会走太多弯路。