1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个招聘网站上的技能标签或者是一份简历里的能力清单。但结合热搜词里反复出现的 Claude Code、Codex、agents、plugin 这些词就能判断出这里说的 skills 不是泛指“技能”而是特指 AI 编程助手生态里的Agent Skills——一种把可复用的操作流程、领域知识、工具调用方式打包成模块让 AI 代理在特定任务上表现更稳定的机制。简单说skills 就是给 AI 代理准备的“操作手册 工具箱”。你告诉它遇到某类任务时该按什么步骤走、该调用哪些工具、该注意哪些边界条件它就能从“什么都能聊两句但什么都不精”变成“在这个具体场景里靠谱得像个老手”。这解决了大模型在实际工程中最大的痛点通用能力很强但落到具体项目、具体框架、具体规范上经常答非所问、步骤跳步、参数写错。这篇文章适合几类人看一是已经在用 Claude Code 或 Codex 做日常开发想进一步提升效率的工程师二是正在搭建内部 AI 代理平台需要设计 skills 体系的技术负责人三是对 agent 生态感兴趣想搞清楚 skills、plugin、agents 之间关系的技术爱好者。我会从设计思路、核心细节、实操过程、常见问题四个维度展开尽量把每个“为什么”讲透让你看完能直接上手复现。2. 内容整体设计与思路拆解2.1 为什么是 skills而不是 prompt 或 plugin很多人第一反应是我直接写一段 system prompt 不就行了为什么要搞 skills 这么一层这个问题我在实际项目里被问过不下十次。答案在于复用粒度和触发时机。Prompt 是每次对话都要重新注入的写长了占上下文写短了覆盖不全而且它和具体任务绑定太松——你没法让 AI 在“写 React 组件”和“排查 Gradle 构建失败”这两个场景下自动切换到不同的 prompt。Plugin 则是更底层的扩展通常涉及进程、网络、文件系统权限开发和维护成本高适合做通用能力比如读文件、跑命令但不适合承载“我们团队 React 组件必须用 function component hooks样式用 CSS Modules测试用 Vitest”这种业务规范。Skills 正好卡在中间它比 prompt 结构化比 plugin 轻量。一个 skill 通常包含元信息名称、描述、触发条件、指令正文步骤、约束、示例、可选资源脚本、模板、参考文档。AI 代理在运行时根据当前任务匹配 skill 描述命中后把指令正文加载进上下文任务结束就释放。这样既保证了专业性又不会长期占用上下文窗口。2.2 三种主流形态Claude Code Skills、Codex Skills、通用 Agent Skills从热搜词看大家关注的主要是三类。Claude Code 的 skills 体系比较成熟官方市场里有大量现成 skill 可以直接装也支持本地自定义。Codex 这边的 skills 更偏向于和代码仓库结合强调在具体项目里沉淀可复用的操作流程。通用 Agent Skills 则是一个更抽象的概念LangChain Deep Agents 这类框架也在推类似的机制核心思想都是“把领域知识从模型权重里解耦出来变成可版本管理的资产”。我个人的选型建议是如果你主力用 Claude Code优先走官方 skill 市场 本地覆盖的方式上手最快如果你团队用 Codex 做代码审查和重构建议把 skills 和仓库的 CONTRIBUTING.md 放在一起维护让规范和 skill 同步更新如果你在自研 agent 平台参考 Claude Agent Skills 的第一性原理设计——描述匹配、按需加载、资源隔离——这三条是绕不开的。2.3 一个 skill 的目录结构长什么样以 Claude Code 的 skill 为例典型结构是这样的my-skill/ SKILL.md # 必需元信息 指令正文 scripts/ # 可选辅助脚本 setup.sh references/ # 可选参考文档 api-spec.md assets/ # 可选模板、配置片段 template.tsxSKILL.md 的头部是 YAML frontmatter至少包含 name 和 description。description 非常关键它决定了这个 skill 什么时候被触发。写得太宽泛比如“帮助写代码”那几乎每个任务都会命中反而干扰写得太窄又可能永远匹配不上。我的经验是 description 里要包含动作 对象 场景三要素比如“当用户需要在 React 项目里新增一个表单组件且项目使用 React Hook Form 做校验时按本 skill 的步骤生成代码”。3. 核心细节解析与实操要点3.1 SKILL.md 的写法把“老手直觉”翻译成步骤写 skill 最难的地方不是技术而是把你脑子里那些“不用说也知道”的直觉显式化。比如一个资深前端在新建组件时会自动做这几件事确认目录结构、检查是否已有类似组件、选样式方案、写类型定义、补测试、更新导出索引。这些对你来说是肌肉记忆但对 AI 来说必须一条条写出来。我通常按这个模板来组织指令正文前置检查动手前先确认哪些条件。比如“先读 package.json确认 react-hook-form 版本是否 7”。执行步骤编号列出每步说明输入、输出、使用的工具。比如“用 Read 工具读取 src/components 目录列出已有组件名”。约束与禁忌明确不能做什么。比如“不要新建 index.ts 以外的导出文件”“不要用 any 类型”。示例给一个最小可运行示例让 AI 有参照。验证方式怎么确认做对了。比如“运行 pnpm test src/components/NewForm.test.tsx全部通过才算完成”。注意步骤不要写得太抽象。“合理组织代码”这种话等于没说“在 src/components/ 下新建 PascalCase 命名的目录目录内放 index.tsx 和 index.test.tsx”才是可执行的。3.2 description 的匹配逻辑与调优不同平台的匹配机制略有差异但大体上都是把用户当前请求和 skill 的 description 做语义相似度比较超过阈值就加载。Claude Code 还会考虑 skill 的优先级和互斥关系。实测下来description 里堆关键词效果并不好反而是一句自然语言描述匹配得更准。我踩过的一个坑是早期我把 description 写成“React 组件开发”结果连“帮我看看这个 React 报错”也会触发加载了一堆用不上的步骤浪费上下文。后来改成“在已有 React 项目中新增一个使用 React Hook Form 的表单组件”误触发率明显下降。另一个技巧是给 skill 加when_to_use字段如果平台支持用更口语化的例子补充说明比如“当用户说‘加个登录表单’‘新建一个注册页’时使用”。3.3 资源文件的组织脚本、模板、参考文档怎么放scripts 目录适合放那些确定性高、不需要 AI 推理的操作。比如初始化目录结构、生成样板代码、跑 lint 修复。把这些写成 shell 或 node 脚本skill 正文里直接让 AI 调用比让 AI 一步步敲命令更稳。references 目录放的是“查阅型”内容比如内部 API 规范、设计系统 token 列表、常见错误码对照表。这些内容通常很长不适合全量塞进上下文而是让 AI 在需要时用 Read 工具按需读取。assets 目录放模板文件比如组件模板、测试模板、配置文件模板AI 可以直接复制修改。提示资源文件命名要见名知意避免file1.md、temp.tsx这种。AI 在匹配资源时也会参考文件名好的命名能提升加载准确率。3.4 版本管理与团队协作Skills 是资产资产就要版本管理。我建议把团队共用的 skills 放在独立仓库通过 submodule 或包管理工具引入到各个项目。每次修改 skill 都要走 PR 流程因为一个错误的步骤可能影响所有使用该 skill 的成员。Claude Code 官方市场的 skill 可以 fork 到内部仓库再改不要直接依赖线上版本否则上游更新可能引入不兼容变更。另外skill 的 description 和正文要同步更新。我见过有人改了步骤但忘了改 description结果触发条件还是旧的新步骤永远加载不到。建议在 CI 里加一个检查如果 SKILL.md 的正文有变更description 也必须变更否则告警。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex 的安装配置先讲 Claude Code 的安装。Windows 用户建议用 WSL2原生 Windows 下路径和权限问题比较多。安装方式按官方文档走即可装完后用claude --version确认。国内网络环境下如果遇到登录或市场加载问题优先检查系统代理设置是否影响了 CLI 工具必要时在终端里单独配置。VS Code 用户装 Claude Code 扩展后可以在设置里指定 CLI 路径避免扩展找不到命令。Codex 的安装类似但 Codex 更依赖项目本地的配置文件。装完后在项目根目录建.codex/目录skills 放在.codex/skills/下。Codex 登录后如果提示“无法加载组织设置”通常是配置文件里的 org 字段和实际账号不匹配检查~/.codex/config.json即可。注意安装过程中如果遇到qt.qpa.plugin: could not find the qt platform plugin windows这类报错说明某个 GUI 依赖缺失和 skills 本身无关装对应的运行库即可。不要在这个问题上浪费太多时间。4.2 从零写一个“新增 React 表单组件”skill假设我们要写一个 skill让 AI 在指定项目里新增表单组件。第一步建目录mkdir -p .claude/skills/new-form-component/{scripts,references,assets}第二步写 SKILL.md--- name: new-form-component description: 当用户需要在 React 项目里新增一个使用 React Hook Form 做校验的表单组件时使用 --- ## 前置检查 1. 读取 package.json确认 react-hook-form 版本 7.0.0 2. 读取 src/components 目录确认没有同名组件 ## 执行步骤 1. 在 src/components/ 下新建 PascalCase 目录名称为组件名 2. 复制 assets/FormTemplate.tsx 到该目录重命名为 index.tsx 3. 替换模板中的 __COMPONENT_NAME__ 为实际组件名 4. 复制 assets/FormTestTemplate.tsx 为 index.test.tsx同样替换占位符 5. 在 src/components/index.ts 中追加导出 ## 约束 - 不要使用 any 类型 - 样式统一用 CSS Modules文件名 index.module.css - 测试用 Vitest Testing Library ## 验证 运行 pnpm test src/components/组件名全部通过第三步准备模板文件。FormTemplate.tsx 里用__COMPONENT_NAME__占位AI 替换后即可使用。模板要尽量完整包含 imports、类型定义、组件主体、导出减少 AI 自由发挥的空间。4.3 测试 skill 是否生效写完 skill 后在 Claude Code 里输入“帮我加一个登录表单组件”观察它是否加载了 new-form-component。如果没加载检查 description 是否匹配、skill 目录是否在正确位置、SKILL.md 的 frontmatter 格式是否正确。如果加载了但步骤没执行检查正文里的工具调用是否被平台支持比如某些平台不支持直接跑 shell 脚本需要改成让 AI 用 Bash 工具执行。我一般会准备一组测试用例正向用例明确匹配、负向用例不该匹配的、边界用例模糊描述。每次改完 skill 都跑一遍确保触发行为符合预期。这个习惯帮我避免了好几次“改了 A 场景结果 B 场景挂了”的事故。4.4 参数计算与选择上下文预算怎么分配Skills 会占用上下文窗口所以要有预算意识。一个 skill 的正文建议控制在 500 到 1500 字超过 2000 字就要考虑拆分或把细节移到 references 里按需加载。假设模型上下文是 200K token系统提示和对话历史占 50K那 skills 总占用最好不超过 30K留足空间给代码和工具输出。如果同时命中多个 skill平台通常会按优先级排序加载。我的做法是给核心 skill 设高优先级辅助 skill 设低优先级并在 description 里写清楚互斥关系比如“本 skill 与 legacy-form-skill 互斥优先使用本 skill”。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发这是最高频的问题。排查顺序如下先看 description 是否包含用户请求里的核心词再看 skill 目录层级是否正确Claude Code 要求放在.claude/skills/下Codex 要求放在.codex/skills/下然后看 frontmatter 是否有语法错误YAML 对缩进敏感一个 tab 就能让整个文件解析失败。误触发的话把 description 写得更具体加上限定条件。比如“在 React 项目里”比“在项目里”好“使用 React Hook Form”比“使用表单库”好。还可以在正文开头加一句“如果项目未使用 React Hook Form请忽略本 skill”给 AI 一个退出条件。5.2 加载了 skill 但步骤执行不完整常见原因是步骤太抽象AI 自由发挥时跳步。解决办法是把每步的输入输出写死并加上验证点。比如“读取 package.json 后输出 react-hook-form 的版本号如果低于 7.0.0 则停止并告知用户”。另一个原因是上下文被截断skill 正文太长导致后半部分没加载。这时候要精简正文把非核心内容移到 references。5.3 脚本执行权限与路径问题scripts 目录里的脚本在 Windows 下可能因为没有执行权限而失败。建议在 skill 正文里让 AI 用bash scripts/setup.sh显式调用而不是直接./scripts/setup.sh。路径统一用相对于项目根目录的写法避免绝对路径导致换机器就挂。5.4 团队协作中的 skill 冲突两个人写了功能重叠的 skill同时命中时行为不可预测。解决办法是建立 skill 注册表每个 skill 登记名称、负责人、适用范围、优先级。新 skill 上线前检查是否与已有 skill 重叠重叠的话合并或明确互斥。我们团队用了一个简单的 Markdown 表格维护这个注册表放在仓库根目录PR 时强制更新。问题现象可能原因排查方法解决方式skill 不触发description 不匹配对比用户请求和 description 关键词改写 description增加场景限定skill 误触发description 太宽泛用负向用例测试加限定条件或互斥声明步骤跳步正文太抽象检查每步是否有明确输入输出细化步骤加验证点脚本失败权限或路径问题手动执行脚本看报错用 bash 显式调用统一相对路径上下文截断正文过长看加载日志精简正文细节移到 references多 skill 冲突功能重叠检查注册表合并或设优先级提示每次平台大版本更新后重新跑一遍 skill 测试用例。平台可能调整匹配算法或工具接口旧 skill 不一定兼容。6. 进阶玩法把 skills 和 agents、plugin 串起来6.1 skills 与 agents 的分工Agent 负责决策“做什么”skill 负责指导“怎么做”。一个 agent 可以挂载多个 skill根据任务动态加载。比如一个“前端开发 agent”可以挂 new-form-component、new-page、fix-lint 三个 skill用户说“加个表单”就加载第一个说“修一下 lint”就加载第三个。这样 agent 的职责清晰skill 的复用性也高。LangChain Deep Agents 这类框架里agent 和 skill 的绑定关系通常在配置里声明。我建议按领域划分 agent按任务划分 skill避免一个 agent 挂几十个 skill 导致匹配混乱。6.2 skills 与 plugin 的边界Plugin 提供底层能力比如文件读写、网络请求、数据库连接skill 提供上层流程比如“新增组件时先读目录再写文件再跑测试”。两者配合的方式是skill 正文里调用 plugin 提供的工具。比如 skill 说“用 Read 工具读取 package.json”Read 就是 plugin 提供的能力。判断一个功能该做成 plugin 还是 skill看它是否需要跨任务复用。文件读写、命令执行这种每个任务都可能用到的做成 plugin业务规范、操作流程这种特定任务才用的做成 skill。6.3 用 skills 做代码审查与规范落地除了生成代码skills 还能用于审查。写一个 code-review skill正文里列出团队的审查清单命名规范、类型完整性、测试覆盖、性能隐患、安全边界。AI 在 review 时加载这个 skill就会按清单逐条检查而不是泛泛地说“代码看起来不错”。这个玩法在我们团队效果很好。以前 code review 靠人肉记规范新人经常漏项现在 AI 先跑一遍 skill把明显问题标出来人只需要看 AI 拿不准的部分。效率提升明显规范落地也更彻底。6.4 持续迭代从使用日志里找改进点Skills 不是写完就完了。我建议定期看使用日志统计每个 skill 的触发次数、任务成功率、用户反馈。触发少但任务重要的 skill可能是 description 没写好触发多但成功率低的 skill可能是步骤有问题。根据数据迭代比拍脑袋改有效得多。另外把用户经常手动纠正 AI 的地方记下来这些就是 skill 该补充的约束。比如用户反复说“不要用 default export”那就在 skill 约束里加上这一条。日积月累skill 会越来越贴合团队的实际习惯。我个人在实际操作中的体会是skills 的价值不在于写得多而在于写得准。一个描述精准、步骤清晰的 skill比十个泛泛而谈的 skill 有用得多。刚开始可以从一两个高频任务入手跑通流程后再逐步扩展。踩过几次坑之后你会发现最难的不是技术实现而是把团队里那些“只可意会”的经验变成可执行的文字。这件事值得花时间做因为一旦沉淀下来就是团队长期受益的资产。