1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它脑子里冒出来的问号是这不就是“技能”的英文吗有什么好聊的但如果你最近在折腾 Claude Code、Codex 或者类似的 AI 编程助手你就会发现这里的 skills 已经变成了一个非常具体的工程概念——它指的是一套写给 AI 看的、结构化的能力描述文件核心载体就是SKILL.md。说白了skills 就是给 AI 助手“开小灶”的说明书。默认情况下AI 编程助手什么都能聊一点但什么都不精。你让它帮你写一个 STM32 的串口驱动它可能会给你一段看起来对、跑起来错的代码你让它按你们团队的规范生成一个 React 组件它大概率会自由发挥。skills 要解决的就是这个问题把某个垂直领域的知识、流程、约束、示例用 Markdown 写成一份 AI 能读懂的文件放在指定目录下AI 在需要的时候会自动加载然后按照你定义的套路来干活。这套机制最早在 Claude 的生态里被明确提出后来 Codex、OpenCode 等工具也陆续跟进。现在你在 GitHub 上搜SKILL.md能翻出成百上千个仓库覆盖前端开发、数学建模、嵌入式、AI 漫剧、数据分析等各个方向。有人把 skills 比作“AI 时代的 npm 包”这个类比不算精确但方向是对的——它让能力可以沉淀、可以复用、可以分享。这篇文章适合谁看如果你是刚接触 Claude Code 或者 Codex 的新手想搞清楚 skills 到底怎么装、怎么写、怎么用那这篇就是写给你的。如果你已经在用 AI 编程助手但总觉得它“不够懂你”那 skills 就是你要找的答案。如果你只是好奇这个热词背后的东西读完你也能跟人聊上几句。下面我会从设计思路、核心细节、实操流程、常见问题几个角度把 skills 这件事彻底讲透。2. skills 的整体设计与核心思路拆解2.1 为什么是 Markdown而不是 JSON 或 YAML第一次看到SKILL.md这个命名的时候我下意识觉得应该用 JSON 或者 YAML 来定义毕竟结构化数据看起来更“工程化”。但实际用下来Markdown 是更合理的选择原因有三层。第一层是可读性。skills 文件不只是给机器看的更是给人看的。你写了一个 skills同事要 review新人要学习你自己过两个月还要回来改。JSON 里嵌套一堆引号和括号改一个字段要小心翼翼数逗号体验很差。Markdown 天然就是给人读的标题、列表、代码块、表格表达力足够写起来也顺手。第二层是表达力。skills 里经常需要嵌入代码示例、命令、配置片段、注意事项这些内容用 Markdown 的代码块和引用块表达非常自然。你甚至可以在 skills 里写一段“如果遇到 X 情况先检查 Y再执行 Z”这样的流程描述Markdown 的列表和段落能很好地承载这种半结构化的知识。第三层是解析成本。大语言模型对 Markdown 的理解能力极强因为训练数据里 Markdown 占比很高。你写一段 Markdown模型几乎不会误解你的意图。相比之下JSON 里的字段名和值对模型来说反而更“抽象”需要额外的推理才能理解语义。所以用 Markdown 写 skills本质上是顺着模型的“语言习惯”来效果自然更好。2.2 skills 的加载机制按需触发而不是全量注入很多人一开始会担心我写了几十个 skillsAI 每次对话都要全部读一遍那上下文不就爆了这个担心是合理的但 skills 的设计恰恰避开了这个问题。skills 的核心机制是按需加载。每个 skills 文件开头会有一个描述区域通常包含名称、适用场景、触发条件。AI 在处理你的请求时会先看这个描述判断当前任务是否匹配某个 skills。如果匹配才把完整的 skills 内容加载进上下文如果不匹配就完全不读。这就像你电脑里的软件装了几十个但只有你双击打开的那个才会占用内存。这个机制带来的直接好处是你可以放心地积累大量 skills不用担心它们互相干扰。我自己的 skills 目录里现在有二十多个文件涵盖前端、Python、数据库、文档写作等方向日常使用中从来没有出现过“上下文被塞满”的情况。AI 每次只会挑最相关的那个来用。2.3 和传统 Prompt 模板的本质区别有人会问这不就是 Prompt 模板吗我直接把要求写在对话里不就行了区别在于持久化和可组合。Prompt 模板是临时的你这次对话写了下次还得再写一遍。skills 是持久化的写一次放在那里以后每次都能用。更重要的是skills 可以被组织成一个库不同 skills 之间可以互相引用、组合。比如你有一个“代码规范”skills一个“测试编写”skills一个“提交信息”skills它们可以独立存在也可以在一个大任务里被依次触发。另一个区别是触发方式。Prompt 模板需要你主动粘贴skills 是 AI 自动判断。你不需要每次都说“请按照我的规范来”AI 看到任务类型就会自己去加载对应的 skills。这种“无感”的体验才是 skills 真正有价值的地方。2.4 方案选型为什么我最终选择了 Claude Code 生态市面上支持 skills 的工具不止一个Claude Code、Codex、OpenCode 都有自己的实现。我最终主要用 Claude Code原因有几个。一是生态成熟度。Claude 这边的 skills 规范最清晰社区贡献的 skills 最多遇到问题也最容易找到答案。GitHub 上搜SKILL.md大部分高质量仓库都是围绕 Claude Code 写的。二是加载逻辑稳定。我实测下来Claude Code 对 skills 的触发判断比较准不会出现“该加载的时候不加载不该加载的时候乱加载”的情况。Codex 那边早期版本有时候会忽略 skills需要手动提醒体验差一些。三是和编辑器的集成。Claude Code 在 VS Code 里的插件做得比较完善skills 文件可以直接在项目里管理改完保存就能生效不需要重启或者额外配置。这对日常高频使用来说很重要。当然这不是说其他工具不好。如果你已经在用 Codex 或者 OpenCode继续用也没问题skills 的核心逻辑是相通的。工具只是载体真正重要的是你写进SKILL.md里的内容。3. 核心细节解析与实操要点3.1 SKILL.md 的文件结构一个标准模板长什么样一个规范的SKILL.md通常包含几个固定区域。我拿自己写的一个前端组件 skills 举例结构是这样的--- name: react-component-generator description: 当用户需要生成 React 函数组件时使用遵循团队规范 --- # React 组件生成规范 ## 适用场景 - 用户要求创建新的 React 组件 - 用户要求重构现有组件 ## 核心规范 1. 使用函数组件 Hooks禁止 class 组件 2. 组件文件名使用 PascalCase 3. Props 必须用 TypeScript interface 定义 ... ## 代码示例 这里放一个标准组件的完整代码 ## 注意事项 - 不要使用 default export统一用 named export - 样式优先使用 CSS Modules开头的---包裹的区域是元信息name是 skills 的唯一标识description是给 AI 看的触发判断依据。这个 description 写得越具体AI 判断越准。我见过有人写“用于前端开发”这种太宽泛AI 很难判断什么时候该用。写成“当用户需要生成 React 函数组件时使用”就明确多了。正文部分就是具体的规范内容。这里有个经验规范要写成“可执行”的而不是“描述性”的。比如“代码要整洁”这种话没有意义AI 不知道什么叫整洁。写成“函数不超过 50 行超过就拆分”AI 就能执行。3.2 触发描述怎么写才能让 AI 准确识别触发描述是 skills 里最容易被忽视、但影响最大的部分。我踩过的坑是早期写了一个“数据库操作”skillsdescription 写的是“用于数据库相关任务”。结果每次我提到“数据”两个字AI 就把这个 skills 加载进来哪怕我只是在聊数据分析根本不涉及数据库。后来我把 description 改成“当用户需要编写 SQL 查询、设计表结构、或优化数据库性能时使用”误触发就少了很多。写触发描述的几条经验用“当……时使用”的句式明确触发条件列出具体的任务类型而不是笼统的领域如果有排除场景也写进去比如“不适用于数据分析场景”控制在两三句话以内太长了 AI 反而抓不住重点还有一个技巧你可以在 description 里嵌入关键词。比如数学建模的 skillsdescription 里写上“数学建模、竞赛、优化模型、评价模型”这些词AI 在判断时命中率会更高。3.3 内容组织的三层结构规范、示例、禁忌一个高质量的 skills内容应该分成三层来组织。第一层是规范也就是“必须怎么做”。这部分要写得硬用“必须”“禁止”“统一”这样的词。比如“必须使用 TypeScript”“禁止使用 any 类型”。AI 对这类指令的遵循度很高。第二层是示例也就是“做出来是什么样”。给一个完整的、可运行的代码示例比写十段描述都管用。AI 会模仿示例的风格和结构。我通常会在示例里故意放一些细节比如注释风格、错误处理方式AI 都会学过去。第三层是禁忌也就是“绝对不能怎么做”。这部分容易被忽略但很重要。比如“不要在组件里直接写 fetch 请求”“不要用 index 作为 key”。把这些写清楚能避免 AI 生成一堆你需要手动改的代码。三层结构写下来一个 skills 文件大概 100 到 300 行信息密度刚好。太短了不够用太长了 AI 加载成本高而且容易抓不住重点。3.4 文件命名与目录组织别小看这些细节skills 文件的命名和存放位置直接影响 AI 能不能找到它。Claude Code 默认会扫描项目根目录下的.claude/skills/目录也支持用户级别的~/.claude/skills/。我建议把通用 skills 放在用户级别项目特有的放在项目级别。文件命名用 kebab-case比如react-component-generator.md、sql-optimization.md。不要用中文名不要用空格不要用大写字母。这些看起来是小事但实际使用中命名不规范会导致 AI 识别失败排查起来很浪费时间。目录组织上我习惯按领域分文件夹.claude/skills/ ├── frontend/ │ ├── react-component.md │ └── css-modules.md ├── backend/ │ ├── sql-optimization.md │ └── api-design.md └── general/ └── commit-message.md这样管理起来清晰找起来也快。Claude Code 会递归扫描子目录所以分文件夹不影响加载。4. 实操过程与核心环节实现4.1 从零开始安装 Claude Code 并配置 skills 目录如果你还没装 Claude Code第一步是把它装好。Windows 用户注意Claude Code 需要虚拟机平台支持安装过程中如果提示“requires the virtual machine platform”去系统设置里把“虚拟机平台”功能打开重启一次就行。Mac 和 Linux 用户直接按官方文档走没什么坑。装完之后在项目根目录创建.claude/skills/目录。如果你想让 skills 在所有项目里都能用就在用户目录下创建~/.claude/skills/。我建议两个都建通用的放用户级别项目特有的放项目级别。VS Code 用户可以在插件市场搜 Claude Code装好之后在设置里把 skills 目录路径配好。配好之后你在编辑器里改SKILL.md保存就能生效不需要重启。4.2 写第一个 skills以“数学建模代码生成”为例我拿数学建模这个场景来演示因为最近问的人特别多。数学建模比赛里代码要跑得快、结果要可复现、图表要规范这些都可以写进 skills。先创建文件.claude/skills/math-modeling.md然后写元信息--- name: math-modeling description: 当用户需要编写数学建模竞赛相关代码时使用包括优化模型、评价模型、预测模型、图论模型等 ---正文部分我先写规范# 数学建模代码规范 ## 适用场景 - 数学建模竞赛代码编写 - 模型求解与结果可视化 - 论文图表生成 ## 核心规范 1. 所有代码必须可复现随机种子固定为 42 2. 数据读取路径使用相对路径禁止硬编码绝对路径 3. 求解结果必须保存为 CSV方便后续论文引用 4. 图表统一使用 matplotlib字体设为 SimHei字号 12 5. 每个模型单独一个 Python 文件文件名用模型名拼音然后给一个示例import numpy as np import pandas as pd import matplotlib.pyplot as plt np.random.seed(42) plt.rcParams[font.sans-serif] [SimHei] plt.rcParams[axes.unicode_minus] False def solve_optimization(): # 模型求解逻辑 result ... pd.DataFrame(result).to_csv(output/result.csv, indexFalse) return result最后写禁忌## 注意事项 - 不要使用 seaborn比赛环境可能没装 - 不要在循环里画图先存数据再统一画 - 不要用 print 输出结果统一写日志文件这个 skills 写完之后我在 Claude Code 里说“帮我写一个线性规划的求解代码”它就会自动加载这个 skills生成的代码直接符合比赛要求省去了大量手动调整的时间。4.3 安装社区 skills从 GitHub 拉取并本地化社区里有很多现成的 skills比如superpower skills、typesafe ai skills这些仓库质量参差不齐但好的确实能省事。安装方式很简单把仓库 clone 下来找到SKILL.md文件复制到你的 skills 目录。但直接复制往往不够因为社区 skills 是通用写的不一定符合你的习惯。我通常做三步本地化第一步改 description加上你常用的触发词。第二步删掉你用不上的部分比如社区 skills 可能支持多种框架你只用 React就把 Vue 相关的删掉。第三步把示例代码换成你自己项目的风格这样 AI 生成的东西才跟你的代码库一致。这个过程花不了多少时间但效果提升很明显。我见过有人直接拿社区 skills 用结果 AI 生成的代码风格跟项目完全不搭改起来比自己写还累。4.4 调试 skills怎么知道它有没有生效skills 写完怎么确认 AI 真的加载了有几个方法。最直接的是看 Claude Code 的输出。它在加载 skills 时会在日志里显示“Loaded skill: xxx”。如果你没看到这行说明没触发。另一个方法是故意在对话里提 skills 里的关键词。比如你的 skills 叫react-component-generator你就说“帮我生成一个 React 组件”看 AI 的回复是否符合 skills 里的规范。如果它用了 class 组件而你的 skills 里明确禁止 class那就说明没加载。如果确认没加载先检查文件路径对不对再检查 description 写得够不够具体。我遇到最多的情况是 description 太宽泛AI 判断不出来。把触发条件写细一点基本都能解决。4.5 版本管理与团队协作skills 也要进 Gitskills 文件应该跟代码一起进 Git 仓库。这样团队成员拉下来就能用新人入职也不用从头配。我建议在项目 README 里加一段说明告诉团队成员 skills 放在哪、怎么改、改完怎么测试。如果团队里有人用不同的 AI 工具skills 文件也可以共享。Claude Code 和 Codex 的 skills 格式基本兼容稍微调整一下元信息就能通用。这样团队的知识沉淀就不会绑死在某个工具上。5. 常见问题与排查技巧实录5.1 skills 不生效的五个常见原因问题现象可能原因排查方法AI 完全不加载 skills文件路径不对确认文件在.claude/skills/或~/.claude/skills/下该加载时不加载description 太宽泛把触发条件写具体加上任务类型关键词不该加载时乱加载description 关键词太泛删掉容易误触发的词加上排除场景加载了但不遵循规范写得太模糊把“要整洁”改成“函数不超过 50 行”改了文件不生效缓存没刷新重启 Claude Code或重新打开项目这张表是我自己踩坑总结出来的基本上覆盖了 90% 的问题。遇到 skills 不工作时按这个顺序排查很快就能定位。5.2 触发冲突多个 skills 同时被加载怎么办有时候一个任务会同时匹配多个 skills比如你说“帮我写一个带数据库查询的 React 组件”可能同时触发前端 skills 和数据库 skills。这时候 AI 会怎么处理实测下来它会尝试融合两个 skills 的规范但融合效果不一定好有时候会顾此失彼。我的做法是给 skills 加优先级。在元信息里加一个priority字段数值越大优先级越高。或者在 description 里写清楚“当同时涉及前端和数据库时以前端规范为准”。这样 AI 在冲突时就有明确的取舍依据。另一个做法是拆分任务。先让 AI 写组件再让它写数据库查询分两步走每次只触发一个 skills。虽然多一轮对话但结果更可控。5.3 上下文超限skills 写太长导致响应变慢skills 不是越长越好。我早期写过一个 800 行的 skills结果每次加载后 AI 的响应速度明显变慢而且经常抓不住重点。后来我把它拆成三个 200 行左右的 skills按场景分别触发效果好很多。经验值是单个 skills 控制在 300 行以内核心规范不超过 10 条示例代码不超过 50 行。如果内容确实多就拆成多个 skills用 description 区分触发场景。这样既保证了信息完整又不会拖慢响应。5.4 跨工具兼容Claude Code 和 Codex 的 skills 差异Claude Code 和 Codex 的 skills 格式大同小异主要差异在元信息字段。Claude Code 用name和descriptionCodex 可能用title和trigger。正文部分的 Markdown 结构基本通用。如果你需要在两个工具之间共享 skills最简单的办法是写一个转换脚本把元信息字段映射一下。或者干脆维护两份元信息正文共用。我自己的做法是正文写一份元信息用注释的方式写两套用哪个工具就取消对应的注释。5.5 独家避坑skills 里的代码示例不要用真实项目代码这是一个我踩过的坑。早期我图省事直接把项目里的真实代码复制到 skills 里当示例。结果 AI 学会了示例里的业务逻辑生成新代码时把不相关的业务逻辑也带进来了。比如示例里有一个用户认证的调用AI 在生成一个纯 UI 组件时也加上了认证代码完全没必要。正确的做法是示例代码要精简只保留跟 skills 规范相关的部分。业务逻辑用伪代码或者省略号代替。这样 AI 学到的是规范和风格而不是具体的业务实现。5.6 定期清理skills 库也需要维护skills 写多了难免有一些过时的、重复的、效果不好的。我建议每个月花十分钟过一遍 skills 目录做三件事删掉三个月没用过的合并功能重复的更新规范有变化的。保持 skills 库精简AI 的触发准确率也会更高。有个小技巧在 skills 文件名前加日期前缀比如2024-01-react-component.md这样一眼就能看出哪些是老的。清理的时候按日期排序老的自然就浮出来了。6. 进阶玩法让 skills 真正成为你的第二大脑6.1 skills 组合用一个大 skills 调度多个小 skills当你有了十几个 skills 之后可以写一个“调度型” skills专门用来组合其他 skills。比如一个“全栈开发”skillsdescription 写“当用户需要完成一个完整功能模块时使用”正文里列出“先加载前端 skills再加载后端 skills最后加载测试 skills”的流程。这样你只需要说“帮我做一个用户管理模块”AI 就会按顺序加载相关 skills一步步完成。这种组合玩法适合复杂任务能把多个 skills 的能力串起来。6.2 从 skills 到工作流把重复劳动彻底自动化skills 的终极形态是工作流。你可以把一系列操作写成一个 skills让 AI 按固定流程执行。比如“发布新版本”这个 skills里面写清楚先跑测试再更新版本号再生成 changelog再打 tag再推送。你只需要说“发布 1.2.0 版本”AI 就按流程走完。这比写脚本更灵活因为 AI 能处理意外情况。比如测试失败了它会停下来告诉你哪里错了而不是硬着头皮往下走。这种“半自动”的工作流在实际使用中比全自动脚本更实用。6.3 团队 skills 库让新人一天上手项目团队里最值钱的 skills 是“项目规范”类的。把代码风格、目录结构、提交规范、测试要求都写进 skills新人拉下代码AI 就自动按规范辅助他写代码。这比写一堆文档有效得多因为文档没人看skills 是 AI 主动执行的。我见过一个团队把 onboarding 流程写成了 skills新人第一天就能提交符合规范的代码review 成本大幅降低。这才是 skills 在团队场景下的真正价值。6.4 我个人的 skills 库现状与使用心得我现在维护着大概二十多个 skills分四类前端开发、后端开发、文档写作、通用工具。每天高频使用的有五六个其余按需触发。最大的体会是skills 的质量比数量重要得多。一个写得好的 skills能顶十个凑数的。另外skills 不是写完就完了要持续迭代。每次发现 AI 生成的代码有问题就想想是不是 skills 里没写清楚然后补上。这样用几个月下来你的 skills 库会越来越贴合你的实际需求AI 也会越来越“懂你”。最后分享一个小技巧把 skills 当成你跟 AI 的“合同”。你写清楚要求AI 按合同执行。合同越细执行越准。别指望 AI 猜你的心思把心思写进SKILL.md里这才是 skills 的正确用法。