1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你如果只看字面意思可能会以为是某种技能培训或者职场能力清单但在当前的技术语境下它指的是一套围绕 AI 编程助手构建的可插拔能力模块——尤其是和 Claude Code、Codex 这类终端里的 AI 编程工具配合使用时skills 就是让这些工具从“能聊天”变成“能干活”的关键拼图。我最早接触这个概念是在折腾 Claude Code 的时候。当时我发现一个很尴尬的事Claude Code 本身能理解代码、能改文件、能跑命令但每次遇到稍微偏门一点的任务比如“帮我把这个 Flutter 项目的 Gradle 插件配置从命令式改成声明式”它就开始泛泛而谈给出来的建议看着对但落不了地。后来我才知道问题不在于模型不够聪明而在于它缺少针对特定场景的结构化操作知识。skills 就是用来补这块的。简单来说一个 skill 就是一份写给 AI 看的“操作手册”。它通常包含几个部分这个 skill 是干什么的、什么时候该用它、具体怎么操作、有哪些坑不能踩。你可以把它理解成给 AI 助手准备的一份 SOP标准作业流程只不过这份 SOP 是用自然语言写的而且 AI 能直接读懂并执行。那为什么 skills 突然火起来了我觉得有三个原因。第一Claude Code 和 Codex 这类工具把 AI 编程从“网页对话框”拉到了“真实终端环境”AI 能直接操作文件系统和命令行能力边界一下子打开了但随之而来的问题是它不知道你的项目里有哪些约定、哪些工具链、哪些历史包袱skills 正好补上这块。第二社区开始自发贡献 skills形成了一个类似“插件市场”的生态你不需要自己从零写找到别人写好的直接装就行。第三skills 的格式足够简单基本上就是 Markdown 加一些约定俗成的元数据学习成本极低前端、后端、移动端、运维都能写自己领域的 skill。这篇文章我会从实际使用的角度出发把 skills 的来龙去脉、安装配置、编写方法、常见坑点全部拆开讲一遍。不管你是刚听说 Claude Code 想试试还是已经在用 Codex 但觉得不够顺手或者想自己写一个 skill 解决团队里的重复劳动下面这些内容应该都能帮到你。2. skills 的核心机制与生态全景2.1 skill 的本质给 AI 的一份结构化操作手册很多人第一次看到 skill 文件的时候会有点懵因为它看起来就是一篇普通的 Markdown 文档。确实从文件格式上说一个 skill 通常就是一个目录里面放一个SKILL.md或者类似命名的文件再加上一些辅助脚本、模板、配置文件。但它的核心不在于格式而在于约定。这个约定包含几层意思。第一层是触发条件skill 文件里会写明“当用户提到 X 或者当前项目包含 Y 的时候你应该加载这个 skill”。这相当于给 AI 一个路由规则让它知道什么场景下该翻哪本手册。第二层是操作步骤具体怎么做分几步每步用什么命令、改哪个文件、注意什么。第三层是验证方式做完之后怎么确认是对的比如跑哪个测试、看哪个输出。第四层是边界和禁忌什么情况下不要用这个 skill或者用了之后不能做什么。我拿一个实际例子来说明。假设你团队里有一个 skill 叫flutter-gradle-migration它的内容大概是这样组织的--- name: flutter-gradle-migration description: 将 Flutter 项目的 Android Gradle 插件从命令式 apply 迁移到声明式 plugins 块 trigger: 当项目包含 android/build.gradle 且出现 apply plugin 字样时 --- ## 操作步骤 1. 打开 android/settings.gradle在 pluginManagement 块中确认 Gradle 版本 7.0 2. 打开 android/build.gradle找到所有 apply plugin: xxx 的行 3. 将 com.android.application 和 kotlin-android 迁移到 plugins 块 4. 保留其他第三方插件在 apply plugin 形式除非确认支持声明式 5. 运行 flutter clean flutter build apk --debug 验证 ## 注意事项 - Flutter 的 gradle 插件版本必须和 AGP 版本匹配否则会报 You are applying Flutters main Gradle plugin imperatively 错误 - 迁移后如果出现 in order to access this application, you must install the J2SE plugin version 说明 JDK 版本不对你看这就是一份典型的 skill。它不写代码逻辑它写的是操作意图和判断依据。AI 读到这份文件之后就知道遇到 Flutter Gradle 迁移任务时该怎么一步步做而不是瞎猜。2.2 Claude Code、Codex 与 skills 的关系Claude Code 和 Codex 是两个不同团队做的终端 AI 编程工具但它们在 skills 这件事上的思路是相通的。Claude Code 原生支持 skills 机制你可以在项目根目录放一个.claude/skills/文件夹里面按 skill 名字建子目录每个子目录放一个SKILL.md。Claude Code 在启动时会扫描这个目录把可用的 skills 列出来然后在对话过程中根据上下文决定是否加载某个 skill 的详细内容。Codex 这边稍微不一样。Codex 本身是一个更偏“代码生成”的工具它的 skills 支持更多是通过插件或者外部配置文件来实现的。社区里有人做了codex skills的适配层把 Claude Code 格式的 skill 转换成 Codex 能识别的形式。也有直接在AGENTS.md或者项目级配置文件里写操作指南的做法效果类似但没那么结构化。这里要提一个容易混淆的点skills 和 agents 不是一回事。agents 通常指的是一个能自主决策、多步执行的智能体它有自己的循环逻辑和工具调用能力。skills 更像是 agents 可以调用的“知识包”或者“技能卡”。一个 agent 可以加载多个 skills根据任务不同切换使用。你可以把 agent 理解成厨师skills 理解成菜谱厨师做菜的时候翻不同的菜谱。2.3 社区生态从官方市场到个人贡献目前 skills 的获取渠道主要有几个。一是官方或者半官方的市场比如 Claude 那边有一个 skills 仓库里面放了一些官方维护的 skill覆盖常见的开发场景。二是社区贡献GitHub 上有很多个人或者团队开源的 skills 集合质量参差不齐但数量增长很快。三是自己写这也是最推荐的方式因为只有你自己最清楚团队里的痛点和约定。我自己的做法是先从社区找几个高频场景的 skill 用起来感受一下它的工作方式然后针对自己项目里反复出现的操作写定制 skill。比如我们团队经常需要把某个服务从旧版配置迁移到新版每次都要翻文档、对参数、跑验证后来我写了一个 skill 把整个流程固化下来新来的同事只要触发这个 skillAI 就会带着他一步步做出错率明显下降。3. 安装与配置把 skills 跑起来3.1 Claude Code 的安装与 skills 目录结构如果你还没装 Claude Code第一步是把它装到本地。Claude Code 是一个命令行工具安装方式取决于你的操作系统。在 macOS 或者 Linux 上通常可以通过包管理器或者官方提供的安装脚本搞定。Windows 用户建议用 WSL2 环境因为 Claude Code 对 Unix 风格的文件路径和命令支持更好直接在 PowerShell 里跑虽然也能用但偶尔会遇到路径分隔符和权限相关的小问题。安装完成之后你需要在项目里初始化 skills 目录。标准做法是在项目根目录创建.claude/skills/然后在里面为每个 skill 建一个子目录。比如mkdir -p .claude/skills/my-first-skill touch .claude/skills/my-first-skill/SKILL.mdSKILL.md的文件名是约定俗成的Claude Code 会优先找这个文件。有些实现也支持skill.md小写但为了兼容性建议用大写。文件内容用 Markdown 写开头可以用 YAML front matter 放元数据比如 name、description、trigger 这些字段。不过即使你不写 front matterClaude Code 也能通过文件名和内容推断出 skill 的用途只是明确写出来会更可靠。注意skills 目录的位置很关键。放在项目根目录下的.claude/skills/只对当前项目生效如果你想让某个 skill 在所有项目里都能用需要放到用户主目录下的.claude/skills/。我建议通用型 skill 放全局项目特定的放项目内避免污染。3.2 Codex 的 skills 适配方式Codex 的安装相对直接官方提供了安装包和命令行工具。装好之后Codex 的 skills 支持不像 Claude Code 那样有固定的目录约定更多是通过项目级的AGENTS.md或者.codex/配置目录来实现。社区里有一个比较流行的做法是在项目根目录放一个skills/文件夹然后在AGENTS.md里写明“当需要执行 X 操作时参考 skills/xxx.md”。这种方式的好处是灵活坏处是没有统一标准不同项目的组织方式可能不一样。如果你同时用 Claude Code 和 Codex可以考虑维护一份 skill 源文件然后用脚本或者手动方式同步到两边的目录结构里。我试过写一个简单的 shell 脚本把.claude/skills/下的内容软链接到 Codex 能识别的位置省得维护两份。另外提一下Codex 在接入本地模型或者第三方模型时有时候会遇到 endpoint 配置问题比如报cc switch local proxy failed while handling codex endpoint /responses这类错误。这通常是因为代理配置或者 base URL 写错了检查一下配置文件里的 endpoint 地址和 API key 是否正确以及本地服务是否真的在监听那个端口。3.3 验证 skills 是否生效装好之后怎么确认 skill 能被正确加载最直接的办法是在 Claude Code 或者 Codex 的对话里问一句“你现在有哪些可用的 skills”如果配置正确它应该能列出你放在目录里的 skill 名称和描述。如果什么都没列出来检查几个点目录路径对不对、文件权限是否可读、front matter 格式有没有语法错误。还有一个验证方法是触发一个 skill。比如你写了一个处理 Git 提交信息的 skill那就让 AI 帮你生成一条提交信息看它是否按照 skill 里定义的格式来输出。如果它还是按默认方式回答说明 skill 没被加载或者触发条件没匹配上。我踩过的一个坑是skill 文件里写了中文描述但触发关键词用的是英文结果 AI 在中文对话里没匹配到。后来我把触发条件写成中英双语问题就解决了。所以写 skill 的时候触发词尽量覆盖用户可能用的各种表达方式。4. 自己动手写一个 skill从需求到落地4.1 找准场景什么样的任务值得写成 skill不是所有事情都值得写成 skill。我的判断标准是重复出现、步骤固定、容易出错、有明确验证方式的任务才值得。比如“每次新建一个 React 组件都要建三个文件、改两个配置、跑一次 lint”这种事就非常适合写成 skill。而“帮我设计一个分布式架构”这种开放性问题写 skill 反而限制 AI 的发挥。具体来说以下几类场景特别适合项目初始化新建服务、新建模块、新建页面时的一系列固定操作代码迁移从旧框架迁到新框架、从旧配置迁到新配置规范检查提交前检查、发布前检查、代码风格统一故障排查某类报错的标准排查流程环境配置本地开发环境搭建、依赖安装、工具链配置拿“安卓脱壳”这个热词来说虽然它本身涉及的技术比较特殊但如果你的团队有固定的分析流程完全可以写成一个 skill把每一步用什么工具、看什么输出、怎么判断结果都固化下来。这样即使新人也能按照标准流程操作减少遗漏。4.2 skill 文件的结构与写法一个高质量的 skill 文件通常包含以下几个部分我按推荐顺序列出来元数据区用 YAML front matter 写 name、description、trigger、version 这些字段。name 用短横线分隔的小写英文description 一句话说清楚这个 skill 干什么trigger 写清楚什么条件下加载。适用场景展开说明这个 skill 解决什么问题什么情况下用什么情况下不用。这部分是给 AI 看的也是给维护 skill 的人看的。前置条件执行这个 skill 之前需要满足什么条件比如需要安装某个工具、需要某个文件存在、需要某个环境变量设置好。操作步骤这是核心部分。每一步写清楚做什么、用什么命令、改哪个文件、预期结果是什么。步骤要足够具体让 AI 能直接执行而不是还要猜。验证方法做完之后怎么确认成功。比如跑哪个测试命令、看哪个输出、检查哪个文件。常见问题这一步容易出什么错出了错怎么排查。这部分是经验沉淀也是 skill 最有价值的地方之一。回滚方案如果操作失败或者结果不对怎么恢复到之前的状态。我写 skill 的时候有一个习惯把操作步骤写成“如果...就...”的形式而不是平铺直叙。因为实际执行过程中经常遇到分支情况提前把分支写清楚AI 处理起来更稳。比如“如果 Gradle 版本低于 7.0先升级 Gradle如果已经是 7.0 以上直接进入下一步”。4.3 一个完整示例前端项目初始化 skill下面这个 skill 是我为一个前端项目写的初始化流程你可以参考这个结构来写自己的。--- name: frontend-project-init description: 初始化一个基于 Vite React TypeScript 的前端项目 trigger: 当用户要求新建前端项目且提到 Vite、React、TypeScript 时 version: 1.0 --- ## 适用场景 新建一个标准的前端项目包含路由、状态管理、请求库、代码规范工具。 ## 前置条件 - Node.js 18 - pnpm 已安装如果没有先运行 npm install -g pnpm ## 操作步骤 1. 运行 pnpm create vitelatest my-app --template react-ts 2. 进入目录运行 pnpm install 3. 安装路由pnpm add react-router-dom 4. 安装状态管理pnpm add zustand 5. 安装请求库pnpm add axios 6. 安装代码规范pnpm add -D eslint prettier eslint-config-prettier 7. 在 src 下创建 router、store、api、components 四个目录 8. 修改 vite.config.ts配置路径别名 指向 src 9. 修改 tsconfig.json添加 paths 配置 10. 运行 pnpm dev 验证项目能启动 ## 验证方法 - 浏览器打开 localhost:5173 能看到 Vite 默认页面 - 运行 pnpm lint 没有报错 ## 常见问题 - 如果 pnpm create 卡住检查网络或者换 npm 试试 - 如果路径别名不生效检查 vite.config.ts 和 tsconfig.json 是否都配了 - 如果 eslint 报解析错误检查是否安装了 typescript-eslint/parser ## 回滚方案 直接删除项目目录重新执行。这个 skill 写完之后我让团队里新来的实习生试了一下他只需要对 AI 说“帮我新建一个前端项目”AI 就会按照这个流程一步步执行中间遇到问题还会根据“常见问题”部分给出排查建议。效率提升很明显而且不会漏掉配置项。4.4 让 skill 更聪明的几个技巧写 skill 不是写完就完了有几个技巧可以让它更好用。第一用条件分支代替线性步骤。实际执行时经常遇到“如果 A 存在就做 X否则做 Y”的情况提前写好分支AI 就不用临时判断。第二把验证命令写具体。不要写“验证项目能跑”要写“运行 pnpm dev看到 Local: http://localhost:5173 即成功”。第三把常见错误和解决方案配对写。AI 遇到报错时如果能直接在 skill 里找到对应解法处理速度会快很多。第四定期更新。项目依赖升级、工具链变化之后skill 里的命令可能过时建议每个季度 review 一次。还有一个进阶玩法skill 嵌套。你可以在一个 skill 里引用另一个 skill比如“初始化项目”的 skill 里可以调用“配置代码规范”的 skill。这样可以把通用逻辑抽出来复用避免每个 skill 都重复写一遍。5. 实战中的坑与排查技巧5.1 安装阶段的典型问题安装 Claude Code 或者 Codex 的时候最常见的问题集中在环境依赖和网络配置上。Claude Code 依赖 Node.js 运行时如果版本太低会直接报错。我建议用 nvm 或者 fnm 管理 Node 版本确保在 18 以上。Windows 用户如果遇到qt.qpa.plugin: could not find the Qt platform plugin windows这类错误通常是因为某些 GUI 依赖没装全换到 WSL2 里跑基本能解决。Codex 安装时如果遇到下载失败检查一下安装包的来源是否可靠以及本地是否有安全软件拦截。有些公司网络环境会限制外部下载这种情况需要联系 IT 开通白名单或者使用内部镜像源。还有一个高频问题是登录和订阅。Claude Code 需要账号登录如果提示your organization has disabled claude subscription access for claude code说明你的账号所属组织关闭了相关权限需要联系管理员开通或者换个人账号。Codex 登录时如果一直转圈检查一下系统时间是否准确时间偏差太大会导致认证失败。5.2 skill 不生效的排查思路skill 写了但 AI 不用这是最让人头疼的问题。我总结了一个排查顺序排查项检查方法常见原因目录位置确认.claude/skills/在项目根目录放错层级比如放到了 src 下面文件命名确认是SKILL.md不是skill.md或SKILL.txt大小写或扩展名不对文件权限ls -la看是否可读权限设置过严front matter用 YAML 校验工具检查缩进错误、冒号后没空格触发条件手动用触发词问 AI触发词写得太窄或太偏缓存问题重启 Claude Code启动时没扫描到新文件我遇到过一次 skill 不生效排查了半天发现是 front matter 里 description 字段用了中文冒号YAML 解析失败导致整个文件被跳过。改成英文冒号之后立刻正常了。所以写 YAML 的时候一定要注意标点符号。5.3 多工具共存时的配置冲突如果你同时用 Claude Code、Codex、Cursor 这些工具可能会遇到配置冲突。比如 Cursor 默认打开的是 agents 面板而不是编辑器你想改成默认打开编辑器需要在设置里调整启动行为。Claude Code 和 Codex 如果都配了本地模型代理端口可能冲突需要错开端口号。我的做法是给每个工具分配独立的配置目录和端口范围。Claude Code 用一套配置Codex 用另一套互不干扰。如果共用同一个模型服务确保服务端能处理并发请求否则会出现一个工具在跑另一个工具卡住的情况。另外VS Code 里装 Claude Code 插件之后有时候会出现插件和命令行版本行为不一致的问题。建议统一用命令行版本插件只作为辅助。如果插件报错先禁用插件用命令行验证功能是否正常再决定要不要继续用插件。5.4 性能与成本控制skills 本身不直接产生费用但它会影响 AI 的 token 消耗。一个写得很长的 skill 被加载时会占用上下文窗口导致可用于实际任务的 token 变少。所以 skill 要写得精炼把最关键的信息放进去不要什么都往里塞。我的经验是单个 skill 文件控制在 200 行以内超过的话考虑拆成多个 skill 或者把详细内容放到外部文档里skill 里只放引用。另外不是所有 skill 都需要在每次对话时加载利用好触发条件让 AI 只在相关场景下加载对应的 skill能有效控制 token 消耗。如果你用的是按量计费的模型服务建议定期看一下 skill 加载带来的额外消耗。有些 skill 可能一个月都用不上一次却每次启动都被扫描这种可以考虑归档或者移到全局目录之外。6. 关于 skills 生态的一些个人观察我用 skills 这套机制大概有几个月了最大的感受是它把“AI 编程”从“碰运气”变成了“可复现”。以前让 AI 帮忙做一件事结果好不好很大程度上取决于 prompt 写得好不好、模型当天状态怎么样。现在有了 skill相当于把最佳实践固化下来每次执行都走同一条路径稳定性提升非常明显。另一个观察是skills 正在从“个人玩具”变成“团队资产”。我认识几个团队已经开始把 skill 纳入代码仓库管理跟代码一起 review、一起版本控制。新成员入职第一件事就是拉取项目里的 skills让 AI 带着他熟悉项目结构和操作流程。这种用法我觉得会越来越普遍。当然skills 也不是银弹。它解决的是“已知问题”的标准化执行对于“未知问题”的探索还是得靠人的判断和 AI 的通用能力。所以我的建议是把重复劳动交给 skill把创造性工作留给自己。这样既能享受效率提升又不会让自己变成只会按按钮的操作员。如果你还没试过 skills建议从一个小场景开始比如把“每次提交代码前要跑的检查”写成一个 skill。写完之后你会发现原来那些琐碎的、容易忘的步骤现在 AI 都会提醒你、帮你执行。这种体验一旦习惯了就回不去了。