1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了。但结合热搜词里的 Claude Code、Codex、agents、plugin 这些关键词方向就清晰了这里说的 skills指的是 AI 编程助手生态里的技能扩展机制也就是给 Claude Code、Codex 这类命令行 AI 代理挂载可复用的能力模块。打个比方AI 代理本身是个刚入职的聪明实习生通用能力强但不懂你们公司的具体业务。skills 就是你写给它的岗位操作手册——告诉它遇到某类任务时该调用什么工具、遵循什么流程、输出什么格式。它可以是几十行的 Markdown 说明也可以是一整套带脚本、模板、参考资料的目录结构。为什么这个概念突然火了因为大家发现光靠一个通用大模型解决不了实际问题。你让它写个符合团队规范的 React 组件它给你写出来的东西风格飘忽你让它处理数据库迁移它可能连你们用的 ORM 都不认识。skills 的价值就在于把隐性经验变成显性指令让 AI 的输出从能用变成符合预期。这篇文章适合三类人看一是刚接触 Claude Code 或 Codex、还在摸索怎么让它听话的新手二是已经用了一段时间、但每次都要重复交代背景的老用户三是想自己开发 skills、把团队工作流沉淀下来的进阶玩家。我会从概念讲到实操从安装配置讲到自定义开发把踩过的坑和验证过的方案都摊开说。需要先明确一点skills 不是某个厂商的专有名词不同工具叫法不同——Claude Code 里叫 Agent SkillsCodex 里可能叫别的但核心逻辑一致用结构化的文件描述扩展 AI 代理在特定场景下的行为。理解了这层后面具体工具的差异就好消化了。2. skills 的底层逻辑为什么一个 Markdown 文件能改变 AI 行为2.1 从提示词到技能包的进化早期大家用 AI 编程靠的是在对话里堆提示词。你是一个资深前端工程师请遵循 Airbnb 规范……这种开场白本质上是把上下文塞进单次对话。问题很明显每次新开对话都要重来一遍提示词越写越长模型注意力被稀释效果反而下降。skills 的思路完全不同。它把提示词从对话内容提升到系统配置层面。以 Claude Code 为例skills 存放在特定目录下每个 skill 是一个独立文件夹里面有SKILL.md作为入口可以附带脚本、模板、示例文件。当 AI 判断当前任务匹配某个 skill 的描述时会主动加载这个 skill 的完整内容把它作为执行依据。这个机制的关键在于按需加载。你不需要把所有规则一次性塞给模型而是让模型根据任务类型自己去翻手册。这就像公司不会让新员工背完所有 SOP而是告诉他遇到报销问题查财务手册第三章。2.2 skill 的文件结构长什么样一个标准的 skill 目录大概是这样my-skill/ ├── SKILL.md # 必需技能的主描述文件 ├── scripts/ # 可选辅助脚本 │ └── validate.py ├── templates/ # 可选输出模板 │ └── component.tsx └── references/ # 可选参考资料 └── api-spec.mdSKILL.md的核心是 YAML frontmatter 加正文。frontmatter 里最关键的是name和description两个字段--- name: react-component-generator description: 当用户需要创建符合团队规范的 React 函数组件时使用。包含命名约定、样式方案、测试模板。 --- # React 组件生成规范 ## 命名约定 - 组件文件使用 PascalCase - hooks 使用 camelCase 且以 use 开头 ...description字段是灵魂。AI 就是靠它来判断当前任务要不要用这个 skill。写得太窄该触发时不触发写得太宽不该触发时乱触发。这个度后面会专门讲。2.3 模型是怎么决定用哪个 skill 的这里涉及一个常被误解的点。很多人以为 skills 是关键词匹配其实不是。AI 代理在收到任务后会把所有可用 skill 的name和description作为上下文的一部分然后基于语义理解判断相关性。这意味着描述里写处理数据可能匹配到任何跟数据沾边的任务太泛描述里写当用户需要把 PostgreSQL 表结构导出为 Prisma schema 时使用就精准得多实测下来description 里包含触发场景什么时候用比包含功能列表能做什么更有效。因为模型判断的是当前情境是否符合而不是这个工具能力够不够。还有一个细节skill 的加载是有 token 成本的。如果一个 skill 正文写了五千字每次触发都要吃掉这些 token。所以好的 skill 讲究入口轻、按需深——SKILL.md只放核心指令详细参考资料放在references/里让模型需要时再去读。3. 在 Claude Code 里装 skills从零到跑通的完整路径3.1 环境准备里最容易卡住的两步Claude Code 的安装本身不复杂但国内环境有两个高频卡点。第一个是 Node 版本Claude Code 要求 Node 18 以上建议直接上 20 LTS。用node -v确认版本不对就用 nvm 切换nvm install 20 nvm use 20第二个是安装后的登录环节。npm install -g anthropic-ai/claude-code装完后第一次运行claude会引导你登录。如果你在 Windows 上遇到终端卡住或者报组织设置相关的错误先检查是不是用了不兼容的终端——实测 Windows Terminal 比老版 cmd 稳PowerShell 也可以但要注意执行策略。提示安装过程中如果提示权限问题Linux/macOS 下不要无脑sudo先检查 npm 全局目录的归属用npm config get prefix看看路径权限问题从根上解决比每次提权干净。3.2 skills 目录该放哪Claude Code 的 skills 有两个层级层级路径适用场景用户级~/.claude/skills/个人常用所有项目共享项目级项目根/.claude/skills/团队规范随代码库分发我的建议是通用能力比如代码审查、提交信息生成放用户级项目特有的比如这个项目的 API 约定、数据库 schema放项目级并提交到 git。这样新同事 clone 下来就自带技能不用口头交接。创建第一个 skill 最简单的方式是手动建目录mkdir -p ~/.claude/skills/my-first-skill touch ~/.claude/skills/my-first-skill/SKILL.md然后往SKILL.md里写内容。写完后重启 Claude Code用/skills之类的命令不同版本命令可能不同以实际为准查看是否被识别。3.3 验证 skill 是否生效的笨办法别指望装完就灵。验证一个 skill 有没有被正确加载和触发我常用两个办法第一个是直接问。在对话里问你现在有哪些可用的 skills模型会列出它看到的 skill 列表。如果列表里没有你刚建的说明路径错了或者格式有问题。第二个是构造触发场景。比如你建了个生成单元测试的 skill就故意说帮我给这个函数写测试看它的输出是否遵循了你 skill 里定义的规范比如用了你指定的测试框架、遵循了你的命名约定。如果输出还是老样子八成是 description 没写对模型没把它和当前任务关联起来。这里有个坑skill 的加载可能有缓存。改完SKILL.md后如果没生效试试重启 Claude Code 进程别在同一个会话里反复试。4. Codex 那边的 skills 玩法有什么不一样4.1 Codex 的定位差异决定了 skills 的用法差异Codex 和 Claude Code 虽然都是命令行 AI 代理但 Codex 更偏向在现有 IDE 和终端工作流里嵌入 AI 能力而 Claude Code 更像一个独立的代理环境。这个差异直接影响了 skills 的设计思路。在 Codex 里skills 往往和具体的开发动作绑定得更紧——比如代码补全、重构建议、测试生成。它的 skills 配置可能更依赖项目内的配置文件而不是全局目录。具体路径和格式随版本变化较大建议以你安装的那个版本的官方文档为准。4.2 接入本地模型时的 skills 注意事项热搜里有个词是claude code 调用 lmstudio 的本地模型这其实是个典型场景用本地模型跑 AI 代理省成本、保隐私。但本地模型的能力通常弱于云端大模型这时候 skills 的作用反而更大——因为你需要用更明确的指令来弥补模型理解力的不足。实测经验本地模型对 skill 的description语义匹配能力较差容易漏触发。对策是把 description 写得更关键词化同时把 skill 正文写得更结构化多用列表和明确的步骤编号少用长段落。模型越弱指令越要像操作手册而不是散文。4.3 跨工具复用 skill 内容的可行性一个好消息是skill 的核心是 Markdown 文本本质上是给 AI 看的文档。所以你在 Claude Code 里写好的 skill 内容稍作格式调整就能搬到 Codex 或其他支持类似机制的工具里。真正需要改的只是 frontmatter 的字段名和目录位置。我自己的做法是维护一个ai-skills仓库里面按主题分文件夹每个工具用软链接或者构建脚本把对应内容同步到各自的 skills 目录。这样一份经验多处复用不用维护多套。5. 自己写一个 skill从需求到落地的完整拆解5.1 先想清楚这个 skill 解决什么重复劳动写 skill 之前先问自己我是不是每次都要跟 AI 重复交代同一件事如果答案是肯定的那就值得写成 skill。常见的值得沉淀的场景代码风格规范命名、注释、目录结构特定框架的样板代码生成比如每次都要写一遍的 CRUD数据格式转换CSV 转 JSON、SQL 转 ORM 模型审查清单提交前要检查哪些项文档模板README、API 文档的固定结构反过来一次性的、高度依赖具体上下文的任务不值得写 skill。skill 的价值在于复用。5.2 description 的写法决定 skill 生死的一行字前面反复强调 description 重要这里给个可操作的写法模板description: 当[触发场景]时使用。这个 skill 会[做什么]输出[什么格式]。举个例子对比两种写法差的写法description: 帮助生成数据库迁移脚本。好的写法description: 当用户需要修改数据库表结构增删字段、改类型、加索引并生成迁移文件时使用。适用于 Prisma 和 TypeORM 项目输出符合项目命名规范的迁移脚本。好的写法明确了触发场景改表结构、适用范围Prisma/TypeORM、输出要求命名规范。模型一看就知道什么时候该翻这本手册。5.3 正文结构把 AI 当成一个需要明确指令的新人skill 正文不要写成散文。我推荐的结构是一句话概述这个 skill 干什么前置条件执行前需要确认什么步骤清单编号的、可执行的操作序列输出格式明确要求输出长什么样最好给示例常见错误明确列出要避免的做法给个真实例子一个生成 API 接口文档的 skill 正文片段## 输出格式 每个接口按以下结构输出 ### [HTTP方法] [路径] - **描述**一句话说明 - **请求参数** | 参数名 | 类型 | 必填 | 说明 | - **响应示例**JSON 代码块 - **错误码**列表 ## 禁止事项 - 不要省略错误码说明 - 不要用等等、其他这类模糊表述 - 参数类型必须用具体类型不要写对象了事这种写法模型执行起来偏差小因为每一步都有明确约束。5.4 用脚本增强 skill 的能力边界纯文本 skill 能解决怎么说的问题但解决不了怎么做的问题。比如你要校验生成的 JSON 是否符合 schema光靠指令模型可能偷懒。这时候可以在 skill 里挂脚本# scripts/validate_schema.py import json, sys from jsonschema import validate with open(sys.argv[1]) as f: data json.load(f) with open(schema.json) as f: schema json.load(f) validate(data, schema) print(校验通过)然后在SKILL.md里写生成后运行python scripts/validate_schema.py output.json校验。这样就把确定性的检查交给了代码模型只负责生成各司其职。6. 实测中踩过的坑和对应的解法6.1 skill 不触发九成是 description 的问题这是最高频的问题。表现是明明建了 skillAI 就是不用。排查顺序确认 skill 目录路径正确文件名大小写对Linux 下大小写敏感确认SKILL.md的 frontmatter 格式正确---不能少检查 description 是否太泛或太窄重启 Claude Code 清缓存我遇到过一次折腾半天发现是 frontmatter 里name字段用了中文改成英文就好了。这种细节文档里不一定写但实际会卡人。6.2 skill 触发太频繁描述写宽了的后果反过来如果 description 写得太宽比如处理任何代码相关任务那模型几乎每个任务都会加载它既浪费 token 又可能干扰判断。解法是把 description 收窄到具体场景宁可多建几个精准的 skill也不要一个万能 skill。6.3 多个 skill 冲突时怎么办当两个 skill 的适用范围有重叠模型可能同时加载导致指令打架。比如一个 skill 说注释用中文另一个说注释用英文。这种情况要么合并成一个 skill 用条件分支处理要么在 description 里明确互斥条件。实测下来skill 之间职责边界清晰比数量多更重要。6.4 版本升级后 skill 失效AI 工具迭代快目录结构、frontmatter 字段、加载机制都可能变。我的习惯是每次升级 Claude Code 或 Codex 后跑一遍核心 skill 的验证流程确认还能用。同时把 skill 仓库用 git 管理出问题能回滚。7. 把 skills 用出复利团队协作与持续迭代7.1 让 skill 成为团队知识资产个人用 skill 是提效团队用 skill 是沉淀。把项目级 skill 提交到代码库配合 README 说明每个 skill 的用途新成员上手时 AI 就已经懂规矩了。这比写一堆没人看的 wiki 有效得多因为 skill 是活的——AI 每次执行都在实践这些规范。7.2 用真实任务反哺 skillskill 不是写完就完事。每次 AI 输出不符合预期都是一次改进机会。我的做法是遇到问题先别急着改提示词想想这个要求是不是应该写进 skill。如果是通用要求就更新 skill如果是一次性的就留在对话里。这样 skill 会随着使用越来越贴合实际需求。7.3 定期清理过时的 skill跟代码一样skill 也会腐化。项目换了框架、规范改了对应的 skill 如果没更新反而会误导 AI。建议每隔一两个月过一遍 skill 列表删掉不再用的更新变了规则的。数量不在多在于每个都准。7.4 一个关于度的经验最后分享一个我摸索出来的度skill 不要写太满。留一些判断空间给模型比事无巨细地规定每一步效果更好。因为真实任务千变万化写死的流程遇到边界情况就僵住了。好的 skill 是给方向和约束而不是给死步骤。这个度需要根据任务类型调——越是确定性的任务比如格式转换越可以写死越是创造性的任务比如架构设计越要留白。我在实际使用中最大的体会是skills 这套机制真正的价值不在于让 AI 变聪明而在于让 AI 变可控。它把人和 AI 的协作从每次重新沟通变成一次约定、长期执行。这个转变带来的效率提升远比单次对话优化来得实在。至于具体用哪个工具、skill 怎么写都是在这个大方向下的细节选择多试几次自然就有手感了。