1. 从skills这个词说起它到底指什么第一次看到skills这个标题很多人会以为是某个泛泛的概念或者干脆就是招聘网站上那个技能栏。但如果你最近在折腾 Claude Code、Codex 这类 AI 编程助手就会发现skills已经变成了一个非常具体的工程概念——它指的是给 AI Agent 挂载的可复用能力模块。我最初接触这个概念的时候也懵。传统意义上我们讲给 AI 加技能无非就是写个 prompt、调个 API、接个工具函数。但 skills 这套东西不太一样它更像是一种结构化的能力封装协议把一段特定领域的知识、一套操作流程、一组工具调用方式打包成一个可以被 Agent 动态发现、按需加载的单元。你可以把它理解成给 AI 装的插件但比插件更轻、更语义化。为什么这个东西突然火起来因为大家发现光靠一个通用大模型 一堆工具做复杂任务时上下文会被撑爆模型注意力也会被稀释。而 skills 的思路是平时不加载用到才加载。Agent 先看到一份 skills 清单只有名字和一句话描述判断当前任务需要哪个 skill再把那个 skill 的完整内容拉进上下文。这个机制在 Claude Code 里叫 Agent Skills在 Codex 生态里也有类似的设计。这篇文章我想聊的不是skills 是什么这种百科式介绍而是一个真正在项目里用 skills 的人会怎么设计、怎么踩坑、怎么把它用出价值。适合已经在用 Claude Code / Codex、或者准备给自己的 Agent 系统加 skills 机制的开发者。如果你只是听说过这个词看完也能明白它到底解决了什么问题。2. Skills 的核心机制渐进式披露与按需加载2.1 为什么不能把所有能力一次性塞给模型先说一个我踩过的坑。早期我给自己的 Agent 写了一个超长的 system prompt把代码规范、部署流程、数据库约定、日志格式全塞进去大概有八千多 token。结果发现模型在简单任务上表现反而变差了——问它一个简单的函数怎么写它会莫名其妙地扯到部署流程上去。这就是上下文污染。模型的注意力是有限的无关信息越多真正相关的信息被看到的概率就越低。而且每次请求都要带上这八千 token成本和延迟都上去了。Skills 机制的核心价值就在这它把能力和上下文解耦了。每个 skill 是一个独立文件通常是一个带 frontmatter 的 Markdown平时只暴露元数据Agent 需要时才加载全文。这个设计在 Anthropic 的 Agent Skills 文档里被称为progressive disclosure渐进式披露。2.2 一个 skill 的最小结构长什么样我实际用下来一个能跑的 skill 至少包含三部分--- name: db-migration description: 当需要修改数据库 schema、新增字段或调整索引时使用。包含迁移脚本编写规范和回滚流程。 --- ## 使用场景 当用户要求修改表结构、新增字段、调整索引时触发。 ## 操作步骤 1. 在 migrations/ 目录下创建带时间戳的迁移文件 2. 使用 up/down 双函数结构 3. 本地执行 dry-run 验证 ...关键在 frontmatter 里的name和description。description 写得好不好直接决定这个 skill 会不会被正确触发。我见过太多人把 description 写成这是一个数据库相关的技能结果模型根本不知道什么时候该用它。正确的写法是描述触发条件而不是描述内容。2.3 加载时机模型自己判断还是人工指定这里有个容易混淆的点。Skills 的触发有两种模式模式触发方式适用场景风险自动触发模型根据 description 自行判断通用型 skill、任务边界清晰误触发、漏触发显式调用用户或代码显式指定 skill 名关键流程、高风险操作需要人工介入混合模式自动推荐 人工确认生产环境流程稍长我个人的经验是涉及写操作、删除操作、部署操作的 skill一律走显式调用。让模型自己判断要不要执行数据库迁移这个风险太大了。而像代码风格检查文档生成这类只读或低风险的可以放开自动触发。2.4 和传统 tool calling 的本质区别很多人会问这不就是 function calling 吗不是。Function calling 是模型调用一个函数输入输出都是结构化的参数。而 skill 是模型加载一段知识它可能包含多个工具调用、多个步骤、甚至一些判断逻辑。打个比方function calling 像是给 AI 一把锤子skill 像是给 AI 一本《木工手册》外加一套工具。前者是原子能力后者是封装好的工作流。这也是为什么 skills 特别适合那些步骤多、有约定、需要领域知识的任务。3. 在 Claude Code 里落地 Skills 的完整流程3.1 目录结构与文件放置位置Claude Code 对 skills 的加载有固定的目录约定。我实测下来主要有两个位置项目级project/.claude/skills/只对当前项目生效用户级~/.claude/skills/对所有项目生效每个 skill 是一个独立目录目录里放一个SKILL.md。注意是目录 SKILL.md不是单个 md 文件。这个结构一开始我也搞错了直接把db-migration.md丢进去结果死活不加载。.claude/ └── skills/ ├── db-migration/ │ └── SKILL.md ├── api-design/ │ └── SKILL.md └── release-check/ └── SKILL.md如果 skill 需要附带脚本、模板文件也放在同一个目录下然后在 SKILL.md 里用相对路径引用。这样打包和迁移都很方便。3.2 description 的写法决定生死的一行字我再强调一遍 description 的重要性因为这是整个 skill 机制里最容易翻车的地方。反面教材description: 帮助处理数据库相关的工作正面教材description: 当用户要求新增/修改数据库表结构、添加字段、创建索引、或编写数据迁移脚本时使用。不适用于查询优化和 SQL 调试。区别在哪正面教材明确了触发条件新增/修改表结构、加字段、建索引、写迁移脚本和排除条件不适用于查询优化和 SQL 调试。模型判断是否加载时靠的就是这些信号。我总结了一个 description 的写法公式当 [具体触发场景列举] 时使用。不适用于 [容易混淆的场景]。这个不适用于特别关键。因为很多 skill 的边界是模糊的不写清楚排除条件模型就会在边缘场景乱触发。3.3 用 SKILL.md 组织操作步骤的实战模板下面是我在项目里实际用的一个 skill 模板做了脱敏处理--- name: release-check description: 当用户要求发布新版本、打 tag、或执行上线前检查时使用。不适用于日常提交和本地测试。 --- ## 前置检查 1. 确认当前分支是 main 且工作区干净 2. 确认 CHANGELOG.md 已更新 3. 确认版本号在 package.json 中已 bump ## 执行步骤 1. 运行 npm run build 并检查产物 2. 运行 npm run test:ci 3. 如果测试通过执行 git tag v{version} 4. 推送 tag 并触发 CI ## 失败处理 - 构建失败检查 node 版本是否为 18 - 测试失败不要跳过定位到具体用例 - tag 已存在先确认是否重复发布 ## 注意事项 - 不要在周五下午发布 - 发布前确认回滚方案这个模板的价值在于它把发布这个动作的所有隐性知识显性化了。新人接手时不用问老员工发布要注意什么skill 里全写着。这也是 skills 除了给 AI 用之外另一个被低估的价值——它其实是团队知识的载体。3.4 验证 skill 是否被正确加载写完 skill 不代表就生效了。我常用的验证方法直接问模型你现在有哪些可用的 skills 看它能不能列出你刚写的那个构造触发场景给一个明确应该触发该 skill 的任务观察它是否加载构造边界场景给一个模糊的任务看它是否误触发如果 skill 没被加载排查顺序是目录结构对不对 → frontmatter 格式对不对 → description 是否够明确 → 是否有语法错误导致解析失败。4. Codex 生态下的 Skills 与跨工具迁移4.1 Codex 的 skills 机制差异Codex 这边的 skills 概念和 Claude Code 不完全一样。Codex 更偏向于配置驱动很多能力通过配置文件、AGENTS.md 这类约定来定义。但核心思路是一致的把领域知识从主 prompt 里剥离出来按需注入。我实测下来Codex 里比较实用的做法是用AGENTS.md定义项目级的通用约定用独立的 skill 文件定义特定任务的流程通过显式的引用让模型加载对应 skill差异点在于Codex 对 skill 的自动发现能力相对弱一些更多依赖显式引用。所以如果你从 Claude Code 迁移过来会发现自动触发没那么灵需要调整使用习惯。4.2 一份 skill 能不能同时给两个工具用这是很多人关心的问题。答案是核心内容可以复用但元数据要适配。我的做法是维护一份源 skill然后写个小脚本生成两个版本字段Claude Code 版本Codex 版本元数据格式YAML frontmatter配置项或注释触发方式description 自动匹配显式引用为主文件位置.claude/skills/项目约定目录正文内容完全一致完全一致正文部分操作步骤、注意事项是纯 Markdown两边通用。真正需要适配的只有头部元数据。这样维护成本就降下来了。4.3 跨工具迁移时最容易丢的东西迁移时最容易丢的不是内容而是触发上下文。在 Claude Code 里description 写得好模型会自动加载迁到 Codex 后如果还是靠自动触发很可能就不灵了。我的经验是迁移时把自动触发改成显式引用同时在项目文档里写清楚什么任务该引用哪个 skill。虽然多了一步人工判断但稳定性反而更高。毕竟 skill 的价值是知识封装不是自动魔法。5. 设计一个好 Skill 的几条硬经验5.1 粒度控制一个 skill 只干一件事我见过最夸张的一个 skill把代码审查 单元测试 部署 监控配置全塞在一起两千多行。结果就是模型加载它之后注意力被分散每个环节都做得马马虎虎。正确的做法是按任务边界拆分。判断标准很简单如果这个 skill 的 description 里出现了和或者以及就该考虑拆了。差code-quality代码质量涵盖审查、测试、格式化好code-review、unit-test-gen、format-check三个独立 skill拆开之后每个 skill 的 description 更精准触发更准加载的上下文也更小。5.2 写什么时候不用比写什么时候用更重要这一点我在前面提过但值得单独拎出来说。因为误触发的代价往往比漏触发大。漏触发模型没加载 skill按通用能力处理可能做得不够好但不会出大错。 误触发模型加载了不该加载的 skill按错误的流程操作可能造成实际损害。所以每个 skill 的 description 里我都会认真写不适用于部分。比如一个数据库迁移的 skill我会明确写不适用于查询优化、不适用于数据修复、不适用于生产环境直接操作。5.3 把隐性知识显性化Skills 最大的价值其实是把老员工脑子里的隐性知识写下来。比如为什么这个字段要用text而不是varchar为什么发布前要先跑一遍 dry-run为什么这个接口不能加缓存这些为什么平时没人写文档但新人踩坑时又特别需要。把它们写进 skillAI 用得上人也能看。这是我觉得 skills 机制最被低估的地方。5.4 版本管理skill 也要进 gitSkill 是代码资产必须进版本控制。我见过有人把 skill 放在本地不提交结果换台机器就没了。我的做法是项目级 skill 跟着项目走用户级 skill 单独建一个 repo 管理。每次修改 skill 都走正常的 PR 流程这样能追溯为什么这个步骤是这么写的。6. 踩坑实录那些让我熬夜排查的 skills 问题6.1 skill 死活不加载从目录结构开始排查有一次我写了个 skill怎么都不生效。排查了半小时最后发现是目录名和 frontmatter 里的 name 不一致。Claude Code 加载时以目录名为准但我在 SKILL.md 里写的 name 是另一个导致索引混乱。排查链路是这样的先确认目录存在且拼写正确检查 SKILL.md 文件名是否大小写正确Linux 下大小写敏感检查 frontmatter 的---是否成对检查 name 和目录名是否一致检查 YAML 缩进是否有 tabYAML 不允许 tab这个顺序建议你存下来能省不少时间。6.2 description 写得太泛导致误触发我写过一个api-design的 skilldescription 是当涉及 API 相关工作时使用。结果发现只要任务里出现接口两个字它就被加载哪怕只是让我改个接口的注释。后来改成当用户要求设计新的 REST 接口、定义请求响应结构、或规划接口版本策略时使用。不适用于修改现有接口的注释、调试接口报错、编写接口测试。改完之后误触发率大幅下降。description 的精度直接决定 skill 的可用性。6.3 多个 skill 冲突时的优先级问题当两个 skill 的触发条件有重叠时模型可能同时加载两个然后按哪个执行就不确定了。我遇到过db-migration和db-schema-design同时被加载结果模型在改字段这个任务上左右横跳。解决办法有两个在 description 里划清边界明确写涉及实际执行迁移用 A只做设计讨论用 B在 skill 正文里加互斥说明比如如果同时加载了 X skill以本 skill 为准我倾向于第一种因为边界清晰是设计问题不该靠运行时打补丁。6.4 skill 内容过长反而拖慢响应有个 skill 我写了三千多字包含大量示例代码。结果每次加载它响应都明显变慢而且模型经常抓不住重点。后来我做了两件事正文精简到核心步骤把详细示例移到同目录的examples.md需要时再引用用表格和列表替代大段文字信息密度更高改完之后加载速度和执行准确率都上来了。skill 不是越长越好是越准越好。7. 从 skills 到 Agent 能力体系我的整体思路7.1 分层设计基础约定、领域 skill、任务 skill用了一段时间之后我慢慢形成了一套分层思路层级内容加载方式例子基础层项目通用约定常驻代码风格、目录结构、命名规范领域层某类任务的通用流程按需数据库操作、API 设计、测试编写任务层具体任务的执行步骤显式发布流程、迁移脚本、故障排查基础层放AGENTS.md或 system prompt领域层和任务层放 skills。这样既保证了通用约定始终生效又避免了上下文被撑爆。7.2 用 skills 承载团队规范我们团队现在有个约定任何口口相传的规范都要沉淀成 skill。比如提交信息怎么写分支怎么命名review 要看哪些点全部写成 skill。好处是双重的AI 用得上新人也能看。而且 skill 进 git 之后规范变更有了历史记录比散落在 wiki 里的文档靠谱多了。7.3 持续迭代skill 是活的Skill 不是写完就完事的。我每个月会回顾一次哪些 skill 从没被触发过可能 description 有问题哪些经常误触发边界没划清哪些内容已经过时流程变了这个过程有点像维护测试用例需要持续投入。但回报也很明显你的 Agent 会越来越懂你的项目。8. 一些实用建议和后续可以做的事如果你刚开始接触 skills我的建议是从一个小场景切入。别一上来就想着把整个项目的知识都 skill 化那样容易半途而废。先挑一个你每周都要重复做、步骤又比较固定的任务把它写成 skill跑通整个流程感受一下效果。跑通之后再逐步扩展。我自己的节奏是每周沉淀 1-2 个 skill一个月下来就有了一套能覆盖主要工作流的能力库。后续可以探索的方向我个人比较感兴趣的是skill 的自动化测试——怎么验证一个 skill 在给定输入下会正确触发、正确执行。目前这块还比较手工如果能做成 CI 的一部分skill 的质量会更有保障。另外就是skill 之间的组合。单个 skill 解决单点问题但真实任务往往是多个 skill 串联。怎么让 Agent 自动编排多个 skill这是个值得琢磨的问题。我试过在 skill 里显式引用其他 skill效果还行但还不够优雅。最后分享一个我踩坑后总结的小技巧写 skill 的时候把自己想象成在给一个刚入职的同事写操作手册。这个心态一换写出来的东西立刻就不一样了——你会自然地写清楚为什么、写清楚什么时候别用、写清楚出错了怎么办。而这些恰恰是 skill 最有价值的部分。