1. 从每次都要重新教AI说起agent-skills到底在解决什么如果你最近半年一直在用 Claude Code、Cursor 这类 AI coding agent 干活大概率经历过这么一种崩溃明明上周才跟它讲过我们这个项目的接口返回值统一用{code, data, message}三层结构这周开个新会话它又给你返回一个裸数组明明团队代码规范里写死了禁止在 service 层直接拼 SQL它还是照拼不误。你只能把那一大段上下文再贴一遍贴到自己都烦。agent-skills这个项目本质上就是冲着这个痛点去的。它做的事情用一句话概括把你反复教给 AI 的那些事沉淀成可复用、可版本管理、可跨会话加载的技能包让 agent 在需要的时候自动把对应的能力调起来而不是靠你每次手动喂 prompt。这里要先厘清一个容易混淆的概念。很多人第一次听到 skills 会以为是插件市场那种装一个功能多一个按钮的东西其实不是。在 Claude Code 这套体系里skill 更接近一份结构化的能力说明书它用 Markdown 描述什么场景下该用我用我的时候按什么步骤来有哪些坑不能踩再配合可选的脚本、模板、参考文件。Agent 读到这份说明书就知道遇到对应任务该怎么干。它不改变模型本身改变的是模型在特定任务上的行为模式。那agent-skills这个仓库/项目扮演什么角色它更像是一个技能的组织与分发层。你可以把它理解成技能的家统一存放、统一命名、统一加载。它要解决的不是怎么写一个 skill那是 Claude Code 官方文档的事而是当我有十几个 skill、要在多个项目、多个 agent 客户端之间共享时怎么管得住。适合谁来参考这篇内容三类人最对口已经在用 Claude Code 或 Cursor 做日常开发但还在靠复制粘贴 prompt 维持一致性的开发者。你会立刻感受到技能化带来的效率差。团队里负责工程规范落地的人。把规范写成 skill比写一份没人看的 wiki 有效得多因为 agent 会真的去执行。想搞清楚 AI coding agent 能力边界的技术负责人。理解 skill 机制才能判断哪些活能交给 agent、哪些必须人工兜底。需要提前说明的是agent-skills这类项目本身还在快速演进不同版本、不同客户端的加载方式差异不小。下面我讲到的目录结构、加载逻辑、CLI 用法都是基于当前主流实践的合理还原具体到你的环境务必以实际版本的行为为准。我会在关键处标注哪些是通用原理、哪些是版本相关、需自行验证。2. Skill 的解剖学一份 Markdown 凭什么能改变 agent 行为要玩转agent-skills先得把单个 skill 的内部结构吃透。不然你只会照抄别人的模板遇到加载不生效、触发不准确的问题就抓瞎。2.1 SKILL.md 的头部元数据name 和 description 是触发器一个标准的 skill 目录长这样my-skill/ ├── SKILL.md # 必需技能主文件 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板、静态资源核心是SKILL.md。它的开头是一段 YAML frontmatter通常至少包含两个字段--- name: api-response-convention description: 当需要编写或修改后端接口的返回值结构时使用。统一采用 {code, data, message} 三层格式code 为业务状态码data 为业务数据message 为提示信息。 ---这两个字段是整个机制里最容易被低估的部分。description不是给人看的简介而是给 agent 看的触发条件。Agent 在决定要不要加载这个 skill时主要就是拿当前任务去匹配所有 skill 的 description。所以 description 写得好不好直接决定 skill 会不会在该触发的时候触发。我踩过的坑一开始我把 description 写成这是一个关于接口规范的技能结果 agent 十次有八次想不起来用它。后来改成当需要编写或修改后端接口的返回值结构时使用命中率立刻上来了。区别在于前者是名词性描述后者是场景性描述。Agent 匹配的是场景不是主题。提示description 里尽量包含当……时使用这类触发语并把你实际会说的关键词比如接口返回值响应体都塞进去。这本质上是在做关键词召回优化。2.2 正文部分写给 agent 的操作手册frontmatter 之后就是正文用 Markdown 写。这部分才是真正指导 agent 干活的内容。一份好的 skill 正文结构上通常包含适用场景与不适用场景明确边界避免 agent 滥用。操作步骤分步骤写清楚越具体越好。正例与反例给出代码片段让 agent 有样学样。常见错误把你知道的坑写进去这是 skill 相对普通 prompt 的最大增值点。举个具体的例子一个数据库迁移skill 的正文可能是这样## 适用场景 需要新增、修改数据库表结构时。 ## 不适用场景 仅查询数据、不涉及 schema 变更时不要使用本技能。 ## 操作步骤 1. 在 migrations/ 目录下新建文件命名格式为 YYYYMMDDHHMMSS_描述.sql 2. 迁移脚本必须包含 up 和 down 两部分 3. 新增字段必须设置默认值或明确标注允许 NULL 4. 涉及大表加索引时必须使用 CONCURRENTLYPostgreSQL ## 反例 不要在已有迁移文件上直接修改历史迁移一经提交不可变。你会发现这跟写给人看的规范文档几乎一样。这正是 skill 的精妙之处它把团队规范和agent 行为用同一种载体统一了。规范文档人可能不看但 agent 一定会读。2.3 渐进式披露为什么 skill 不会把上下文撑爆很多人有个疑问如果我装了 20 个 skill每个正文几千字agent 的上下文窗口不就炸了这就是 skill 机制设计上最聪明的地方——渐进式披露progressive disclosure。Agent 在初始阶段只加载所有 skill 的name和description这部分很轻量只有当某个 skill 被判定为相关时才把它的完整正文读进来。如果正文里还引用了references/下的详细文档那部分更是按需再读。这个分层加载的逻辑用生活化的类比就是你书架上摆了 20 本书你不需要把 20 本书全背下来只需要记住每本书的书名和一句话简介。真要用到某本时再翻开来细读。理解这一点对写 skill 有直接的指导意义description 要精炼但信息密度高因为它是常驻内存的。正文可以写详细因为它只在触发时加载。超长的参考资料放references/正文里用相对路径引用让它按需读取。2.4 scripts 与 assets让 skill 从会说到会做纯 Markdown 的 skill 只能指导 agent怎么写代码但有些任务需要真正执行命令。这时候scripts/就派上用场了。比如一个生成 changelog的 skill可以在scripts/下放一个gen_changelog.py正文里写运行python scripts/gen_changelog.py --since tag生成变更日志。Agent 在执行时会调用这个脚本而不是自己现编一段可能出错的逻辑。这里有个实操心得脚本要写成幂等的、参数化的、有清晰 --help 的。因为 agent 调用脚本时很多时候是试探性的它需要从--help输出里理解怎么用。脚本报错信息也要写清楚agent 会读报错来调整调用方式。3. 用 skills CLI 把技能装进项目一次讲清加载路径理解了单个 skill 的结构接下来是agent-skills项目最核心的价值——怎么把这些 skill 组织起来并让 agent 找到它们。这部分是实操重灾区我见过太多人卡在skill 写好了但 agent 死活不加载。3.1 三个层级的加载位置项目级、用户级、插件级Claude Code 这类客户端查找 skill 时通常会扫描几个固定位置。以当前主流实践为例版本相关需自行验证层级典型路径适用场景项目级项目根/.claude/skills/只在本项目生效随代码库提交团队共享用户级~/.claude/skills/本机所有项目生效个人通用技能插件级由插件系统管理通过插件市场分发的技能包agent-skills项目通常就是围绕项目级这个位置做文章。它的思路是把技能集中放在仓库里某个目录比如skills/然后通过 CLI 或软链接的方式把它们同步/挂载到.claude/skills/下。为什么要多这一层因为直接往.claude/skills/里塞东西有几个问题不好版本管理.claude/目录经常被 gitignore技能就丢了。不好跨客户端复用Cursor、其他 agent 客户端可能认不同的路径。不好组织技能一多平铺在一个目录里就乱了。agent-skills相当于在技能源和客户端加载点之间加了一个中间层让技能可以集中维护、按需分发。3.2 skills CLI 的典型用法假设你已经把agent-skills仓库 clone 到本地典型的操作流程大致是这样命令为示意具体以项目 README 为准# 查看当前可用的技能列表 skills list # 把某个技能安装到当前项目 skills install api-response-convention --target ./.claude/skills/ # 批量安装某个分类下的所有技能 skills install --category backend --target ./.claude/skills/ # 查看某个技能的详情 skills info api-response-convention安装的本质通常是把技能目录复制或软链接到目标路径。这里有个关键选择复制还是软链接。复制技能内容固化到项目里随项目走团队其他人 clone 下来就有。缺点是源技能更新了项目里的不会自动同步。软链接项目里的技能指向源目录源更新即生效。缺点是团队其他人如果没有同样的源目录链接就断了。我的建议是团队共享的规范类技能用复制个人效率类技能用软链接。前者要的是稳定和可复现后者要的是随时更新。3.3 加载不生效的排查链路这是最高频的问题。我按排查顺序给你一条完整链路第一步确认路径对不对。不同客户端、不同版本认的目录可能不一样。Claude Code 认.claude/skills/但有些工具认.agent/skills/或别的。先去看你所用客户端的官方文档确认加载路径。第二步确认目录结构对不对。常见错误是把SKILL.md放错层级。正确结构是skills/skill-name/SKILL.md而不是skills/SKILL.md。每个技能必须有自己的子目录。第三步确认 frontmatter 格式对不对。YAML 对缩进敏感name和description必须顶格冒号后面要有空格。我见过有人写成name:api-response冒号后没空格YAML 解析直接失败skill 静默不加载还不报错。第四步确认 description 能不能被匹配上。如果前三步都对但 agent 就是不触发那多半是 description 写得不够场景化。临时验证方法在对话里直接说请使用 xxx 技能看它能不能加载。能加载说明是触发问题不能加载说明是配置问题。第五步看客户端日志。大多数客户端在启动时会打印加载了哪些 skill。如果日志里没有你的技能回到第一步。注意skill 加载失败往往是静默的不会弹错误提示。所以每次新增 skill 后养成先验证加载、再验证触发的习惯别等到用的时候才发现没生效。4. 写出一个agent 真的会用的 skill从触发到执行的完整设计装得上只是第一步用得好才是本事。这一节讲怎么设计一个高质量的 skill让 agent 在该用的时候用、用的时候不出错。4.1 触发设计description 的写法决定一切前面提过 description 是触发器这里展开讲怎么写。核心原则是用 agent 能匹配的语言而不是你习惯的语言。对比一下写法问题改进接口规范技能名词性无场景当需要编写或修改后端接口返回值结构时使用帮助处理数据库太宽泛容易误触发当需要新增或修改数据库表结构migration时使用代码审查相关模糊agent 不知道何时用当需要审查 PR 中的代码变更、检查是否符合团队规范时使用一个实用技巧把你平时会说的口语化指令写进 description。比如你经常说帮我加个接口那 description 里就带上新增接口编写接口这类词。Agent 匹配的是语义相似度你喂的词越贴近真实使用场景命中率越高。另一个技巧是控制触发范围。description 写太宽skill 会在不相关的时候被加载浪费上下文还可能误导 agent写太窄又该触发时不触发。我的经验是宁可稍微窄一点然后在正文里用不适用场景兜底。因为误触发比不触发更麻烦——不触发你手动喊一声就行误触发可能让 agent 在错误的方向上跑偏。4.2 正文设计把隐性知识显性化Skill 相对普通 prompt 的最大价值是它能承载隐性知识——那些老手觉得理所当然、但新手包括 AI不知道的细节。举个例子一个写单元测试的 skill普通 prompt 可能就写请为这个函数写单元测试。但一个高质量 skill 会写## 测试编写规范 1. 测试文件命名被测文件名.test.ext与被测文件同目录 2. 每个测试用例必须包含三段Arrange准备、Act执行、Assert断言用空行分隔 3. 禁止在测试中使用真实网络请求必须 mock 4. 边界值必须覆盖空值、零值、最大值、最小值 5. 测试描述用中文格式为应该……当……时 ## 常见错误 - 不要在测试里写 console.log 调试用断言 - 不要测试私有方法只测公开接口 - 一个测试只断言一件事避免一个测试里塞十个 assert这些内容你让一个资深工程师口头讲他能讲出来但你不写下来AI 就不知道。Skill 的本质就是把团队里口口相传的经验变成AI 可读的资产。4.3 用 references 拆分长文档如果一个 skill 的正文超过几百行就该考虑拆分了。把详细参考资料放到references/下正文里只保留核心步骤和引用。比如一个API 设计skillapi-design/ ├── SKILL.md └── references/ ├── error-codes.md # 完整错误码表 ├── pagination.md # 分页规范详解 └── versioning.md # 版本管理策略SKILL.md正文里写错误码定义参见references/error-codes.mdagent 需要时再去读。这样既保证了正文轻量又不丢失细节。这里有个坑引用路径要用相对路径且要确保 agent 能解析。有些客户端对路径解析比较严格用绝对路径或者带~的路径可能读不到。统一用相对于 skill 根目录的路径最稳。4.4 版本管理与团队协作Skill 是要演进的。团队规范变了skill 得跟着改。所以agent-skills这类项目通常会把技能纳入 git 管理走正常的 PR 流程。我的实践是每个 skill 一个目录改动走 PR方便 review 和追溯。在 SKILL.md 里加一个version字段如果客户端支持或者用 git tag 标记。重大变更写 changelog让用的人知道行为变了。团队协作里最容易出的问题是技能漂移——不同人本地装了不同版本的 skill行为不一致。解决办法就是项目级技能随代码库提交大家用同一份。个人级技能才允许各自维护。5. 跨客户端复用Claude Code、Cursor 之间的技能迁移agent-skills的另一个价值点是它试图解决技能锁定问题。你为 Claude Code 写的 skill能不能在 Cursor 里用反过来呢5.1 不同客户端的技能机制差异先说结论目前各家客户端的 skill 机制并不完全兼容但核心思路趋同。Claude Code 的 skill 机制相对成熟有明确的SKILL.md规范、渐进式披露、脚本执行能力。Cursor 这边早期主要靠.cursorrules或.cursor/rules/目录下的规则文件后来也逐步引入了更结构化的能力。两者的差异主要在维度Claude CodeCursor主文件SKILL.md.mdc / .cursorrules元数据YAML frontmatter部分支持 frontmatter触发机制description 语义匹配规则匹配 手动 引用脚本执行支持支持通过终端加载路径.claude/skills/.cursor/rules/agent-skills这类项目的思路通常是用一套源格式Markdown frontmatter维护技能再通过转换/同步工具适配到不同客户端。这样你写一次多处能用。5.2 迁移时的实际取舍理想很美好实操有取舍。我迁移过一批 skill几点体会第一触发机制不同description 要分别优化。Claude Code 靠语义匹配description 要写得像人话Cursor 的规则匹配更偏关键词description 里要把关键词堆足。同一份技能两边的 description 可能得微调。第二脚本路径要小心。如果你的 skill 里有脚本脚本里的路径假设比如假设工作目录是项目根在不同客户端下可能不成立。稳妥做法是脚本内部用相对自身位置的路径解析而不是依赖 cwd。第三能力边界不同别硬套。有些 skill 依赖 Claude Code 特有的能力比如特定的工具调用迁到 Cursor 可能水土不服。这种就别强求保留在原生环境用。5.3 一个务实的跨端方案如果你确实需要跨端我的建议是分层维护核心层纯 Markdown 的规范类技能不含脚本、不依赖特定工具这部分最容易跨端复用。适配层针对每个客户端写薄薄的适配文件引用核心层内容。专属层依赖特定客户端能力的技能各自维护不追求复用。这样 80% 的通用规范能复用20% 的专属能力各管各的性价比最高。6. 那些文档不会告诉你的坑我的踩坑清单最后这部分是我在实际用agent-skills和类似机制时踩过的坑按血泪程度排序。6.1 坑一skill 太多导致触发混乱一开始我很兴奋把能想到的都写成 skill装了二十多个。结果 agent 经常在写接口的时候触发了数据库迁移技能在改配置的时候触发了测试编写技能。原因是 skill 之间的 description 语义有重叠agent 匹配时看花了眼。解法控制数量合并同类项。真正高频、边界清晰的技能保留低频的合并成一个大技能里的不同章节。我的经验是单个项目 5 到 10 个 skill 比较舒服超过 15 个就要警惕触发混乱。6.2 坑二description 里的万能词导致误触发我有个 skill 的 description 里写了当需要处理数据时使用。结果 agent 只要碰到数据两个字就想加载它包括写个简单的变量赋值。处理相关涉及这类万能词是触发污染源能删就删。解法description 里用具体的动作 具体的对象比如当需要编写 SQL 查询语句时使用而不是当需要处理数据库相关操作时使用。6.3 坑三脚本没有错误处理agent 卡死我写过一个 skill里面有个脚本正常情况跑得挺好。但有次输入格式不对脚本直接抛了个 Python tracebackagent 读不懂就在那儿反复重试烧了一堆 token。解法脚本必须做输入校验错误信息要人类可读 agent 可理解。比如不要抛KeyError: foo而是打印错误缺少必需参数 foo用法python script.py --foo value。Agent 读到这种信息就知道该怎么调整。6.4 坑四把 skill 当 prompt 用写得太随意Skill 和 prompt 最大的区别是skill 是长期资产prompt 是一次性消耗品。我一开始用写 prompt 的心态写 skill随手写几句就完事结果用的时候发现 agent 理解得七零八落。解法把 skill 当产品文档写。想象你写完之后一个完全不了解背景的新人AI要照着它干活你得写到他能独立完成的程度。这个标准一立质量立刻不一样。6.5 坑五忽略 skill 的负向指令新手写 skill 只写要做什么不写不要做什么。但 agent 很听话你不说不要它就可能做出你不想看到的事。比如你写生成接口文档它可能顺手把接口实现也改了。解法每个 skill 都加一段不适用场景或禁止事项。明确告诉 agent 边界在哪。这跟带新人一个道理你不划红线他就自由发挥。6.6 坑六技能更新后没通知团队有次我改了一个核心 skill 的行为但没告诉团队。结果同事那边 agent 行为突然变了排查半天才发现是 skill 更新了。解法技能变更走 PR 通知重大变更在团队频道同步。把 skill 当代码管就得有代码管理的纪律。7. 从会用到用好我对 agent-skills 的一点判断用了一段时间下来我对agent-skills这类项目的价值判断是它解决的是 AI coding agent 从玩具到工具的关键一跃。没有 skill 机制的时候agent 的能力上限取决于你当次 prompt 的质量本质上是一次性的。有了 skill能力可以沉淀、可以复用、可以团队共享这才让它真正进入工程化的范畴。但它也不是银弹。Skill 能规范的是已知的、可描述的任务对于那些需要临场判断、需要跨领域权衡的复杂问题skill 帮不上太多忙。所以我的用法是把重复性的、有明确规范的任务 skill 化把探索性的、需要创造力的任务留给自己和 agent 实时协作。如果你刚开始接触我的建议是从一个最痛的场景入手——就是你每次都要重复交代的那件事把它写成第一个 skill。跑通写 skill → 装 skill → 触发 skill → 验证效果这个完整闭环你就理解这套机制了。剩下的就是不断往这个框架里填内容。至于agent-skills这个具体项目它的目录组织、CLI 用法、跨端适配策略都还在演进。别指望一次学到位跟着版本走遇到问题看 README 和 issue比背文档管用。真正稳定的是前面讲的那些原理description 是触发器、正文是操作手册、渐进式披露控制上下文、脚本扩展能力边界。这些搞懂了换哪个客户端、哪个版本你都能快速上手。