最近这半年我几乎把所有精力都花在折腾 AI 编程工具上从 Claude Code 到 Codex再到 OpenCode每个都试了个遍。一开始以为这些工具的核心竞争力是模型本身后来发现真正让它们从能用变成好用的反而是那些不起眼的 skills 技能包。今天想好好聊聊这个话题把我的实践经验、踩过的坑、以及一套可以直接上手的技能包开发流程都分享出来。如果你也在用 Claude Code、Codex 这类命令行 AI 编程工具或者正在研究怎么让 AI 更稳定地完成特定任务这篇文章应该能帮你省下不少时间。我会从 skills 到底是什么说起然后逐步拆解它的安装、开发、推荐来源最后附上我整理的问题排查经验。先说个结论skills 技能包就像给 AI 装了一套专业领域的工作手册它本身不是代码逻辑而是一套结构化的指令和上下文规则。你装得越精准AI 的输出就越稳定越接近一个真正了解你项目的资深同事。1. 深入理解 SkillsAI 的岗位说明书1.1 打破误区Skills 不是插件也不是 Prompt 模板我经常看到有人把 skills 和插件Plugin、MCPModel Context Protocol服务器、普通 Prompt 模板混为一谈这其实是最大的认知误区。简单来说插件负责让 AI 能调用某个外部工具MCP 负责统一 AI 与外部系统的通信协议而 skills 负责的是告诉 AI 在这种情况下应该怎么做才算专业。你可以把 skills 理解成一套 SOP标准作业程序而不是一把扳手或一个 API 接口。举个例子你给 AI 装一个代码审查 skill这个 skill 内部不会去调用任何静态分析工具它提供的是审查时应该关注哪些维度安全性、性能、可读性、边界条件输出报告时应该用什么模板严重级别、问题定位、修复建议哪些场景下应该拒绝自动修复只做提示这本质上是在约束 AI 的行为范式而不是给它新的能力。理解这一点非常关键因为后面你自己写 skills 的时候思路会完全不同——你不需要去考虑怎么让 AI 调工具你考虑的是怎么让 AI 像一个有经验的人那样思考和表达。1.2 Skills 为什么突然火了从 TypeSafe AI 提出第一个可复用的 SKILL.md 开始到 Superpowers Skills 在 GitHub 上引起关注再到 Claude Code、Codex 在今年陆续原生支持 skills 目录这个生态的爆发速度非常快。背后有两条核心逻辑第一大模型的上下文窗口再大也不可能把所有领域的最佳实践都塞进一次对话里。通过本地加载 skills 文件AI 可以在任务开始前阅读相关领域的操作方法用很小的 token 成本换取极高的行为一致性。实测下来一个 300 行左右的 skill 文件加载成本不过几千 token但能让 AI 在后续数小时内的输出质量保持稳定这是单纯靠提示词堆砌根本无法实现的。第二skills 是天然可复用的。你写完一个数据清洗 skill不只是你自己能用整个团队、甚至整个社区都能用。GitHub 上已经出现了大量开源的 skills 仓库从编程开发到数学建模从内容创作到数据分析几乎覆盖了各个场景。我个人体会最深的是以前给 AI 布置任务每次都像在开盲盒同样的需求它这次这么做下次那么做完全没有稳定性。引入 skills 之后至少 80% 的任务变成了标准化交付这对工作效率的提升是革命性的。1.3 主流平台的 Skills 生态现状不同工具的 skills 实现方式有所差异我用过一段时间后总结出了各自的定位平台Skill 目录位置特点适合场景Claude Code.claude/skills最早支持生态最成熟文档完善日常开发、通用任务Codex.codex/skills与 OpenAI 系模型深度绑定配置灵活数学建模、代码生成OpenCodeopencode/skills更轻量社区驱动目录结构简单快速原型、个人定制通用 Skills 仓库.cursor/skills等通过配置文件适配多个工具团队共享、跨工具复用这里有个很实用的经验如果你写了一个 skill想让它在多个工具里通用尽量把核心内容放在一个纯 Markdown 文件里比如 SKILL.md然后用各平台自己的目录结构去引用它。不要为了某个平台写一堆特定配置那样反而失去了复用性。2. 手把手怎么手动安装 GitHub 上的 Skills2.1 安装前需要知道的三件事很多新手一上来就急着把仓库 clone 到本地结果装完发现根本没法用问题通常出在三个地方。第一确认你的工具版本是否支持 skills。比如 Claude Code 在某个版本之前只能通过插件系统加载技能原生 skills 目录是后来才加的。我建议先执行一下版本检查命令确认所在版本支持以后再做下一步。第二确认 skill 的目录结构是否规范。一个标准的 skill 必须有入口文件通常叫 SKILL.md并且在文件头部包含 YAML frontmatter声明 name 和 description 字段。如果没有这些元数据工具无法识别这个目录是一个 skill装进去也是白装。第三确认 skill 的依赖环境。有些 skills 需要特定命令行工具比如 jq、ffmpeg、node有些需要网络访问特定的 API。安装之前最好看一下 README 里的依赖说明否则运行时会频繁报错。2.2 完整安装流程以 Claude Code 为例我先以 Claude Code 为例演示手动安装一个 GitHub skill 的完整流程。假设我们要安装的是某个知名的前端开发 skills 包。第一步进入你的项目根目录创建 Claude Code 的配置目录。如果项目还没有这个目录手动创建一个即可mkdir -p .claude/skills第二步把目标 skills 仓库 clone 到临时目录或者直接下载需要的 skill 文件夹。GitHub 支持手动下载单个文件夹这里推荐一个很实用的方法——用svn export或者直接用 GitHub 的在线目录下载工具当然最稳妥的还是完整 clone 后复制git clone https://github.com/某用户/某-skills-仓库.git /tmp/skills-temp第三步查看仓库结构找到你想要安装的那一个 skill 子目录。比如仓库结构可能是这样的某-skills-仓库/ ├── README.md ├── code-review/ │ ├── SKILL.md │ └── review-template.md └── frontend-dev/ ├── SKILL.md └── rules/ └── vue-guidelines.md第四步把对应目录复制到项目的.claude/skills下cp -r /tmp/skills-temp/frontend-dev .claude/skills/第五步回到项目根目录启动 Claude Code随便发起一个相关任务观察 AI 是否自动加载了这个 skill。通常 AI 会在思考过程中引用 SKILL.md 里的内容或者在回答开头提到根据技能包的规范我将……之类的话。有这种反应就说明安装成功了。2.3 Codex 与 OpenCode 的安装差异Codex 的安装流程与 Claude Code 类似只是目录名要改成.codex/skills。但有一个关键差异——Codex 对 SKILL.md 头部 YAML 的 description 字段有更严格的要求。它推荐使用第三人称描述并且尽量包含可触发的关键词。举个例子--- name: frontend-review description: 用于前端代码审查关注 Vue/React 项目的性能、安全、可访问性。当用户要求 review 前端代码、检查组件质量或优化交互时可以触发使用。 ---这段描述里的review 前端代码检查组件质量优化交互都是触发词。AI 会根据任务语义检索对应的 skill触发词写得越准命中率越高。OpenCode 则更加轻量它基本遵循通用的 skills 目录规范但有一个额外约定如果 SKILL.md 里写了allowed-tools字段OpenCode 会优先在该字段声明的工具集内选择调用这个设计很适合做一些受限场景的定制。2.4 安装失败的典型症状与对策在实际操作中最常见的安装失败症状有以下几种症状一AI 完全无视 skill回答内容和以前一样。这多半是因为 description 字段写的太笼统或者触发词没有覆盖用户的表述习惯。症状二AI 报错Unknown skill或者Skill not found。这说明目录结构不对工具没有扫描到你放的技能目录。症状三skill 加载了但执行到一半因为缺依赖中断。这是没看 README 的典型结果先把依赖装好再试。我自己吃过最大的亏是把整个仓库直接塞进了 skills 目录而没把单个 skill 子目录作为最小单位。结果工具扫描到一堆嵌套的 SKILL.md行为变得非常奇怪。后来才明白每个 skill 目录必须保持扁平结构里面只能有一个 SKILL.md 入口其他辅助文件都是被它引用的资源。3. 从零开发一个自己的 Skills核心环节全拆解3.1 SKILL.md 的标准结构与编写心法如果你打算自己写 skill最重要的一件事就是掌握 SKILL.md 的标准结构。做到了然于胸后面所有的灵感都可以直接落成文件。标准结构分三块YAML frontmatter、正文指令、参考资源清单。YAML frontmatter 是最先被 AI 读取的部分它决定了这个 skill 什么时候被触发。name 字段很简单description 字段则需要仔细打磨。我之前写过一个教训第一次写 description 只写了一句用于文本润色结果任何涉及写作的任务都会触发它干扰严重。后来改成当用户需要改写、润色或压缩长文本或者希望调整语气风格时使用不适用于翻译和代码注释生成效果立刻精准很多。正文部分是核心指令要根据任务类型采取不同的写法。对于流程型任务用编号列表列出每一个步骤对于检查型任务用 checklist 形式给出所有检查项对于创作型任务用案例对比来示范好与坏的差异。这里要特别强调宁可写得啰嗦不要写得含糊。因为你写的每一句话都会被 AI 当作硬性要求来执行含糊的表述会让 AI 自由发挥结果就不受控。参考资源清单是可选的但你如果希望 AI 每次执行时都能参考特定模板、代码库最好以相对路径的方式把这些资源文件放进 skill 目录然后在 SKILL.md 末尾用明确的语句声明执行任务前必须阅读文件 xxx。3.2 设计一个数学建模辅助 Skill 的全程示例我拿自己用得最顺手的数学建模辅助 skill 来做一个完整拆解这个 skill 是从华为杯备赛开始写的后来在多次实战中打磨完善思路非常有代表性。首先是 design设计阶段。我在写这个 skill 之前先问自己三个问题这个技能主要服务哪类任务数学建模的赛题分析、模型选择、论文排版用户最常踩的坑有哪些乱选模型、不检验假设、论文结构混乱希望 AI 表现出什么样的行为范式先分析再建模、先验证再写结论想清楚以后我搭建了这样的目录结构math-modeling/ ├── SKILL.md ├── templates/ │ ├── a4-paper-structure.md │ └── model-selection-guide.md └── examples/ ├── regression-case.md └── optimization-case.md然后写了 SKILL.md 的核心指令节选如下--- name: math-modeling description: 用于数学建模竞赛或课后建模任务。当用户需要选题分析、模型选择、数据预处理、结果验证、论文结构设计时使用。如果用户只是要求做简单的数据绘图不需要使用本技能。 --- # 数学建模辅助指南 ## 执行流程 1. 与用户确认问题类型优化类、预测类、评价类还是分类聚类类。 2. 如果用户提供了数据先执行探索性数据分析EDA检查缺失值、异常值和量纲差异。 3. 基于问题类型推荐 1~2 个核心模型并说明选择理由不要超过 3 个候选。 4. 建立模型时必须同时给出假设检验方法。回归类模型需要检查多重共线性优化类模型需要分析约束条件的可行性。 5. 结果输出统一包含三部分模型表达式、参数含义、误差或敏感度分析。 6. 如果用户需要写论文参考 templates/ 下的结构模板输出章节骨架后逐节填充。 ## 禁忌 - 拒绝回答推荐一个最牛的模型这类问题必须结合数据量和问题场景来决定。 - 不要滥用深度学习模型当传统统计模型足够有效时优先使用传统方法。 - 永远不要跳过数据质量检查哪怕是时间紧迫。写完这一版之后我真实跑了几个题目测试发现 AI 有时候会绕过步骤 4 的假设检验直接给出漂亮的模型公式。后来我在禁忌里又加了一条强约束输出任何回归结果前缺失 R²、F 统计量和残差诊断结论时必须暂停输出并补充完整。这才把行为稳定下来。3.3 开发过程中容易犯的五个错误第一个错误是野心过大一个 skill 想覆盖所有场景。我最初想写一个万能写作助手 skill结果什么任务都处理不好因为指令彼此冲突。建议初始设计尽量聚焦在单一任务族上等稳定后再拆分子技能。第二个错误是只写正向要求不写约束条件。很多人的 skill 就是一堆要怎么样的清单而那些不要怎么样的边界条件只字未提。AI 在没有禁忌约束的时候倾向于自作主张所以禁止事项和例外条件必须占一定篇幅。第三个错误是资源文件用了绝对路径。一旦把 skill 分享给别人或者换一台机器路径就失效了。所有辅助文件都应该用相对路径引用并且在 SKILL.md 里写明本文件所在目录下的 xxx 文件。第四个错误是不做版本管理。SKILL.md 改了几版之后自己都分不清哪个是有效的。我现在所有的 skills 都放在一个 Git 仓库里管理每次修改都提交并且用版本号标注字段记录更新内容。这个习惯帮我在迁移环境时省了大麻烦。第五个错误是忽略跨平台兼容性。比如你写了一个需要调用jq的 skill在 macOS 上没问题但换到 Windows 环境就可能失效。发布或分发 skills 时一定要在 README 里写清楚依赖工具和对应平台的安装方法。4. 优秀 Skills 推荐哪些技能包值得装4.1 我整理的高口碑技能库社区里已经有非常多的开源 skills 仓库这里我按类别推荐一些我实测稳定、更新频繁的。技能包名称来源功能定位使用体验Code Review 技能包社区热门仓库代码审查与质量检查报告结构清晰严重分级合理Refactoring 技能包社区热门仓库代码重构建议能识别坏味道给出渐进式修改方案Frontend Development 技能包前端社区Vue/React 项目开发辅助对组件拆分和状态管理建议非常实用Data Cleaning 技能包数据分析社群数据探索、清洗与特征工程自动输出缺失率统计省了不少事Mathematics Proof 技能包学术编程社区数学推导与证明辅助擅长 LaTeX 排版步骤完整实时网络搜索技能包工具类仓库调用网络搜索获取最新信息需要配合 API Key配置成本略高要说明的是很多打包好的技能库并不是装上立刻能用还需要根据你自己的项目特点做微调。比如前端开发技能包默认针对 React你是 Vue 项目就一定得改一下里面的规则文件否则很多建议会跑偏。4.2 常用的 Skills 源网站和仓库如果你想找更多现成的 skills我推荐从这几个渠道入手。第一个是 GitHub 全站搜索。直接搜awesome skills或claude skills等关键词能找到大量汇总列表很多列表的维护者本身就是重度的 AI 编程工具用户筛选过的技能比盲搜好很多。我经常用的一个技巧是按星标数排序然后逐个查看最近几周的更新记录只保留活跃维护的技能包。第二个是 TypeSafe AI 的官方仓库。它的 skills 设计规范被很多平台认可仓库里也有很多高质量的参考示例适合用来学习标准写法。第三个是各工具官方文档中的 skills 收录页。Claude Code、Codex 的官方文档都有专门的 skills 指南页里面除了示例还会说明平台特有的一些扩展字段这是做跨平台适配的必备参考。第四个是一些社区整理的数学建模 skills专题仓库。这类仓库通常集合了数据预处理、模型评估、图表生成等多个子技能特别适合打比赛前一次性装好。我记得去年备赛时装了一套三天里省下的时间足够多写两版论文摘要。4.3 如何判断一个技能包是否靠谱判断标准就三条。第一条看它的设计是否遵循单一职责。如果 SKILL.md 里既写代码审查又写数据库优化还写前端调试这种大杂烩技能包最好避开因为 AI 极容易相互干扰。第二条看它是否有具体的禁忌条款和边界声明。没有禁忌条款的技能包只是把一些常识性要求堆在一起对 AI 行为的约束力非常有限。第三条看它是否有配套的测试示例或典型案例。靠谱的作者会在 examples 目录里放几个输入-输出示例你可以在自己的环境里复现验证技能效果是否可预期。没有测试示例的技能包效果很可能是薛定谔的稳定。5. 常见问题与排查技巧实录5.1 装了很多 Skills 之后 AI 变笨了这是一个非常普遍的现象装了一堆技能包之后AI 反而频繁跑偏、犹豫不决、甚至答非所问。我踩过一次大坑之后总结出原因技能包互相覆盖description 里的触发词重叠了。解决办法是给每个技能包划分清晰的触发边界。具体做法分两步第一步运行一下你正在用的工具的 skills 诊断命令。Claude Code 和 Codex 都有列出当前加载技能的命令通常还能看到每个技能的命中次数。第二步对命中次数高但你不常用的技能直接停用或移出目录对经常误触发的技能修改它的 description加上更严格的排除条件。举一个具体例子我装了中英文翻译和文案润色两个技能包结果每次写英文邮件时两个都会被触发AI 一会儿翻译一会儿润色输出乱七八糟。后来我把翻译技能的 description 明确为当用户明确要求将文本从一种语言转换为另一种语言且输入文本长度大于 50 词时使用把润色技能的描述加上不适用于跨语言改写冲突立刻消失。5.2 技能没生效时怎么定位问题我的排查顺序一向是由外到内。先检查技能目录是否被工具扫描到。有些工具支持/skills这类斜杠命令查看技能列表如果列表里没有你装的技能说明目录结构不对。再检查 SKILL.md 的 YAML frontmatter 是否解析成功。YAML 是出了名的对缩进敏感我有一次只是把 description 后面的冒号写成了全角冒号整个技能就无法识别花了半小时才找到问题。接着检查描述语是否与你的任务匹配。你可以故意把问题描述得和 description 里的关键词高度一致测试技能能否触发。如果仍不触发就是 description 表达的问题如果触发了但表现异常问题出在正文指令。最后检查辅助文件能否被正确读取。SKILL.md 里如果写了参考 xxx.md确认这个文件确实存在于技能目录下同时确认它没有依赖其他缺失资源。很多技能失效的原因不是主文件坏了而是二级资源文件被移动或删除。5.3 性能占用的顾虑要不要担心有些人不敢装太多技能怕每次对话都把所有技能内容加载进上下文导致 token 消耗暴涨。其实大多数主流工具在实现 skills 时都做了延迟加载也就是先扫描所有技能的 description再根据当前对话内容判断是否需要把某个技能正文完整加载进来。所以平时你装了 50 个技能实际每次对话可能只加载 1~2 个正文上下文开销远比想象中低。但有一个例外如果你的 description 写得太模糊导致多个技能同时被触发那就会同时加载多个正文token 自然就上去了。这也是为什么我一直强调description 的排除性描述比包揽性描述更重要。宁可让技能在某些边缘场景下不触发也不要让它频繁误触发。5.4 跨平台复用时需要注意的细节如果你和团队同事用的工具不一样或者你自己从 Claude Code 换到了 Codex技能包跨平台复用时要注意三个细节。第一个细节是 YAML 字段的兼容性。虽然大部分平台都认 name 和 description但某些高级字段比如 allowed-tools在部分平台会被忽略甚至可能因为未知字段触发报错。跨平台复用之前先删掉平台特有的字段只保留通用字段。第二个细节是命令规范和系统差异。如果技能正文里写了很多 shell 命令尽量使用跨平台的写法。比如用python -m pip而不是pip用路径拼接说明而不是假定/usr/local/bin等固定目录。第三个细节是触发语境的差异。同一个技能在 Claude Code 里表现良好不代表在 Codex 里也一样。因为底层模型不同对指令的服从程度和解析风格会有明显差异。我建议每个平台都保留一份微调记录记录哪些描述在该平台下命中率更高慢慢形成自己的一套适配笔记。6. 关于 Skills 的后续扩展思路聊了这么多实操细节最后再分享一个我最近在尝试的方向就是技能包间的编排与联动。单个 skill 能解决的问题有限但如果把多个 skill 串联起来效果会非常惊人。比如我正在实验的一套数据分析 图表优化 论文排版组合先让数据清洗技能处理原始数据再让图表生成技能输出统一风格的图最后让论文排版技能把图和表组织进标准结构中。每一个技能只负责一段环节但它们通过主任务串成一条流水线整个流程稳定性和执行效率比我之前的单一指令高了很多。这件事的意义在于skills 不只是一个个孤立的指令包它本质上是一套可以设计的智能体工作流的最小单元。你把一个复杂的协作过程拆解成多个 skills再通过主任务描述来编排它们的调用顺序这其实就是一种轻量级的 AI Agent 架构搭建。不需要复杂的框架和配置也不需要写代码只要你会写 Markdown就能完成整套编排。还有一个小技巧值得分享写 skill 时尽量留下记录评审意见的位置。AI 每次执行完任务后让它总结出本次执行的不足之处追加到 SKILL.md 的常见问题段落里。这样每次执行都会让技能包自动进化。我用这个方法跑了三个项目之后技能包的质量已经完全不像是第一版的样子了。最后说一个我自己的体悟不要神化 skills也不要轻视它。它本质上就是用可控的成本给 AI 立规矩。规矩立得越清晰AI 的表现就越可预期。如果你现在还在重复地、费力地向 AI 描述每一个任务应该如何做那我想告诉你试着把这些指令沉淀成技能包你会看到完全不一样的效率变化。