1. 从每次都要重新教AI说起agent-skills到底在解决什么如果你最近半年深度用过 Claude Code、Cursor 这类 AI coding agent大概率经历过这样一种循环新开一个会话agent 对你的项目结构、代码规范、提交习惯一无所知你得重新贴一遍目录树、重新解释一遍我们不用 default export测试文件放tests下commit message 用 conventional commits。解释完这一轮会话结束下次再来一遍。这个循环的本质问题是agent 的能力是通用的但你的项目知识是私有的。通用能力靠模型本身私有知识过去只能靠你每次手动喂。而 agent-skills 这套东西就是把这个喂的动作标准化、文件化、可复用化——把项目知识、操作流程、领域经验沉淀成 agent 能自动识别和加载的 skill 文件让 agent 在需要的时候自己去找、自己去用。我把它理解成给 AI coding agent 装的一套岗位说明书 操作手册。你不再需要每次口头交代而是提前写好一份份 skillagent 在遇到对应场景时自动调用。这跟过去写.cursorrules、CLAUDE.md是同一个思路的延伸但 agent-skills 走得更远它不只是全局规则而是按场景拆分的、可被按需触发的技能单元。适合谁来读这篇三类人最有用一是已经在用 Claude Code 或 Cursor、但还停留在每次手动贴上下文阶段的开发者二是团队里负责工程规范、想让多个人的 agent 行为保持一致的技术负责人三是想把自己重复性的操作流程比如发版、写迁移脚本、生成 API 文档固化下来、以后一句话就能触发的效率党。如果你还没装过 Claude Code建议先把基础跑通再回来看这篇否则会有点空中楼阁。下面我会从skill 到底是什么形态讲起然后拆解它的加载机制、怎么写第一个能用的 skill、怎么组织多个 skill、以及我在实际使用中踩过的那些坑。全程按我自己的实操顺序来不搞理论空转。2. skill 的文件形态与加载机制它凭什么能被自动触发2.1 一个 skill 最小长什么样先说结论一个 skill 本质上就是一个带 frontmatter 的 Markdown 文件放在约定的目录里。它的核心结构分两块——元数据metadata和正文指令instructions。元数据部分通常包含name技能名、description什么时候该用这个技能这两项最关键。正文部分就是你写给 agent 的具体指令做什么、按什么顺序做、注意什么。我用一个真实场景举例。假设我们团队有个固定流程每次新增数据库迁移文件都要遵循一套命名和回滚规范。我会写一个 skill大致长这样--- name: db-migration description: 当需要创建、修改或回滚数据库迁移文件时使用。适用于 migrations 目录下的所有操作。 --- 创建迁移文件时遵循以下规则 1. 文件名格式为 YYYYMMDDHHMMSS_动词_对象.sql动词用 create/alter/drop/add。 2. 每个迁移文件必须包含 up 和 down 两部分down 必须能完整回滚 up 的操作。 3. 涉及大表加字段时必须显式指定默认值或允许 NULL避免锁表。 4. 迁移文件写完后在文件头部注释里写明本次变更的影响范围和预估执行时长。就这么简单。没有复杂的 DSL没有要编译的东西就是纯文本。这是 agent-skills 最聪明的地方——它把扩展 agent 能力这件事的门槛降到了会写 Markdown。2.2 description 字段才是真正的开关很多人第一次写 skill 会犯一个错把精力全花在正文指令上description 随便写一句处理数据库相关操作。结果就是 skill 写好了agent 却很少触发它。原因在于agent 决定要不要加载某个 skill主要看的就是 description。它不会把每个 skill 的正文都读一遍再判断——那样 token 成本太高。它先扫一遍所有 skill 的 name description判断当前任务和哪个 description 匹配匹配上了才去读正文。所以 description 的写法直接决定 skill 的命中率。我的经验是description 要写清楚三件事触发场景、适用对象、边界。对比一下写法问题改进处理数据库太泛agent 不知道何时用当需要创建、修改或回滚数据库迁移文件时使用写代码规范没有具体场景当新增 React 组件、编写组件测试时使用发版流程边界不清当执行生产环境发布、打 tag、生成 changelog 时使用不适用于预发环境我实测下来description 里带上当……时使用这种明确的触发条件命中率能明显提升。因为它给了 agent 一个清晰的模式匹配信号而不是让它去猜。2.3 加载是按需而非全量这里有个关键机制值得说透agent 加载 skill 不是一次性把所有 skill 塞进上下文而是渐进式披露progressive disclosure。具体来说分三层第一层agent 启动时只加载所有 skill 的 name 和 description这部分很轻第二层当判断某个 skill 相关时才把它的正文读进来第三层如果 skill 正文里引用了其他文件比如一个脚本、一份模板agent 在执行到那一步时才去读那个文件。这个设计的意义在于控制上下文预算。你可能有几十个 skill如果全量加载光 skill 就吃掉几千甚至上万 token留给实际任务的预算就少了。按需加载让skill 数量多和上下文干净这两件事不再矛盾。理解这一点之后你写 skill 的策略也会变正文可以写得很详细因为不触发就不占上下文但 description 必须精准因为它永远在上下文里。这跟写代码时接口要窄、实现可以厚是一个道理。3. 动手写第一个 skill从目录结构到实际触发3.1 目录放哪里决定了谁能用skill 的存放位置直接决定它的作用范围。常见的有三个层级项目级放在项目根目录下的约定文件夹里不同工具路径略有差异Claude Code 一般是.claude/skills/这类位置。只对当前项目生效适合项目专属规范。用户级放在用户主目录下的配置目录里。对你所有项目生效适合个人通用习惯比如我写 Python 一律用 ruff 格式化。团队/共享级通过版本控制或共享目录分发让整个团队用同一套 skill。我的建议是项目强相关的放项目级并提交到 git个人习惯放用户级团队规范两者结合。项目级的 skill 跟着代码走新人 clone 下来就自动获得一致的 agent 行为这是它最大的价值。这里有个容易忽略的点项目级 skill 提交到 git 后要确保它不会被构建产物或部署流程误打包。一般放在源码目录之外、或者加进.npmignore/.dockerignore里。我见过有人把 skill 目录放进了会被打包的路径结果生产镜像里多了一堆无关文件。3.2 写 skill 正文的四个实用原则正文怎么写直接决定 skill 好不好用。我总结了四条第一用命令式别用描述式。写创建文件时先检查目录是否存在而不是创建文件时应该注意目录是否存在。agent 需要的是可执行的指令不是背景介绍。第二步骤要能落地到具体命令或文件路径。别写运行测试要写运行pnpm test --filteraffected。模糊指令会让 agent 自由发挥结果往往不是你想要的。第三把为什么也写进去。这一点很多人忽略。比如你规定迁移文件必须包含 down如果只写规则agent 可能在某些情况下觉得 down 不重要就跳过。但如果你补一句因为生产环境回滚依赖 down缺失会导致无法回退agent 在边缘情况下更可能坚持这条规则。给 agent 讲道理它会更可靠地执行。第四控制单个 skill 的职责范围。一个 skill 只干一件事。别写一个万能 skill把代码规范、测试、发版全塞进去。职责越单一description 越容易写准触发越精准。3.3 验证 skill 是否真的被触发写完 skill 别急着高兴先验证它到底会不会被触发。我的验证方法是构造一个明确的触发场景然后观察 agent 的行为。比如写完db-migrationskill 后我会新开一个会话直接说帮我加一个用户表的 phone 字段迁移。如果 skill 生效agent 应该按我定义的命名格式创建文件、带上 down、在头部写注释。如果它没这么做说明要么 description 没匹配上要么正文指令不够明确。排查顺序是先看 description 是不是太泛或太窄再看正文是不是有歧义。我遇到过一次skill 明明写了命名格式agent 却用了自己的格式最后发现是正文里我用了建议这个词——agent 把建议理解成了可选。改成必须之后就稳定了。在 skill 里措辞的确定性直接影响执行的确定性。4. 多 skill 协作怎么组织才不会互相打架4.1 按任务阶段还是按领域拆分当你有了五六个 skill 之后就会面临组织问题是按任务阶段拆写代码、测试、发版还是按技术领域拆前端、后端、数据库我的实践结论是优先按领域拆领域内部再按阶段细分。原因是 agent 判断当前任务属于哪个领域比判断当前处于哪个阶段更容易。你说加个接口agent 能明确这是后端领域但现在是不是该测试了这种阶段判断往往依赖上下文容易误判。所以我的目录大概是这样组织的skills/ backend/ api-endpoint.md db-migration.md frontend/ react-component.md style-guide.md workflow/ release.md changelog.md领域 skill 负责这类活怎么干workflow skill 负责跨领域的流程怎么走。两者职责清晰不容易冲突。4.2 冲突的根源与规避多个 skill 同时被触发时最容易出的问题是指令冲突。比如style-guide说缩进用 2 空格另一个legacy-format说缩进用 4 空格agent 就懵了。规避冲突的核心原则是让每个 skill 的适用边界互斥。具体做法有两个一是在 description 里写清不适用于。比如style-guide的 description 补一句不适用于 legacy 目录下的历史代码。这样 agent 在处理 legacy 代码时就不会误触发新规范。二是用优先级显式声明。有些工具支持在元数据里标优先级冲突时高优先级覆盖低优先级。如果不支持就在正文里写当与其他 skill 冲突时以本 skill 为准。我踩过的一个坑是两个 skill 都涉及 commit message 格式一个要求带 issue 号一个没提。结果 agent 有时带有时不带很不稳定。后来我把 issue 号要求合并进主 skill删掉了那个重复的问题就消失了。能合并的 skill 就合并别为了看起来模块化而强行拆分。4.3 skill 之间的引用与复用skill 正文里可以引用其他 skill 或共享文件这是减少重复的好办法。比如releaseskill 里可以写生成 changelog 时遵循changelogskill 的规则。但引用要克制。引用链太长会让 agent 的加载路径变复杂也增加排查难度。我的经验是引用深度不超过两层超过两层就该考虑是不是该合并了。另外共享的模板、脚本这类资源建议放在一个统一的assets/或templates/目录里skill 正文用相对路径引用。这样改一处所有引用它的 skill 都跟着更新避免复制粘贴导致的版本漂移。5. 实战踩坑那些文档里不会写的经验5.1 skill 写太细反而不好用新手容易走极端把 skill 写成一本操作手册事无巨细全列上。结果 agent 执行时被大量细节淹没反而抓不住重点。我的教训是skill 正文控制在关键决策点 必要步骤这个粒度。什么是关键决策点就是那些如果 agent 自己发挥很可能做错的地方。比如命名格式、目录位置、必须包含的字段。至于先打开文件再编辑这种常识性步骤不用写agent 自己会。一个判断标准如果你不写这条agent 有 50% 以上概率做错那就写低于这个概率就别写。这样能保证 skill 精简且高价值。5.2 中文 skill 的编码与标点问题如果你的 skill 正文用中文写有两个细节要注意。一是文件编码统一用 UTF-8否则某些环境下中文会乱码agent 读到的就是一堆问号。二是标点尽量用中文全角但代码、路径、命令里的符号必须用英文半角。混用会导致 agent 解析出错。我遇到过一次诡异的问题skill 里写了个路径src/组件/结果 agent 死活找不到目录。排查半天发现是路径里的斜杠被输入法打成了全角。在 skill 里凡是涉及代码和路径的地方切到英文输入法再打这个习惯能省很多事。5.3 版本更新后 skill 失效AI coding agent 这类工具迭代很快skill 的加载机制、目录约定、元数据字段都可能变。我遇到过升级工具版本后原来能触发的 skill 突然不触发了最后发现是目录路径改了。应对办法是把 skill 目录纳入版本控制并在 README 里记录当前适配的工具版本。升级工具后先跑一遍验证场景确认 skill 还正常再继续用。别等到关键时刻才发现 skill 失效。5.4 别把敏感信息写进 skill这一点必须强调。skill 会被提交到 git、会被 agent 读取绝对不能把密钥、token、内部地址、账号密码写进去。需要用到这类信息时让 skill 引用环境变量或外部配置文件正文里只写从环境变量 XXX 读取。我见过有人图省事把测试环境的数据库连接串直接写进 skill结果提交到了公开仓库。这种坑一次就够记一辈子。skill 是给 agent 看的说明书不是保险箱。6. 把重复劳动固化下来我的 skill 清单与迭代方法6.1 我目前常驻的几个 skill用了一段时间后我沉淀下来几个高频 skill基本覆盖了日常大部分重复场景skill 名触发场景核心价值api-endpoint新增/修改后端接口统一路由、参数校验、错误码规范react-component新增前端组件统一目录结构、命名、测试文件位置db-migration数据库变更保证可回滚、命名规范、锁表规避release生产发布固定检查清单、changelog 生成code-review提交前自查按团队 checklist 过一遍这几个 skill 加起来不到 500 行 Markdown但省下的重复解释时间非常可观。尤其是团队协作时新人 clone 下来就自动获得一致的 agent 行为不用再口头培训。6.2 skill 也要迭代别写完就不管skill 不是一次性的。我的做法是每次发现 agent 在某个场景做错了就回头看看是不是 skill 该更新。如果这个错误是重复出现的那基本就是 skill 的缺口。迭代时注意小步修改。一次只改一个点改完立刻验证。别一次性大改否则出问题很难定位是哪处改动导致的。我一般会在 skill 目录里保留一个简单的变更记录写清楚每次改了什么、为什么改方便回溯。6.3 从个人 skill 到团队资产个人用顺了之后下一步就是团队化。团队化的关键不是技术而是共识。skill 里的规范必须是团队认可的否则就会出现你的 skill 和我的习惯打架。我的建议是先个人试点跑通了再拿到团队评审。评审时重点讨论那些有争议的规则比如命名风格、目录结构达成一致后再合并进共享 skill。这样推行的阻力最小也最容易落地。最后分享一个我自己的体会agent-skills 这东西价值不在于写了多少而在于写对了几个。一个精准的 skill 顶十个模糊的。与其追求 skill 数量不如把最痛的那两三个重复场景打磨到位让 agent 真正成为你工作流的一部分而不是一个需要你反复调教的工具。