1. 从装完就吃灰说起agent-skills 到底解决了什么问题我身边不少朋友最近都在折腾 AI coding agentsClaude Code 装了、Cursor 也配了结果用了一周就搁那儿吃灰。问起来原因都差不多要么是每次都要重新解释一遍项目规范要么是让它改个代码风格它给你重写整个文件要么是同一个错误反复犯。说白了就是通用 agent 不懂你的项目。agent-skills这个项目本质上就是给 AI coding agents 装技能包的一套机制。你可以把它理解成给一个新来的实习生发一本《团队开发手册》——手册里写清楚了这个项目用什么框架、代码风格是什么样、提交信息怎么写、测试怎么跑、哪些文件不能碰。没有这本手册实习生每次干活都得问你一遍有了这本手册他上手就能按规矩来。这套东西的核心价值在于三个字可复用。你花半小时写好的一个 skill之后每次让 agent 干活它都会自动加载不用重复交代。对于长期维护的项目来说这个投入产出比非常高。适合谁来用我的判断是只要你每周用 AI coding agent 写代码超过 5 小时或者你手上有超过两个需要长期维护的项目就值得花时间把 skills 体系搭起来。纯小白也能上手因为 skill 本质上就是一个 Markdown 文件不需要写代码。热搜词里频繁出现的claude code skills 安装、agent-skills、skills CLI这几个词其实指向的是同一件事怎么把这套技能机制跑起来。下面我按自己的实操经验从设计思路到落地细节完整拆一遍。2. 整体设计思路为什么是技能文件而不是提示词模板2.1 核心思路拆解把项目知识从对话里搬到文件里传统用法是每次开新会话你手动粘贴一段项目说明或者靠 agent 自己去读代码猜规范。这两种方式都有问题手动粘贴费时且容易漏让 agent 自己猜则经常猜错——它可能把你项目里的历史遗留写法当成规范去模仿。agent-skills的思路是把这些知识外化成独立文件放在项目里一个约定好的目录下常见的是.claude/skills/或项目根目录的skills/文件夹。agent 启动时会扫描这个目录把匹配当前任务的 skill 加载进上下文。这个设计的关键在于按需加载——不是把所有 skill 一股脑塞进去而是根据你当前在做什么改前端、写测试、做数据库迁移加载对应的那一个。我实测下来这种按需加载比全量塞入效果好很多。原因很直接上下文窗口是有限资源塞太多无关内容会稀释 agent 对当前任务的注意力。你让它改一个 React 组件结果上下文里一半是数据库迁移规范它反而容易跑偏。2.2 方案选型为什么用 Markdown 而不是 JSON 或 YAML有人会问为什么 skill 文件用 Markdown 而不是结构化格式我的理解是这样skill 的内容大部分是自然语言描述——变量命名用 camelCase、组件文件必须导出 default、提交前跑一遍 lint。这些用 JSON 写会非常别扭而且 agent 读自然语言的理解效果本来就比读结构化字段好。Markdown 还有个好处是人也能读。你团队里新来的真人同事翻一遍 skills 目录就能快速了解项目规范这份文档同时服务人和 agent一举两得。YAML 适合配置Markdown 适合说明skill 属于后者。至于 skill 的触发机制常见做法是在文件头部用一段 frontmatter 声明元信息比如适用场景、关键词、优先级。agent 根据这些元信息判断当前任务该不该加载这个 skill。这部分细节不同工具实现略有差异但核心逻辑一致。2.3 优势与要规避的坑这套方案最大的优势是解耦。项目规范变了你改 skill 文件就行不用去改 agent 的配置也不用重新训练什么。规范是规范工具是工具各管各的。要规避的坑主要有两个。第一是skill 写太细细到每行代码怎么缩进都规定结果 agent 被束缚得死死的稍微超出规范就不会干活了。skill 应该规定原则和边界而不是每一笔怎么写。第二是skill 之间冲突比如一个 skill 说用 tabs 缩进另一个说用 spacesagent 加载两个就懵了。这个后面在问题排查部分会详细讲怎么处理。3. 核心细节解析一个高质量 skill 文件长什么样3.1 文件结构元信息 正文说明 示例一个能用的 skill 文件我一般按三段式来写。第一段是元信息声明这个 skill 叫什么、什么时候用、优先级多高。第二段是正文说明用自然语言讲清楚规范是什么、为什么这么定。第三段是示例给正例和反例各一到两个。元信息部分不同工具字段名不一样但核心就那几个name技能名、description一句话说明用途、when_to_use触发条件、priority优先级冲突时谁覆盖谁。这里的关键是when_to_use要写得具体别写写代码时使用这种废话要写修改 React 函数组件或新增组件文件时使用。正文说明部分我踩过的坑是只写是什么不写为什么。比如你写禁止使用 any 类型agent 可能在某些边界情况下觉得用 any 更方便就违反了。但如果你补一句因为 any 会绕过类型检查导致运行时错误在编译期无法发现本项目曾因此出过线上事故agent 对这条规范的重视程度会明显提升。给理由比单纯下命令有效。3.2 触发条件的设计精准比宽泛好触发条件写得太宽skill 会在不该加载的时候加载浪费上下文写得太窄该加载的时候不加载等于白写。我的经验是宁可稍窄一点因为漏加载了你还能手动提醒 agent但错误加载会持续干扰它。举个例子一个数据库迁移规范的 skill触发条件我写的是创建或修改 migration 文件、执行数据库 schema 变更时。这样它在日常写业务代码时不会加载只有真正碰数据库结构时才生效。如果你写成涉及数据库时使用那 agent 每次写一个查询语句都会加载这个 skill纯属浪费。还有个技巧是用关键词触发。在元信息里列几个关键词比如migration、schema、alter tableagent 检测到任务描述里出现这些词就加载。这个比纯语义判断更可控适合规范边界比较清晰的项目。3.3 内容颗粒度原则、边界、示例三层我把 skill 内容分成三层来写。原则层讲大方向比如本项目优先可读性而非极致性能。边界层讲红线比如禁止在组件里直接操作 DOM。示例层给具体代码。原则层不用多两三条就够多了 agent 记不住。边界层是重点因为红线是必须遵守的写清楚能避免大部分低级错误。示例层我建议正例反例都给只给正例的话 agent 不知道边界在哪给了反例它才知道哦原来这样是不行的。这里有个细节示例代码要短。一个示例超过 20 行agent 理解成本就上去了。我一般控制在 10 行以内只保留最能说明问题的那部分。3.4 注意事项别把 skill 写成百科全书我见过有人把整个项目的架构文档塞进一个 skill 文件几千字。结果 agent 加载后注意力被大量无关信息分散真正干活时反而不聚焦。skill 不是文档是操作指南。它应该回答我现在要干这件事该注意什么而不是这个项目的一切。判断标准很简单如果一个信息在你 90% 的任务里都用不到它就不该进 skill应该放在项目 README 里让人去看。skill 只放那些每次干活都需要遵守的规范。4. 实操过程从零搭起一套可用的 skills 体系4.1 环境准备与目录结构先说目录。不同 agent 工具约定的路径不一样Claude Code 常见的是项目根目录下的.claude/skills/Cursor 则更灵活可以放在.cursor/rules/或者项目里任意位置然后在配置里指定。我自己的习惯是统一放在项目根目录的skills/下然后在各工具的配置里指向这个目录这样一套 skill 多个工具共用不用维护两份。目录结构我一般这样组织skills/ frontend/ react-component.md css-naming.md backend/ api-design.md db-migration.md common/ commit-message.md code-review.md按领域分子目录好处是加载时能按目录批量匹配。比如当前任务是改前端就只扫frontend/下的 skill。安装环节热搜里claude code skills 安装问的人多我补充一句大部分情况下不需要安装这个动作你只要把 skill 文件放到约定目录agent 启动时自动扫描。有些工具提供了skills命令行工具来管理增删改查、校验格式但那是锦上添花核心还是文件本身。4.2 写第一个 skill以提交信息规范为例我建议第一个 skill 从提交信息规范开始写因为它最简单、最独立、见效最快。下面是我实际在用的一个版本你可以直接抄--- name: commit-message description: 规范 git 提交信息的格式 when_to_use: 执行 git commit 操作时 priority: high --- ## 提交信息格式 格式type(scope): subject type 取值 - feat: 新功能 - fix: 修复 bug - refactor: 重构不改变外部行为 - docs: 文档变更 - test: 测试相关 - chore: 构建、依赖等杂项 scope 为影响的模块名可选。 subject 用中文不超过 50 字结尾不加句号。 ## 示例 正例 feat(user): 新增用户头像上传接口 fix(cart): 修复优惠券重复计算的问题 反例 update code 修复了一个bug。这个 skill 写完后agent 每次提交都会按格式来你再也不用在 review 时纠正提交信息了。实测下来这一个 skill 就能省掉不少来回沟通。4.3 参数与优先级冲突时谁说了算当多个 skill 同时匹配一个任务时优先级就起作用了。我的设置原则是越具体越优先。比如common/commit-message.md是通用规范frontend/commit-message.md是前端特有的补充那前端任务时应该两个都加载且前端那个优先级更高冲突时覆盖通用版。优先级我一般用数字表示1 到 10数字越大越优先。通用规范给 5领域规范给 7项目特有规范给 9。这样层级清晰不会乱。这里有个计算逻辑要说明假设通用 skill 说subject 不超过 50 字前端 skill 说不超过 30 字前端任务时 agent 应该用 30 字这个限制。这就是优先级覆盖的实际效果。如果你不设优先级agent 可能随机选一个行为就不稳定了。4.4 实操现场一次完整的 skill 加载过程我拿一个真实场景走一遍。任务给用户模块新增一个修改密码的接口。第一步agent 解析任务识别出关键词接口、用户模块匹配到backend/api-design.md和backend/db-migration.md因为改密码要动数据库。第二步加载这两个 skill。api-design.md告诉它接口路径用/api/v1/前缀、请求体用 JSON、错误码规范是什么。db-migration.md告诉它改 schema 要写 migration 文件、不能直接改表。第三步agent 按规范生成代码接口文件、migration 文件、对应的测试。整个过程我没说一句话它自己就按项目规矩来了。对比一下没有 skill 的情况它会问你接口路径怎么定、错误码用什么、要不要写 migration来回好几轮。这就是 skill 的价值——把沟通成本前置到写 skill 的那一次。4.5 注意事项skill 的版本管理skill 文件应该跟代码一起进版本库。为什么因为规范是随项目演进的。今天你规定用 A 方案三个月后改成 B 方案skill 也得跟着改。如果 skill 不进版本库改了什么、谁改的、为什么改全都没记录过段时间就成一笔糊涂账。我一般把 skill 的变更跟相关代码变更放在同一个提交里提交信息里注明更新 xxx skill。这样回溯的时候能对上。5. 常见问题与排查技巧实录5.1 skill 不生效怎么办这是问得最多的问题。排查顺序我总结成一张表现象可能原因排查方法完全不加载目录路径不对确认 agent 配置里指向的目录和实际存放目录一致完全不加载文件格式错误检查 frontmatter 的---是否成对YAML 语法是否正确偶尔加载触发条件太窄放宽when_to_use的描述或补充关键词加载了但没遵守内容太抽象补充具体示例和边界说明加载了但被覆盖优先级设置问题检查是否有更高优先级的 skill 冲突我踩过最坑的一次是 frontmatter 里when_to_use写成了whenToUse工具不认skill 静默失效排查了半天。所以字段名一定要按工具文档来别想当然。5.2 skill 之间冲突怎么处理冲突分两种。一种是规则冲突比如一个说用 tabs 一个说用 spaces。这种靠优先级解决明确谁覆盖谁。另一种是语义冲突比如一个 skill 说优先性能另一个说优先可读性这俩不一定矛盾但 agent 可能纠结。我的处理办法是在更高优先级的 skill 里明确写一句当本 skill 与 xxx skill 冲突时以本 skill 为准。给 agent 一个明确的裁决规则它就不会纠结了。5.3 skill 写多了会不会拖慢 agent会但影响没你想的那么大。关键在于按需加载做得好不好。如果你的 skill 触发条件都很精准每次只加载一两个那即使总共有一百个 skill对单次任务也没影响。反过来如果触发条件都很宽泛每次加载十几个那确实会拖慢。我的经验值是单次任务加载的 skill 内容总量控制在 2000 字以内比较舒服。超过这个量agent 的响应质量和速度都会下降。所以写 skill 时要克制别什么都往里塞。5.4 独家避坑技巧分享几个我实际踩出来的经验。第一skill 写完先自己读一遍读的时候想象你是个完全不了解项目的新人看能不能看懂。看不懂就说明写得太跳补上背景。第二定期清理失效 skill。项目演进后有些规范已经废弃了但 skill 还留着agent 加载后按老规范干活反而添乱。我一般每个季度过一遍 skills 目录该删的删该改的改。第三给 skill 加个最后更新日期。放在 frontmatter 里一眼就能看出哪些 skill 很久没维护了优先检查这些。第四别在 skill 里写死具体路径。比如别写配置文件在/src/config/app.ts因为路径可能变。写配置文件位于 src 目录下的 config 文件夹让 agent 自己去找。写死了路径一旦重构skill 就失效了。6. 多工具协同一套 skill 喂饱 Claude Code 和 Cursor6.1 为什么值得做多工具共用现在很多人是 Claude Code 和 Cursor 混着用——重活、批量改动用 Claude Code日常编辑、补全用 Cursor。如果两套工具各维护一份 skill改一处要同步两处迟早会不一致。所以我的做法是一份 skill 源文件多工具引用。具体怎么引不同工具配置方式不同。Claude Code 一般认.claude/skills/目录你可以在项目里建这个目录然后软链接到统一的skills/目录。Cursor 则在设置里指定 rules 目录指向同一个skills/。这样改一次两边都生效。6.2 格式兼容的注意事项不同工具对 frontmatter 字段的支持不完全一样。比如有的工具认when_to_use有的认trigger。我的处理办法是把两个字段都写上值一样。多写一个字段不影响但能保证各工具都能识别。正文部分基本通用因为都是 Markdown 自然语言。唯一要注意的是别用工具特有的语法比如某个工具支持的include指令另一个工具不认用了就出问题。保持纯 Markdown兼容性最好。6.3 实测效果对比我拿同一个项目分别测了有 skill和无 skill两种情况让 agent 完成同样的任务新增一个带测试的接口。无 skill 时平均需要 4 到 5 轮对话才能把规范对齐且第一次生成的代码经常要返工。有 skill 时基本一轮就能出符合规范的代码返工率明显下降。这个提升在长期项目上尤其明显。项目越大、规范越多skill 的价值越高。小项目、一次性脚本可能就不太值得专门写 skill。7. 从个人用到团队用skill 体系的扩展思路7.1 团队共享的目录约定个人用的时候skill 放哪都行。团队用就得有约定。我的建议是项目级 skill 放项目仓库里团队级 skill 放一个独立的共享仓库通过子模块或者包管理工具引入。项目级管这个项目特有的规范团队级管所有项目通用的规范比如提交信息格式、代码审查清单。这样分层的好处是通用规范改一次所有项目都受益项目特有规范各管各的互不干扰。7.2 让 skill 成为团队知识沉淀的载体skill 其实是个很好的知识沉淀工具。团队里那些老人都知道但新人不知道的隐性规范写进 skill 就显性化了。而且这份知识同时服务人和 agent新人读一遍 skill 就能快速上手agent 加载后也能按规范干活。我现在的习惯是每次 code review 发现一个反复出现的问题就想想是不是该写进 skill。如果是通用问题写进团队级 skill如果是项目特有写进项目级。这样 skill 体系会随着项目一起成长越来越贴合实际需求。7.3 后续可以怎么扩展skill 体系搭起来后还能往几个方向扩展。一是跟 CI 打通提交前自动校验代码是否符合 skill 里的规范不符合就拦下来。二是做 skill 的测试写一些典型任务跑一遍看 agent 是否按 skill 执行确保 skill 没写错。三是按角色分 skill前端、后端、测试各有一套agent 根据当前任务的角色加载对应的。这些扩展不是必须的但如果你团队规模上来了值得考虑。我个人的体会是skill 体系这东西起步简单上限很高。一开始就写几个最痛的规范用起来然后慢慢迭代比一上来就想搞个大而全的体系要靠谱得多。