1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的“技能包”。你可以把它理解成一套标准化的“操作手册 可执行脚本 测试用例”的集合专门喂给 Claude Code、Cursor、Windsurf 这类 AI 编程代理让它们在特定任务上从“能聊两句”变成“真能干活”。这个项目解决的核心问题很具体AI coding agent 的通用能力很强但一到具体工程场景就掉链子。比如你让它“帮我加一个带分页的用户列表接口”它可能给你生成一堆看起来对、跑起来报错的代码。原因不是模型不行而是它缺少针对你项目结构、技术栈、代码规范的“技能约束”。agent-skills就是把这些约束沉淀成可复用、可版本管理的技能单元。适合谁看三类人最值得花时间一是已经在用 Claude Code 或类似工具做日常开发的工程师想把自己的经验固化成 agent 能执行的技能二是团队里负责搭建 AI 辅助开发流程的人需要一套可维护的技能库三是对 AI coding agent 底层机制好奇、想自己写 skill 的开发者。哪怕你只是刚装好 Claude Code理解这套东西也能让你少走很多弯路。我自己的体会是agent-skills 的价值不在“多”而在“准”。一个写得好的 skill能让 agent 在特定任务上的成功率从五五开提到八成以上这个提升是实打实的。2. 核心设计思路为什么是“技能”而不是“提示词”2.1 提示词的天花板在哪里大部分人用 AI coding agent 的方式是打开对话框敲一段自然语言等结果。这本质上是在写一次性提示词。提示词的问题在于它太依赖你当下的表达而且无法沉淀。你今天写了一段很精妙的提示让 agent 正确生成了数据库迁移脚本明天换个任务这段提示就废了。更麻烦的是提示词没有可测试性。你没法给一段提示词写单元测试也没法在 CI 里跑它。agent 输出对不对全靠你肉眼看。这在个人玩票阶段没问题一旦要团队协作、要规模化就完全撑不住。agent-skills的思路是把“提示”升级成“技能”。一个技能包含的不只是指令还有输入约束、执行步骤、验证逻辑、失败回退。它更像一个函数而不是一段话。2.2 技能包的三层结构我拆过几个比较成熟的 agent-skills 实现基本都遵循类似的三层结构元数据层技能名、适用场景、触发条件、依赖项。这层决定了 agent 什么时候该调用这个技能。指令层具体的操作步骤通常用结构化格式写比如分步骤的 markdown 或 YAML。这层是 agent 实际执行的“剧本”。验证层怎么判断任务完成了、结果对不对。这层最容易被忽略但恰恰是区分“玩具”和“工具”的关键。为什么这么分因为 agent 的执行是有状态、多轮次的。它需要先判断“这个任务我有没有对应技能”再“按步骤执行”最后“自检结果”。三层结构正好对应这三个阶段。2.3 和 test-driven-development 的关系热词里出现了test-driven-development这不是巧合。技能包天然适合 TDD 的工作流。你可以先写一个失败的测试用例描述“agent 应该能完成 X 任务”然后写技能让 agent 通过这个测试。技能本身是可迭代的测试通过率就是它的质量指标。我试过给一个“生成 RESTful 接口”的技能写测试给定一个数据模型定义agent 应该输出符合项目规范的路由、控制器、服务层代码并且能通过预设的接口测试。第一次跑通过率大概六成迭代了三轮技能描述后稳定在九成以上。这个过程和传统 TDD 几乎一模一样只是被测对象从人写的代码变成了 agent 的行为。注意技能不是越细越好。我见过有人把“打开文件”都写成一个技能结果 agent 调用链长得离谱反而容易出错。技能的粒度应该对齐“一个有意义的工程任务”比如“新增一个数据库迁移”或“重构一个函数并补测试”。3. 核心细节解析一个技能包到底长什么样3.1 技能描述文件的关键字段不同实现细节有差异但核心字段大同小异。下面这张表是我根据常见实践整理的你可以对照自己用的工具调整字段作用常见坑name技能唯一标识用中文或空格会导致调用失败description给 agent 看的自然语言说明写太泛agent 不知道何时用triggers触发条件通常是关键词或文件模式条件太宽会误触发太窄会漏触发steps执行步骤列表步骤之间缺少依赖声明顺序会乱validation验证命令或检查逻辑只写“检查是否正确”没有可执行命令fallback失败时的回退策略不写回退agent 失败后会反复重试description这个字段特别值得说。它不是写给人看的文档而是写给 agent 看的路由依据。我踩过的坑是一开始把 description 写得很“官方”比如“用于处理数据库相关操作”。结果 agent 在遇到“改一下用户表字段”时根本没想到调用这个技能。后来改成“当需要新增、修改、删除数据库表结构或字段时使用包括生成迁移文件和回滚脚本”命中率立刻上来了。3.2 步骤编排的两种模式技能内部的步骤编排我见过两种主流模式线性模式步骤 1 → 2 → 3 顺序执行。适合流程固定的任务比如“生成迁移文件 → 执行迁移 → 验证表结构”。优点是简单可控缺点是遇到分支就抓瞎。决策树模式在关键节点让 agent 根据当前状态选择下一步。比如“如果项目用 Prisma走 A 分支如果用 TypeORM走 B 分支”。灵活但复杂写不好容易让 agent 陷入循环。我的建议是新手从线性模式开始把分支逻辑放到技能外层的触发条件里。比如写两个技能一个叫create-migration-prisma一个叫create-migration-typeorm让 agent 根据项目依赖自动选。这样每个技能内部保持线性维护成本低很多。3.3 验证层怎么写才有效验证层是技能包的“质检员”。最有效的验证是可执行的命令而不是自然语言描述。比如# 验证迁移文件是否生成 test -f prisma/migrations/*/migration.sql # 验证接口是否返回 200 curl -s -o /dev/null -w %{http_code} http://localhost:3000/api/users | grep 200把这类命令写进技能的 validation 字段agent 执行完就能自己判断成败。我实测下来带可执行验证的技能一次通过率比不带的高出约 40%。因为 agent 有了明确的“完成信号”不会在“我觉得差不多了”和“再改改”之间反复横跳。提示验证命令要幂等。比如检查文件存在用test -f不要用会修改状态的命令。否则 agent 重试时可能把环境搞乱。4. 实操过程从零搭一个可用的技能包4.1 环境准备与工具选型假设你已经在用 Claude Code 或类似的 AI coding agent。技能包的存放位置通常有两种约定项目根目录下的.agent-skills/文件夹或者用户主目录下的全局技能库。我建议项目级技能放项目里通用技能放全局这样既能版本管理又能跨项目复用。工具方面skills CLI是热词里提到的不同实现可能叫不同名字。核心功能就三个list列出可用技能、validate检查技能格式、test跑技能测试。如果你用的工具没有 CLI手动建文件夹也能跑只是少了自动化检查。我自己的目录结构是这样的.agent-skills/ create-api-endpoint/ skill.yaml steps/ generate-route.md generate-controller.md validation/ check-endpoint.sh refactor-function/ skill.yaml ...每个技能一个文件夹skill.yaml是入口steps/放分步指令validation/放验证脚本。这样结构清晰agent 也容易定位。4.2 写第一个技能生成 RESTful 接口拿“生成 RESTful 接口”举例。先写skill.yamlname: create-api-endpoint description: 当需要为某个数据模型新增 RESTful 接口时使用包括路由、控制器、服务层和基础测试 triggers: - 新增接口 - create endpoint - 添加 API steps: - read: steps/analyze-model.md - read: steps/generate-route.md - read: steps/generate-controller.md - read: steps/generate-service.md - read: steps/generate-test.md validation: - run: validation/check-endpoint.sh fallback: - 如果路由生成失败检查项目路由注册方式 - 如果测试失败先确认数据库连接配置然后steps/analyze-model.md里写清楚先读数据模型定义文件提取字段名、类型、必填项。这一步的目的是让 agent不要凭空猜字段。我见过太多 agent 生成的接口字段和模型对不上就是因为跳过了分析步骤。generate-route.md里要指定路由风格是/api/users还是/users用不用版本号HTTP 方法怎么映射。这些细节不写清楚agent 每次生成的风格都不一样代码评审时很痛苦。4.3 参数选择与计算过程技能里经常需要 agent 做判断比如“分页默认每页多少条”。这种参数不要写死而是给一个计算规则。比如分页大小默认值 如果项目配置文件里有pagination.defaultSize用该值否则用 20。最大值不超过 100超过则截断为 100。为什么是 20这是常见实践里的平衡点太小会导致请求频繁太大单次响应体过重。100 的上限是防止客户端传个size100000把数据库拖垮。这类规则写进技能agent 每次都会按同样逻辑处理不会这次 10 条下次 50 条。再比如“生成测试用例的覆盖范围”可以写成至少覆盖正常返回 200、参数缺失返回 400、资源不存在返回 404、无权限返回 401。每个用例包含请求构造、预期状态码、预期响应体关键字段。这样 agent 生成的测试就有明确边界不会只写一个 happy path 就交差。4.4 实操现场记录我第一次跑这个技能时agent 在generate-service.md这一步卡住了。原因是项目里服务层用了依赖注入但技能描述里没提。agent 生成的代码直接new了一个 repository编译报错。修复方式是在技能里加一条前置检查# 检查项目是否使用依赖注入 grep -r inject src/ --include*.ts | head -5如果检测到注入模式就在步骤里明确“服务类通过构造函数注入依赖不要手动实例化”。改完之后一次通过。这个经历让我意识到技能包不是写完就完事它需要跟着项目演进。项目换了 ORM、改了目录结构、引入了新的规范技能都要同步更新。否则 agent 会拿着过时的剧本演新戏越演越乱。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。agent 明明有能力做某件事但就是不调用对应技能。排查顺序如下检查 triggers 关键词你用的词和技能里写的词是否匹配。比如你说“加个接口”技能里只写了“新增 API”可能就匹配不上。解决办法是把常见同义词都列进去。检查 description 的语义覆盖有些 agent 用语义匹配而不是关键词匹配。description 写得太窄语义相似度不够就不会触发。检查技能是否被正确加载用skills list确认技能在列表里。如果不在可能是路径不对或格式错误。我踩过最坑的一次是技能文件用了 UTF-8 BOM 头导致 YAML 解析失败但工具没报错只是静默跳过。后来养成习惯保存技能文件时一律选“无 BOM 的 UTF-8”。5.2 技能执行到一半失败失败原因通常分三类对应不同的处理策略失败类型典型表现处理策略环境问题命令找不到、依赖缺失在技能开头加环境检查步骤逻辑问题生成的代码编译不过细化步骤描述增加示例验证问题验证脚本本身有 bug先单独跑验证脚本确认可用环境问题最容易被忽略。比如技能里用了jq解析 JSON但用户机器上没装。agent 执行到那一步就卡住然后开始胡乱重试。解决办法是在技能最前面加一段command -v jq /dev/null 21 || { echo 需要安装 jq; exit 1; }这样失败得早、失败得明确比执行到一半再报错好排查得多。5.3 技能之间互相冲突当你装了多个技能可能出现两个技能都觉得自己该执行的情况。比如create-api-endpoint和create-crud-module都匹配“新增用户管理功能”。解决办法有两个一是给技能加优先级在元数据里写priority: 10数字大的先匹配二是收窄触发条件让create-crud-module只在明确提到“完整模块”时触发而create-api-endpoint处理更细粒度的接口需求。我倾向于第二种因为优先级是隐式规则时间长了没人记得谁高谁低。触发条件写清楚是显式契约维护起来更省心。5.4 独家避坑技巧几个我实际踩过、文档里不会写的坑不要在技能里写绝对路径。用相对路径或环境变量否则换台机器就废。技能步骤不要超过 7 步。超过之后 agent 的注意力会分散中间步骤容易被跳过。如果任务确实复杂拆成多个技能串联。验证脚本要能独立运行。不要依赖 agent 上一步的输出作为输入否则验证失败时你分不清是任务失败还是验证失败。定期跑技能回归测试。项目依赖升级、目录调整后老技能可能悄悄失效。我一般每周跑一次全量技能测试花不了几分钟但能避免关键时刻掉链子。6. 技能包的扩展方向与个人体会技能包搭起来之后能玩的花样比想象中多。我目前尝试过几个方向效果都不错。方向一把代码评审规则技能化。团队里常说的“这个函数太长了”“错误处理不规范”写成技能后agent 在生成代码时就会主动规避而不是等评审时再改。相当于把评审前移到了生成阶段。方向二技能组合成工作流。单个技能是原子操作多个技能按顺序调用就是工作流。比如“新增功能”工作流 分析需求 → 生成接口 → 生成测试 → 跑测试 → 生成文档。每个环节都是一个独立技能可以单独替换和升级。方向三用技能包做新人 onboarding。新同事装好 agent 和技能包相当于随身带了一个“团队规范执行器”。他让 agent 生成代码时自动就符合团队规范学习成本大幅降低。我个人在实际操作中的体会是技能包的质量取决于你对“好代码”的定义有多清晰。如果你自己都说不清楚什么样的接口设计是好的那写出来的技能也是模糊的agent 执行起来自然时好时坏。反过来写技能的过程其实是在逼你把工程规范想明白、写下来。这件事本身的价值可能比技能包本身还大。最后分享一个小技巧从你最常重复的任务开始写技能。不要一上来就搞个大而全的技能库先挑一个你每天都要做、每次都要跟 agent 解释半天的任务把它技能化。跑通一个你就有感觉了后面就是复制粘贴加微调的事。 AI编程代理技能包实战：从提示词到可测试的agent-skills
1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的“技能包”。你可以把它理解成一套标准化的“操作手册 可执行脚本 测试用例”的集合专门喂给 Claude Code、Cursor、Windsurf 这类 AI 编程代理让它们在特定任务上从“能聊两句”变成“真能干活”。这个项目解决的核心问题很具体AI coding agent 的通用能力很强但一到具体工程场景就掉链子。比如你让它“帮我加一个带分页的用户列表接口”它可能给你生成一堆看起来对、跑起来报错的代码。原因不是模型不行而是它缺少针对你项目结构、技术栈、代码规范的“技能约束”。agent-skills就是把这些约束沉淀成可复用、可版本管理的技能单元。适合谁看三类人最值得花时间一是已经在用 Claude Code 或类似工具做日常开发的工程师想把自己的经验固化成 agent 能执行的技能二是团队里负责搭建 AI 辅助开发流程的人需要一套可维护的技能库三是对 AI coding agent 底层机制好奇、想自己写 skill 的开发者。哪怕你只是刚装好 Claude Code理解这套东西也能让你少走很多弯路。我自己的体会是agent-skills 的价值不在“多”而在“准”。一个写得好的 skill能让 agent 在特定任务上的成功率从五五开提到八成以上这个提升是实打实的。2. 核心设计思路为什么是“技能”而不是“提示词”2.1 提示词的天花板在哪里大部分人用 AI coding agent 的方式是打开对话框敲一段自然语言等结果。这本质上是在写一次性提示词。提示词的问题在于它太依赖你当下的表达而且无法沉淀。你今天写了一段很精妙的提示让 agent 正确生成了数据库迁移脚本明天换个任务这段提示就废了。更麻烦的是提示词没有可测试性。你没法给一段提示词写单元测试也没法在 CI 里跑它。agent 输出对不对全靠你肉眼看。这在个人玩票阶段没问题一旦要团队协作、要规模化就完全撑不住。agent-skills的思路是把“提示”升级成“技能”。一个技能包含的不只是指令还有输入约束、执行步骤、验证逻辑、失败回退。它更像一个函数而不是一段话。2.2 技能包的三层结构我拆过几个比较成熟的 agent-skills 实现基本都遵循类似的三层结构元数据层技能名、适用场景、触发条件、依赖项。这层决定了 agent 什么时候该调用这个技能。指令层具体的操作步骤通常用结构化格式写比如分步骤的 markdown 或 YAML。这层是 agent 实际执行的“剧本”。验证层怎么判断任务完成了、结果对不对。这层最容易被忽略但恰恰是区分“玩具”和“工具”的关键。为什么这么分因为 agent 的执行是有状态、多轮次的。它需要先判断“这个任务我有没有对应技能”再“按步骤执行”最后“自检结果”。三层结构正好对应这三个阶段。2.3 和 test-driven-development 的关系热词里出现了test-driven-development这不是巧合。技能包天然适合 TDD 的工作流。你可以先写一个失败的测试用例描述“agent 应该能完成 X 任务”然后写技能让 agent 通过这个测试。技能本身是可迭代的测试通过率就是它的质量指标。我试过给一个“生成 RESTful 接口”的技能写测试给定一个数据模型定义agent 应该输出符合项目规范的路由、控制器、服务层代码并且能通过预设的接口测试。第一次跑通过率大概六成迭代了三轮技能描述后稳定在九成以上。这个过程和传统 TDD 几乎一模一样只是被测对象从人写的代码变成了 agent 的行为。注意技能不是越细越好。我见过有人把“打开文件”都写成一个技能结果 agent 调用链长得离谱反而容易出错。技能的粒度应该对齐“一个有意义的工程任务”比如“新增一个数据库迁移”或“重构一个函数并补测试”。3. 核心细节解析一个技能包到底长什么样3.1 技能描述文件的关键字段不同实现细节有差异但核心字段大同小异。下面这张表是我根据常见实践整理的你可以对照自己用的工具调整字段作用常见坑name技能唯一标识用中文或空格会导致调用失败description给 agent 看的自然语言说明写太泛agent 不知道何时用triggers触发条件通常是关键词或文件模式条件太宽会误触发太窄会漏触发steps执行步骤列表步骤之间缺少依赖声明顺序会乱validation验证命令或检查逻辑只写“检查是否正确”没有可执行命令fallback失败时的回退策略不写回退agent 失败后会反复重试description这个字段特别值得说。它不是写给人看的文档而是写给 agent 看的路由依据。我踩过的坑是一开始把 description 写得很“官方”比如“用于处理数据库相关操作”。结果 agent 在遇到“改一下用户表字段”时根本没想到调用这个技能。后来改成“当需要新增、修改、删除数据库表结构或字段时使用包括生成迁移文件和回滚脚本”命中率立刻上来了。3.2 步骤编排的两种模式技能内部的步骤编排我见过两种主流模式线性模式步骤 1 → 2 → 3 顺序执行。适合流程固定的任务比如“生成迁移文件 → 执行迁移 → 验证表结构”。优点是简单可控缺点是遇到分支就抓瞎。决策树模式在关键节点让 agent 根据当前状态选择下一步。比如“如果项目用 Prisma走 A 分支如果用 TypeORM走 B 分支”。灵活但复杂写不好容易让 agent 陷入循环。我的建议是新手从线性模式开始把分支逻辑放到技能外层的触发条件里。比如写两个技能一个叫create-migration-prisma一个叫create-migration-typeorm让 agent 根据项目依赖自动选。这样每个技能内部保持线性维护成本低很多。3.3 验证层怎么写才有效验证层是技能包的“质检员”。最有效的验证是可执行的命令而不是自然语言描述。比如# 验证迁移文件是否生成 test -f prisma/migrations/*/migration.sql # 验证接口是否返回 200 curl -s -o /dev/null -w %{http_code} http://localhost:3000/api/users | grep 200把这类命令写进技能的 validation 字段agent 执行完就能自己判断成败。我实测下来带可执行验证的技能一次通过率比不带的高出约 40%。因为 agent 有了明确的“完成信号”不会在“我觉得差不多了”和“再改改”之间反复横跳。提示验证命令要幂等。比如检查文件存在用test -f不要用会修改状态的命令。否则 agent 重试时可能把环境搞乱。4. 实操过程从零搭一个可用的技能包4.1 环境准备与工具选型假设你已经在用 Claude Code 或类似的 AI coding agent。技能包的存放位置通常有两种约定项目根目录下的.agent-skills/文件夹或者用户主目录下的全局技能库。我建议项目级技能放项目里通用技能放全局这样既能版本管理又能跨项目复用。工具方面skills CLI是热词里提到的不同实现可能叫不同名字。核心功能就三个list列出可用技能、validate检查技能格式、test跑技能测试。如果你用的工具没有 CLI手动建文件夹也能跑只是少了自动化检查。我自己的目录结构是这样的.agent-skills/ create-api-endpoint/ skill.yaml steps/ generate-route.md generate-controller.md validation/ check-endpoint.sh refactor-function/ skill.yaml ...每个技能一个文件夹skill.yaml是入口steps/放分步指令validation/放验证脚本。这样结构清晰agent 也容易定位。4.2 写第一个技能生成 RESTful 接口拿“生成 RESTful 接口”举例。先写skill.yamlname: create-api-endpoint description: 当需要为某个数据模型新增 RESTful 接口时使用包括路由、控制器、服务层和基础测试 triggers: - 新增接口 - create endpoint - 添加 API steps: - read: steps/analyze-model.md - read: steps/generate-route.md - read: steps/generate-controller.md - read: steps/generate-service.md - read: steps/generate-test.md validation: - run: validation/check-endpoint.sh fallback: - 如果路由生成失败检查项目路由注册方式 - 如果测试失败先确认数据库连接配置然后steps/analyze-model.md里写清楚先读数据模型定义文件提取字段名、类型、必填项。这一步的目的是让 agent不要凭空猜字段。我见过太多 agent 生成的接口字段和模型对不上就是因为跳过了分析步骤。generate-route.md里要指定路由风格是/api/users还是/users用不用版本号HTTP 方法怎么映射。这些细节不写清楚agent 每次生成的风格都不一样代码评审时很痛苦。4.3 参数选择与计算过程技能里经常需要 agent 做判断比如“分页默认每页多少条”。这种参数不要写死而是给一个计算规则。比如分页大小默认值 如果项目配置文件里有pagination.defaultSize用该值否则用 20。最大值不超过 100超过则截断为 100。为什么是 20这是常见实践里的平衡点太小会导致请求频繁太大单次响应体过重。100 的上限是防止客户端传个size100000把数据库拖垮。这类规则写进技能agent 每次都会按同样逻辑处理不会这次 10 条下次 50 条。再比如“生成测试用例的覆盖范围”可以写成至少覆盖正常返回 200、参数缺失返回 400、资源不存在返回 404、无权限返回 401。每个用例包含请求构造、预期状态码、预期响应体关键字段。这样 agent 生成的测试就有明确边界不会只写一个 happy path 就交差。4.4 实操现场记录我第一次跑这个技能时agent 在generate-service.md这一步卡住了。原因是项目里服务层用了依赖注入但技能描述里没提。agent 生成的代码直接new了一个 repository编译报错。修复方式是在技能里加一条前置检查# 检查项目是否使用依赖注入 grep -r inject src/ --include*.ts | head -5如果检测到注入模式就在步骤里明确“服务类通过构造函数注入依赖不要手动实例化”。改完之后一次通过。这个经历让我意识到技能包不是写完就完事它需要跟着项目演进。项目换了 ORM、改了目录结构、引入了新的规范技能都要同步更新。否则 agent 会拿着过时的剧本演新戏越演越乱。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。agent 明明有能力做某件事但就是不调用对应技能。排查顺序如下检查 triggers 关键词你用的词和技能里写的词是否匹配。比如你说“加个接口”技能里只写了“新增 API”可能就匹配不上。解决办法是把常见同义词都列进去。检查 description 的语义覆盖有些 agent 用语义匹配而不是关键词匹配。description 写得太窄语义相似度不够就不会触发。检查技能是否被正确加载用skills list确认技能在列表里。如果不在可能是路径不对或格式错误。我踩过最坑的一次是技能文件用了 UTF-8 BOM 头导致 YAML 解析失败但工具没报错只是静默跳过。后来养成习惯保存技能文件时一律选“无 BOM 的 UTF-8”。5.2 技能执行到一半失败失败原因通常分三类对应不同的处理策略失败类型典型表现处理策略环境问题命令找不到、依赖缺失在技能开头加环境检查步骤逻辑问题生成的代码编译不过细化步骤描述增加示例验证问题验证脚本本身有 bug先单独跑验证脚本确认可用环境问题最容易被忽略。比如技能里用了jq解析 JSON但用户机器上没装。agent 执行到那一步就卡住然后开始胡乱重试。解决办法是在技能最前面加一段command -v jq /dev/null 21 || { echo 需要安装 jq; exit 1; }这样失败得早、失败得明确比执行到一半再报错好排查得多。5.3 技能之间互相冲突当你装了多个技能可能出现两个技能都觉得自己该执行的情况。比如create-api-endpoint和create-crud-module都匹配“新增用户管理功能”。解决办法有两个一是给技能加优先级在元数据里写priority: 10数字大的先匹配二是收窄触发条件让create-crud-module只在明确提到“完整模块”时触发而create-api-endpoint处理更细粒度的接口需求。我倾向于第二种因为优先级是隐式规则时间长了没人记得谁高谁低。触发条件写清楚是显式契约维护起来更省心。5.4 独家避坑技巧几个我实际踩过、文档里不会写的坑不要在技能里写绝对路径。用相对路径或环境变量否则换台机器就废。技能步骤不要超过 7 步。超过之后 agent 的注意力会分散中间步骤容易被跳过。如果任务确实复杂拆成多个技能串联。验证脚本要能独立运行。不要依赖 agent 上一步的输出作为输入否则验证失败时你分不清是任务失败还是验证失败。定期跑技能回归测试。项目依赖升级、目录调整后老技能可能悄悄失效。我一般每周跑一次全量技能测试花不了几分钟但能避免关键时刻掉链子。6. 技能包的扩展方向与个人体会技能包搭起来之后能玩的花样比想象中多。我目前尝试过几个方向效果都不错。方向一把代码评审规则技能化。团队里常说的“这个函数太长了”“错误处理不规范”写成技能后agent 在生成代码时就会主动规避而不是等评审时再改。相当于把评审前移到了生成阶段。方向二技能组合成工作流。单个技能是原子操作多个技能按顺序调用就是工作流。比如“新增功能”工作流 分析需求 → 生成接口 → 生成测试 → 跑测试 → 生成文档。每个环节都是一个独立技能可以单独替换和升级。方向三用技能包做新人 onboarding。新同事装好 agent 和技能包相当于随身带了一个“团队规范执行器”。他让 agent 生成代码时自动就符合团队规范学习成本大幅降低。我个人在实际操作中的体会是技能包的质量取决于你对“好代码”的定义有多清晰。如果你自己都说不清楚什么样的接口设计是好的那写出来的技能也是模糊的agent 执行起来自然时好时坏。反过来写技能的过程其实是在逼你把工程规范想明白、写下来。这件事本身的价值可能比技能包本身还大。最后分享一个小技巧从你最常重复的任务开始写技能。不要一上来就搞个大而全的技能库先挑一个你每天都要做、每次都要跟 agent 解释半天的任务把它技能化。跑通一个你就有感觉了后面就是复制粘贴加微调的事。