agent-skills 实战：为 AI coding agent 构建可复用技能层

1. 从每次都要重新教AI说起agent-skills到底在解决什么如果你用过 Claude Code、Cursor 这类 AI coding agent大概率经历过这样的循环新开一个会话agent 对你的项目结构一无所知你得重新解释一遍我们的 API 返回格式统一用{code, data, message}数据库迁移必须走 Alembic 不能手改表提交信息要遵循 Conventional Commits。解释完这一轮活干完了会话关掉下次再来一遍。这个问题的本质不是模型不够聪明而是agent 缺少一个可持久化、可复用、可版本管理的技能层。agent-skills这个项目要解决的正是这件事——它给 AI coding agent 定义了一套标准化的技能组织方式让 agent 能够按需加载你预先写好的领域知识、操作流程和约束规则而不是每次都从零开始理解你的项目。我第一次接触这个概念是在给一个中型后端项目配置 Claude Code 的时候。项目里有 40 多个微服务模块每个模块的测试命令、部署脚本、日志路径都不一样。最初我的做法是把这些信息全塞进CLAUDE.md结果那个文件膨胀到 800 多行agent 每次会话都要吃掉大量上下文而且经常看漏关键约束。后来改用 skills 的方式拆分每个技能只在自己被触发时才加载上下文占用直接降了一个数量级agent 的执行准确率反而上去了。所以这篇文章适合谁看三类人一是已经在用 Claude Code 或 Cursor 但还在用大杂烩配置文件的开发者二是团队里负责制定 AI 编码规范、想让多个成员共享同一套 agent 行为标准的技术负责人三是单纯好奇skills CLI 到底是个什么东西、值不值得折腾的观望者。我会从目录结构、触发机制、CLI 操作、实战编写、踩坑排查几个角度把它讲透尽量让你看完就能上手写自己的第一个 skill。需要先说明一点agent-skills 目前主要围绕 Claude Code 的技能体系设计Cursor 对它的支持程度取决于版本和配置方式后文会具体区分。另外这个领域迭代很快我写的是我实测下来稳定的那套用法具体命令以你本地--help输出为准。2. 拆开一个 skill 看内部目录结构、元数据与渐进式加载2.1 skill 的最小构成单元一个 skill 本质上就是一个文件夹里面至少有一个SKILL.md文件。这个文件分两部分顶部的 YAML frontmatter 元数据和下面的 Markdown 正文。--- name: api-response-convention description: 当需要编写或修改 HTTP API 响应结构时使用。定义统一的 {code, data, message} 返回格式、错误码规范和分页字段。 --- # API 响应约定 所有接口必须返回如下结构 json { code: 0, data: {}, message: ok }code为 0 表示成功非 0 为业务错误码分页接口的data必须包含list、total、page、page_size禁止在data里嵌套code字段frontmatter 里最关键的两个字段是 name 和 description。name 是技能的唯一标识建议用短横线连接的英文小写description 决定了这个技能**什么时候被加载**——agent 会读取所有已安装技能的 description判断当前任务是否匹配匹配才把正文内容注入上下文。 这就是所谓的**渐进式加载progressive disclosure**元数据常驻、正文按需。你可以装几十个技能但只要 description 写得准每次会话真正吃进上下文的只有当前任务相关的那两三个。这一点是它和把所有规则堆进一个文件最本质的区别。 ### 2.2 description 是技能的灵魂不是摘要 很多人第一次写 skill 会把 description 写成这个技能介绍了 API 规范——这是错的。description 不是给人看的摘要而是给 agent 看的**触发条件**。它应该回答在什么情况下该用我。 对比一下 | 写法 | 问题 | 改进 | |------|------|------| | 介绍项目的 API 规范 | 没有触发场景agent 不知道何时加载 | 当编写、修改或审查 HTTP API 接口的响应结构时使用 | | 数据库相关 | 太宽泛几乎所有后端任务都会误触发 | 当需要编写数据库迁移脚本或修改表结构时使用 | | 测试 | 同上 | 当需要为新功能编写单元测试或修复失败测试时使用 | 我踩过的坑是早期给一个技能写了很宽泛的 description结果每次 agent 做任何后端任务都会把它加载进来白白占用上下文还偶尔干扰判断。后来我把 description 收窄到具体动作 具体对象误触发率明显下降。 提示description 里最好包含当……时使用这样的触发语并且明确列出动作动词编写、修改、审查、调试和对象API、迁移脚本、测试用例。这是实测下来最有效的写法。 ### 2.3 技能可以带附属文件 SKILL.md 不是孤立的。你可以在技能目录里放模板文件、示例代码、脚本然后在正文里引用它们api-response-convention/ ├── SKILL.md ├── templates/ │ └── response.go.tmpl └── examples/ └── paginated-response.json正文里可以写生成响应结构时参考 templates/response.go.tmpl。agent 在需要时会去读这些附属文件。这个设计的好处是正文保持精简只讲规则和意图大块的模板和示例放在外面进一步节省上下文。 我一般会把超过 30 行的代码模板、完整的配置文件样例、长表格都外置成附属文件。正文里只留什么时候用哪个文件的指引。这样即使一个技能被加载注入的 token 也可控。 ## 3. skills CLI 实操安装、列出、启用与卸载的完整链路 ### 3.1 安装位置与作用域 skills 的存放位置决定了它的作用范围。常见的有两个层级 - **用户级**放在用户主目录下的配置目录里Claude Code 通常是 ~/.claude/skills/对所有项目生效 - **项目级**放在项目根目录下的 .claude/skills/只对当前项目生效可以随代码仓库一起提交团队成员共享 我的建议很明确**跟具体项目强相关的技能放项目级通用的个人偏好放用户级**。比如这个项目的部署流程放项目级我习惯用某种提交信息格式放用户级。项目级技能进版本控制后团队里每个人拉下代码就自动获得同一套 agent 行为这是团队协作里最省事的一招。 ### 3.2 用 CLI 管理技能 skills CLI 提供了一套命令行操作核心命令大致如下不同版本可能有差异以 --help 为准 bash # 列出当前已安装/可用的技能 skills list # 查看某个技能的详情 skills show api-response-convention # 从某个来源安装技能 skills install source # 移除技能 skills remove api-response-conventionskills list是我用得最频繁的命令。它会列出所有技能及其 description我经常用它来检查是不是有技能的 description 写得太宽泛了。如果发现某个技能几乎每次任务都被列出来那基本可以判定它的触发条件需要收窄。skills install支持从本地路径或远程仓库安装。团队内部我一般会维护一个私有的技能仓库新成员入职时一条命令把整套团队规范装好比口头传达或者写文档靠谱得多——因为文档没人看但 agent 会强制执行。3.3 手动管理也完全可行CLI 不是必须的。因为 skill 就是文件夹你完全可以手动创建目录、写SKILL.md效果一样。CLI 的价值在于批量操作和来源管理。我个人的习惯是单个技能手写成批安装或团队同步时用 CLI。有一点要注意技能目录的命名和 frontmatter 里的name最好保持一致。我遇到过目录叫api-convention但 name 写成api-response-convention的情况某些版本的加载逻辑会以 name 为准导致skills show用目录名查不到。统一命名能省掉这类莫名其妙的排查。3.4 验证技能是否真的被加载写完技能最怕的是以为装上了其实没生效。验证方法有两个一是直接在会话里问 agent你现在加载了哪些技能如果配置正确它会列出当前可用的技能清单。二是故意触发让 agent 做一个应该匹配某技能的任务观察它的输出是否遵循了技能里的规则。比如你写了 API 响应约定就让 agent 生成一个接口看它返回的结构对不对。我一般两个都做。第一个确认技能被识别第二个确认内容被正确应用。只做第一个的话有可能技能加载了但 agent 没遵守那说明正文写得不够明确或者有冲突。4. 写一个真正好用的 skill从触发词到正文组织的经验4.1 先想清楚边界再动笔写技能之前我会先问自己三个问题这个技能覆盖的任务范围是什么它的边界在哪里什么情况不该触发它和已有技能会不会重叠边界不清是新手最容易犯的错。比如你写了一个代码审查技能又写了一个代码风格技能两者在检查命名规范这件事上就重叠了。agent 同时加载两个技能时如果规则有细微冲突行为就会不稳定。我的做法是一个技能只负责一类明确的任务风格检查归风格逻辑审查归逻辑宁可拆细也不要糅在一起。4.2 正文用规则 理由 反例三段式光给规则agent 容易机械执行加上理由它能在边界情况下做出合理判断加上反例它能避开常见错误。我写正文基本遵循这个结构## 规则 所有数据库变更必须通过迁移脚本禁止直接修改表结构。 ## 理由 直接改表会导致开发、测试、生产环境结构不一致且无法回滚。 ## 反例 不要执行 ALTER TABLE users ADD COLUMN age INT; 这样的裸 SQL。 正确做法是生成一个迁移文件包含 upgrade 和 downgrade 两个方向。实测下来理由这一段特别值钱。当 agent 遇到技能没明确覆盖的边界情况时它会根据理由去推断而不是死板地报错或者乱来。4.3 用祈使句别用描述句技能正文是给 agent 的指令不是给人看的说明文档。所以要用祈使句好生成响应时data 字段必须为对象不能为 null。差本项目的响应 data 字段通常是一个对象。通常一般建议这类词会让 agent 犹豫。规则就是规则用必须禁止始终来表述。只有真正存在多种合理选择的地方才用可以。4.4 控制单个技能的体量一个技能正文我一般控制在 100 到 300 行之间。太短说明规则没讲透太长说明这个技能承担了太多职责应该拆分。超过 300 行的技能加载时占用的上下文就很可观了违背了渐进式加载的初衷。如果内容确实多就外置成附属文件。正文只保留核心规则 文件指引。比如一个完整的部署技能正文讲清楚部署分几步、每步的意图、失败怎么处理具体的命令清单和配置模板放到scripts/和templates/里。4.5 一个完整的实战技能示例假设我们要给一个 Go 项目写新增 HTTP 接口的技能--- name: add-http-endpoint description: 当需要新增、修改 HTTP 接口路由或 handler 时使用。覆盖路由注册、参数校验、响应封装、错误处理四个环节。 --- # 新增 HTTP 接口 ## 步骤 1. 在 internal/router/ 下对应模块的路由文件里注册路由禁止在 main.go 里直接注册。 2. handler 放在 internal/handler/模块/ 下命名格式为 动作资源Handler。 3. 请求参数必须定义结构体并绑定校验标签禁止用 map[string]interface{} 接收。 4. 响应统一走 response.Success(c, data) 和 response.Fail(c, code, msg)禁止手写 c.JSON。 5. 错误必须记录日志并返回业务错误码禁止把底层错误直接透传给客户端。 ## 理由 路由集中注册便于排查冲突handler 分层便于测试统一响应封装保证前端解析逻辑一致错误码隔离避免泄露内部实现。 ## 反例 不要这样写 go func Handler(c *gin.Context) { var req map[string]interface{} c.BindJSON(req) c.JSON(200, req) }这样既没有参数校验也没有统一响应格式还泄露了原始请求。这个技能不到 60 行但把做什么、为什么、别做什么都讲清楚了。我把它放进项目级技能目录后团队里 agent 生成的接口代码风格立刻统一了。 ## 5. 当技能不生效时一条可复现的排查链路 技能写完不生效是最高频的问题。我整理了一条自己常用的排查链路按顺序走基本能定位。 ### 5.1 第一步确认文件位置和命名 先确认 SKILL.md 是不是在正确的目录下文件名大小写是否准确。Linux 和 macOS 对大小写敏感skill.md 和 SKILL.md 在某些加载逻辑里不是一回事。我见过有人把文件命名成 Skill.md结果死活加载不出来。 同时确认目录层级是 skills/技能名/SKILL.md还是直接 skills/SKILL.md前者才是标准结构每个技能一个子目录。 ### 5.2 第二步检查 frontmatter 格式 YAML frontmatter 对格式很敏感。常见错误 - 开头必须是 ---结尾也必须是 ---且都在单独一行 - name 和 description 后面是冒号加空格不能是中文冒号 - description 里如果有冒号整个值要用引号包起来否则 YAML 解析会出错 我踩过一次坑description 写成 当需要处理 API: 响应时使用中间那个英文冒号让 YAML 解析直接失败技能静默不加载也不报错。后来养成习惯description 里一律不用冒号或者用引号包起来。 ### 5.3 第三步验证 description 的触发匹配 如果文件没问题但技能还是不加载多半是 description 没匹配上。这时候把 description 临时改得宽泛一点看是否加载。如果宽泛版能加载、精确版不能说明你的触发词和 agent 实际理解的任务描述对不上。 解决办法是观察 agent 在任务中实际使用的措辞把 description 里的关键词往那个方向靠。比如 agent 总说实现一个 endpoint那 description 里就该出现 endpoint 这个词。 ### 5.4 第四步排查技能之间的冲突 多个技能同时加载时如果规则冲突agent 的行为会变得不可预测。典型症状是单独测试每个技能都正常一起用就出问题。 排查方法是临时禁用其他技能只留一个逐个测试。找到冲突的两个技能后要么合并要么明确各自的边界。我一般会在技能正文开头加一句本技能不覆盖 XXX那部分见 YYY 技能给 agent 一个明确的分工提示。 ### 5.5 第五步确认 agent 版本和配置 最后要确认你用的 agent 版本是否支持 skills。Claude Code 对 skills 的支持相对成熟Cursor 的支持情况要看版本有些版本需要通过特定配置开启。如果你在 Cursor 里怎么都加载不出来先查一下当前版本是否支持别在配置上死磕。 注意不同工具对 skills 的目录约定可能不同。Claude Code 用 .claude/skills/其他工具可能有自己的路径。跨工具使用时先确认目标工具的约定路径别想当然地复制。 ## 6. 团队协作与长期维护让技能库不腐烂 ### 6.1 技能进版本控制但要有 review 项目级技能目录提交到仓库后任何改动都会影响全团队的 agent 行为。所以技能文件的修改应该走 code review和改代码一样对待。我见过有人随手改了一个技能的 description结果全团队的 agent 突然开始在不该加载的时候加载这个技能排查了半天才发现是那次改动。 review 的重点是description 的触发条件有没有变宽正文规则有没有和现有技能冲突有没有引入和项目实际不符的约束 ### 6.2 定期清理失效技能 项目在演进技能会过期。比如某个模块重构了对应的技能还在讲旧结构agent 照着旧技能干活就会出错。我一般每个季度过一遍技能库删掉不再适用的更新结构变了的。 判断技能是否过期有个简单方法看它最近有没有被触发过。如果连续几个月都没被加载要么是任务场景消失了要么是 description 写得太偏没人触发。前者删掉后者修 description。 ### 6.3 技能命名和分类的约定 技能多了以后命名混乱会很痛苦。我的约定是领域-动作 或 领域-对象比如 db-migration、api-response-convention、test-unit。这样在 skills list 里一眼就能看出每个技能管什么。 如果技能超过 20 个可以考虑用子目录分类但要注意加载逻辑是否支持嵌套。有些工具只扫描一层目录嵌套太深会漏掉。这个要实测确认。 ### 6.4 把踩过的坑沉淀成技能 这是我觉得 skills 最有价值的用法之一**把团队反复踩的坑写成技能**。比如这个第三方库的某个方法在并发下不安全这个配置项改了之后必须重启某个服务这些知识以前散落在聊天记录和某个人脑子里现在写成技能agent 在相关任务里会自动提醒。 我团队里有个技能叫 known-pitfalls-payment专门记录支付模块的历史坑。每次有人让 agent 改支付相关代码这个技能就会被加载agent 会主动检查那些已知的雷区。上线事故率肉眼可见地下降了。 ## 7. 我实际用下来的一些体会 skills 这套东西最大的价值不是让 agent 更聪明而是让 agent 的行为可预期、可复用、可传承。模型能力再强它也不知道你项目的具体约定而技能就是把这些约定固化下来让每一次会话都站在同一个起点上。 我现在的习惯是每当发现自己在会话里重复解释同一件事超过两次就把它写成一个技能。这个触发条件很实用能保证技能库只沉淀真正高频、真正有价值的知识而不是变成另一个没人维护的文档坟场。 另外提醒一句别一上来就追求技能库的完备。先写两三个最痛的场景用起来感受一下触发和加载的实际效果再逐步扩展。我见过有人一口气写了三十个技能结果互相冲突、触发混乱最后全删了重来。小步快跑比一次性设计完美方案靠谱得多。