agent-skills 实战：用 skills CLI 为 Claude Code 和 Cursor 构建可复用技能包

1. 从每次都要重新教AI说起agent-skills到底在解决什么如果你最近半年一直在用 Claude Code、Cursor 这类 AI coding agent 写代码大概率经历过这种循环新开一个会话agent 对你的项目结构一无所知你得重新告诉它这个仓库用 pnpm 不用 npm测试跑 vitest 不跑 jest提交信息要遵循 Conventional Commits。讲完一遍会话结束下次再来一遍。agent-skills 就是冲着这个痛点去的。它本质上是一套给 AI coding agent 用的技能包规范与配套 CLI。你可以把它理解成给 agent 装的一本随身手册把项目约定、领域知识、常用操作流程写成结构化的 skill 文件agent 在需要的时候自动加载对应技能而不是靠你在对话里反复口述。关键词里的skills CLI就是操作这套技能包的命令行入口而Claude Code、Cursor是目前最主要的两个宿主环境。我最初接触这个概念时的第一反应是这不就是换个名字的 prompt 模板吗实际用下来发现差别很大。prompt 模板是静态文本你得手动粘贴skill 是带元数据、带触发条件、能被 agent 主动检索和调用的结构化单元。前者是你喂给它后者是它自己找。这篇文章适合三类人看一是天天用 Claude Code / Cursor 但还在靠复制粘贴 prompt 干活的开发者二是团队里想把 AI 编码规范沉淀下来的技术负责人三是单纯好奇skills 这套东西到底怎么落地的观望者。我会从目录结构、CLI 用法、和宿主 agent 的配合方式一直讲到我自己踩过的坑尽量把能直接抄的部分写清楚。需要先说明一点agent-skills 这类工具迭代非常快具体命令和字段可能随版本变化。下面涉及配置的部分我会标注哪些是稳定约定、哪些是以你本地版本为准你照着做的时候留意一下--help输出。2. 拆开一个 skill 看目录结构、元数据与触发逻辑2.1 一个 skill 最小长什么样先别急着装 CLI理解 skill 的物理形态更重要。一个 skill 通常就是一个目录里面至少有一个描述文件多数实现用SKILL.md或skill.yaml加上可选的脚本、模板、参考资料。结构大致是这样skills/ commit-convention/ SKILL.md examples.md api-error-handling/ SKILL.md scripts/ check_error_codes.pySKILL.md里最关键的是头部元数据一般包含name、description有些实现还支持triggers、when_to_use之类的字段。description不是写给人看的装饰它是 agent 决定要不要加载这个技能的主要依据。这一点很多人第一次写会忽略随手写一句处理提交信息结果 agent 死活不触发。2.2 description 为什么决定了技能能不能被用上我做过一个对比实验。同一个技能只改 descriptiondescription 写法agent 主动触发率我本地 20 次任务测试提交相关2/20当用户要求生成 git commit message、检查提交规范、或提到 Conventional Commits 时使用17/20差距非常明显。原因在于 agent 的检索逻辑本质上是语义匹配它拿当前任务去和所有 skill 的 description 做相似度比较。你写得太抽象匹配不上你把触发场景、关键词、动作都写进去命中率立刻上来。所以我的经验是description 要写成什么时候用我而不是我是什么。这跟写函数注释是反过来的——注释描述功能skill description 描述调用时机。2.3 技能加载的两种模式主动检索 vs 显式调用实际使用中skill 被用上有两条路径。第一条是自动检索agent 在处理任务时扫描可用 skill 列表根据 description 匹配度决定加载哪个。Claude Code 里这套机制相对成熟你几乎感觉不到它在选技能只觉得它突然就懂你的项目了。第二条是显式调用你在对话里直接点名比如用 commit-convention 这个 skill 帮我写提交信息。当自动检索不稳定或者技能比较冷门时显式调用是兜底手段。提示如果你发现某个 skill 总是不触发先别怀疑工具坏了九成是 description 写得太泛。把它改成当……时使用的句式再测一遍。2.4 技能粒度宁可小不要大新手最容易犯的错是写一个万能 skill把代码规范、测试流程、部署步骤全塞进去。结果就是 agent 加载了一大坨内容真正相关的只有两行反而稀释了注意力。我的建议是一个 skill 只干一件事。比如生成 commit message和检查 PR 描述完整性就该拆成两个。粒度小带来的好处是description 可以写得很精准触发准确率高维护时改动范围小不同项目之间还能复用。代价是 skill 数量会变多这时候就需要目录分类和命名规范来管理下一节讲 CLI 的时候会说到。3. skills CLI 实操安装、初始化到跑通第一个技能3.1 安装前的环境确认skills CLI 一般通过包管理器分发。以常见的 Node 生态为例先确认版本node -v npm -vNode 版本建议 18 以上低版本在解析某些依赖时容易出问题。装完之后验证skills --version skills --help--help的输出值得认真看一遍不同版本的子命令差异挺大。我见过有人照着半年前的教程敲命令结果命令早就改名了白折腾半小时。3.2 初始化技能目录大多数 CLI 提供init类命令来生成骨架skills init它会在当前目录创建skills/文件夹和一个示例技能。如果你是在已有项目里接入注意别让它覆盖你手写的目录——先git status看一眼确认新增文件范围再继续。初始化之后我习惯先做一件事把示例技能删掉自己从零写一个最简单的。因为示例往往带一堆你用不上的字段留着反而干扰理解。3.3 写第一个能跑通的技能拿生成符合规范的 commit message举例。新建skills/commit-convention/SKILL.md--- name: commit-convention description: 当用户要求生成 git commit message、检查提交信息格式、或提到 Conventional Commits 规范时使用 --- # Commit Convention 本项目提交信息遵循 Conventional Commits。 ## 格式 type(scope): subject ## type 取值 - feat: 新功能 - fix: 修复 - docs: 文档 - refactor: 重构 - test: 测试 - chore: 构建/工具 ## 规则 - subject 用中文不超过 50 字 - 不写句号结尾 - scope 用模块名可省略写完保存然后让 agent 处理一次提交任务观察它是否自动套用了这个格式。3.4 验证技能是否真的被加载这一步很多人跳过结果技能没生效也不知道。验证方法有两个一是看行为让 agent 生成一条 commit message如果格式对了说明加载成功。二是看日志部分 CLI 和宿主支持输出技能加载日志比如skills list --verbose或者 agent 侧的调试开关。能看到loaded skill: commit-convention就实锤了。如果没生效按这个顺序排查description 是否够具体 → 文件路径是否在 agent 扫描范围内 → 元数据字段名是否拼错 → 宿主是否需要重启会话。3.5 常用 CLI 命令速查命令作用备注skills init初始化技能目录已有目录时注意覆盖风险skills list列出可用技能加--verbose看详情skills validate校验技能文件格式元数据写错时能报出来skills add name添加技能部分版本支持从仓库拉取skills remove name移除技能谨慎操作先备份注意命令名和参数以你本地skills --help为准。这类工具版本迭代快教程和实际对不上是常态别硬套。4. 让 Claude Code 和 Cursor 真正吃上这套技能4.1 两个宿主的接入方式不一样Claude Code 和 Cursor 虽然都支持 agent 能力但接入 skill 的路径不同。Claude Code 侧通常是把 skills 目录放在项目根或用户配置目录下它启动时会扫描。有些版本支持在配置文件里显式声明技能路径。我一般放在项目根目录的skills/跟着仓库走团队共享方便。Cursor 侧接入方式更依赖它的规则系统Rules和上下文机制。你可以把 skill 内容转成 Cursor 能识别的规则文件或者通过 MCP 之类的扩展机制挂载。具体怎么挂取决于你用的 Cursor 版本和是否开了相关实验特性。4.2 项目级 vs 用户级放哪儿有讲究这是个容易纠结的点。我的判断标准很简单项目级放仓库里跟具体项目强相关的约定比如这个仓库的目录结构、测试命令、提交规范。好处是团队共享新人拉下来就有。用户级放个人配置目录跨项目通用的技能比如如何写清晰的 PR 描述如何做代码审查。好处是走到哪都能用。混着放会导致两个问题项目里塞了太多通用技能仓库变臃肿个人目录里放了项目专属技能换个项目就失效还占地方。4.3 团队协作时的同步问题skills 跟着仓库走就必然遇到同步问题。我的做法是把skills/纳入版本控制和代码一起 review。在 README 或 CONTRIBUTING 里写清楚技能目录的用途和新增流程。定期清理失效技能——项目重构后很多技能描述的场景已经不存在了留着只会干扰 agent 检索。第 3 点特别重要。我见过一个仓库积累了三十多个技能其中一半是历史遗留agent 检索时经常匹配到过时技能输出反而变差。技能不是越多越好是越准越好。4.4 和现有 Rules / 配置的边界很多人会问我已经有 Cursor Rules 了还需要 skills 吗我的理解是两者定位不同。Rules 更像始终生效的背景约束比如这个项目用 TypeScript 严格模式。Skills 更像按需调用的操作手册比如当需要写数据库迁移时按这个流程来。前者常驻后者触发。所以不是替代关系是互补。你可以把稳定的、全局的约定放 Rules把场景化的、带步骤的流程放 Skills。硬要合并成一种要么 Rules 臃肿到每次都占满上下文要么 Skills 触发不稳定。5. 我踩过的坑从技能不触发到技能互相打架5.1 技能写了但 agent 视而不见这是最高频的问题。我最初的排查链路是这样的第一步确认文件真的被扫描到了。用skills list看列表里有没有它。没有的话是路径问题。第二步确认元数据格式对。YAML 头部对缩进敏感多一个空格都可能解析失败。用skills validate跑一遍最省事。第三步也是最容易被忽略的——description 的语义匹配。我有个技能叫数据库迁移助手description 写的是处理数据库相关任务。结果 agent 在做给用户表加一个字段时压根没匹配上因为它检索的是加字段这个动作而我的描述里没有这个词。改法很直接把 description 改成当需要新增/修改数据库表结构、编写 migration 文件、或提到 schema 变更时使用。改完立刻生效。5.2 两个技能抢同一个任务技能多了之后会出现打架。比如我同时有api-error-handling和backend-conventions两个技能前者讲错误码规范后者也顺带提了错误处理。agent 处理一个接口报错任务时可能加载了后者给出的建议和前者冲突。解决办法有两个一是合并把重叠内容收敛到一个技能里二是明确边界在 description 里写清楚各自的适用范围比如 backend-conventions 里注明错误处理细节见 api-error-handling 技能。我倾向于合并。技能之间的引用关系越复杂agent 越容易迷糊。宁可一个技能稍微大一点也别搞出一堆互相引用的碎片。5.3 技能内容太长把上下文挤爆有一次我写了个完整部署流程技能洋洋洒洒两千字包含所有环境的配置。结果 agent 加载后留给实际任务的上下文空间被压缩回答质量明显下降。教训是技能里只放 agent 决策需要的信息不放执行细节。比如部署流程技能里写生产环境用 A 流程预发用 B 流程具体命令见 scripts/deploy.sh把长命令丢到脚本文件里agent 需要时再去读。这样技能本身保持精简上下文压力小很多。5.4 版本升级后技能全失效这个坑比较隐蔽。某次 CLI 升级后元数据字段名变了我所有技能的 description 都不被识别agent 集体失忆。当时排查了半天最后是翻 changelog 才发现的。从那以后我养成了一个习惯升级 CLI 或宿主 agent 之后先跑一遍skills validate再随便测一个技能是否触发。花两分钟省得后面抓瞎。6. 把技能写活几个提升触发率的实战技巧6.1 description 的三要素写法经过反复试我总结出一个 description 模板触发场景 关键词 动作。举个例子当用户要求生成 API 文档、更新接口说明、或提到 OpenAPI/Swagger 时使用负责从代码注释提取接口信息并生成规范文档。触发场景要求生成 API 文档、更新接口说明关键词OpenAPI、Swagger动作从代码注释提取并生成文档三要素齐全命中率比只写API 文档助手高出一个量级。6.2 用示例反推技能边界写技能时我有个习惯先想三个应该触发的任务和三个不应该触发的任务写进技能文件的注释里不一定要给 agent 看主要是帮自己理清边界。比如 commit-convention 技能应该触发不应该触发帮我写提交信息解释一下这个 commit 改了什么检查我的提交格式回滚上一次提交生成符合规范的 commit查看提交历史右边这些任务虽然也涉及 commit但不需要提交规范知识。想清楚这个边界description 就不会写得太宽。6.3 技能里的反例比正例更有用大多数技能只写应该怎么做但 agent 犯错往往是因为不知道什么不能做。我在技能里会专门加一段常见错误比如## 常见错误 - 不要在 subject 里写修复了一些问题这种模糊描述 - 不要用 fix 表示新功能那是 feat - 不要在一条提交里混合多个不相关的改动这段内容对 agent 的约束效果比正面规则还明显。因为正面规则它可能理解偏差但明确的反例它更容易对齐。6.4 定期做技能体检我大概每个月会做一次技能体检流程是skills list列出所有技能。逐个问自己这个技能最近一个月被触发过吗描述的场景还存在吗没触发过的要么改 description要么删掉。触发过但效果不好的看是内容问题还是粒度问题。这个习惯让我的技能库始终保持精简。技能库不是资产是负债——每多一个agent 检索时就多一分干扰。只有真正在用的才值得留。7. 技能之外这套思路还能怎么扩展agent-skills 表面上是给 AI coding agent 用的但它背后的思路——把隐性知识结构化、让 agent 按需检索——适用范围比写代码广得多。我现在会把一些非编码的场景也做成技能。比如周报生成把周报的格式要求、数据来源、常见措辞写成技能agent 处理周报任务时自动套用。会议纪要整理同理把输出结构、待办提取规则写进去。再往远一点想团队里的新人上手文档其实也可以技能化。传统文档是写给人看的线性阅读技能是写给 agent 看的按需触发。两者不冲突但后者在 AI 辅助工作流里效率更高。不过有个前提技能化的知识必须是相对稳定的。如果某个流程每周都在变做成技能就是给自己找麻烦改都改不过来。判断标准是这个知识半年内会不会大改不会就值得沉淀。最后分享一个我自己的体会。刚开始用 agent-skills 时我总想着一次写全结果写出来的技能又长又泛触发率还低。后来改成先写最小可用版本用起来再补反而顺了。技能这东西和代码一样是迭代出来的不是设计出来的。先让它跑起来再根据实际触发情况一点点调 description、补反例、拆粒度比一开始就追求完美靠谱得多。