1. 从“agent-skills”说起为什么AI编码代理需要一套技能体系第一次看到“agent-skills”这个词很多人会以为它只是某个仓库的名字或者某个AI工具的插件集合。但如果你真正在终端里跑过Claude Code、用过skills CLI、尝试过让AI代理帮你完成一个完整的开发任务你就会明白agent-skills本质上是一套让AI编码代理从“能聊天”进化到“能干活”的能力封装规范。我最初接触这个概念是在一个自动化重构项目里。当时我用Claude Code帮我改一个遗留的Python服务代码量大概三千行涉及数据库迁移、接口兼容和单元测试。第一次跑的时候AI代理确实能理解我的意图也能生成代码但问题在于它每次都要我重复描述项目结构、测试命令、代码风格约束。更麻烦的是它生成的测试用例经常不符合项目已有的pytest规范导致CI直接挂掉。后来我意识到问题不在于模型能力不够而在于我没有把“这个项目该怎么干活”这件事告诉它。agent-skills就是解决这个问题的。简单来说agent-skills是一组可复用的技能定义文件通常以Markdown或YAML格式存在放在项目的特定目录下。每个技能描述了一类任务的标准操作流程、约束条件和验证方式。当AI编码代理启动时它会自动加载这些技能从而知道“在这个项目里写测试要用什么框架”“提交代码前要跑哪些检查”“数据库迁移文件放在哪里”。这就像给一个新入职的工程师发了一本团队内部的操作手册而不是让他每次遇到问题都来问你。这套体系解决的核心问题是AI编码代理的上下文一致性和任务可复现性。没有agent-skills的时候你每次和AI代理对话都像是在重新培训一个新人有了agent-skills之后代理的行为变得可预测、可审计、可版本控制。对于团队协作来说这意味着你可以把“如何用AI代理完成某类任务”的最佳实践固化下来而不是靠某个人的提示词技巧。适合阅读这篇文章的人包括正在使用或准备使用Claude Code的开发者、需要为团队搭建AI编码工作流的技术负责人、对skills CLI和test-driven-development结合感兴趣的工具爱好者以及任何想让AI代理真正融入自己日常开发流程的人。不管你是刚接触AI编码代理的新手还是已经用过一段时间但觉得“效果不稳定”的老用户下面这些从实际项目中踩出来的经验应该都能帮到你。2. agent-skills的核心设计思路与方案选型2.1 为什么是“技能”而不是“提示词”很多人第一次听说agent-skills的时候会下意识地把它等同于“一套写得很好的提示词”。这个理解不能说错但不够准确。提示词是单次对话的输入而技能是跨会话、跨任务、跨项目成员共享的能力单元。两者的区别有点像“临时给同事发一条微信说怎么改这个bug”和“写一份团队内部的代码审查清单”。我试过两种方式。早期我是在Claude Code的对话里直接粘贴一大段项目说明包括目录结构、测试命令、代码规范。这种方式在单次任务里有效但每次新开一个会话就要重新粘贴而且一旦项目结构变了那段说明就过期了。更麻烦的是团队里其他人不知道我用了什么提示词他们和AI代理协作时得到的结果完全不一样。后来我转向agent-skills的方式在项目根目录下建一个.agent/skills/目录里面放若干个Markdown文件每个文件定义一个技能。比如run-tests.md里写清楚测试命令、测试文件命名规则、覆盖率要求code-style.md里写清楚格式化工具、lint规则、import排序方式。Claude Code在启动时会自动读取这个目录后续所有对话都基于这些技能约束来执行。这个转变带来的最大好处是可版本控制。技能文件跟着代码仓库一起提交新人克隆项目后他的AI代理自动就具备了和团队一致的“工作常识”。代码审查时如果发现AI代理总是犯某个错误我们可以直接修改对应的技能文件而不是在聊天记录里翻找当时的提示词。2.2 skills CLI的角色让技能可发现、可组合skills CLI是这套体系里的另一个关键组件。它的作用不是“运行技能”而是“管理技能”。你可以把它理解为一个轻量级的包管理器专门用来发现、安装、更新和组合agent-skills。我实际使用skills CLI的场景主要有三个。第一是初始化在一个新项目里运行skills init它会生成标准的技能目录结构和几个基础技能模板包括测试、代码风格、提交信息规范。第二是安装社区技能比如我想让AI代理支持TDD工作流可以直接skills install tdd-workflow它会从注册表拉取对应的技能定义并放到本地目录。第三是组合技能有些技能之间有依赖关系比如“数据库迁移”技能可能依赖“测试”技能skills CLI会自动解析这些依赖并确保加载顺序正确。为什么需要这样一个CLI工具因为手动管理技能文件在项目规模变大后会变得很痛苦。我见过一个项目有二十多个技能文件分散在不同目录有些是团队自研的有些是从社区复制的版本混乱更新时经常漏掉某个文件。skills CLI通过一个skills.json清单文件来记录所有技能的来源和版本更新时只需要skills update就能全部同步。2.3 与test-driven-development的天然契合agent-skills和test-driven-development的结合是我认为最有价值的一个设计方向。TDD的核心循环是“红-绿-重构”先写一个失败的测试然后写最少的代码让测试通过最后重构。这个循环对AI代理来说其实非常友好因为每一步都有明确的验证信号。我在一个Node.js项目里配置了TDD技能后AI代理的工作方式发生了明显变化。以前我让它“实现一个用户注册接口”它会直接生成路由、控制器、数据库操作和测试但测试往往是最后补的而且经常和实现不匹配。配置了TDD技能后代理会先写测试文件运行测试确认失败然后才写实现代码再运行测试确认通过。整个过程它会在终端里实际执行命令而不是只在对话里描述。这个技能定义的关键在于明确每一步的验证命令和预期输出。比如技能文件里会写“写测试后运行npm test -- --grep 用户注册预期看到至少一个失败用例实现后再次运行同一命令预期全部通过。”这样AI代理就知道什么时候该继续什么时候该停下来检查。2.4 方案选型的几个关键取舍在设计agent-skills体系时有几个取舍点值得展开说。第一个取舍是技能粒度。技能太粗比如一个“后端开发”技能包揽所有事情代理就失去了灵活性技能太细比如“写一个Express路由”单独成一个技能又会导致技能文件数量爆炸。我的经验是按“任务类型”而不是“代码单元”来划分。测试、迁移、部署、代码审查、文档更新这些是任务类型而“写控制器”“写模型”是代码单元不应该单独成技能。第二个取舍是技能文件的格式。Markdown可读性最好适合人类维护YAML结构化程度高适合程序解析。我目前的做法是混合技能的主体描述用Markdown但元数据如依赖、触发条件、验证命令用YAML front matter放在文件开头。这样既方便人读也方便skills CLI解析。第三个取舍是是否允许代理修改技能。有些团队希望AI代理在发现技能不完善时自动更新技能文件。我个人的做法是禁止自动修改但允许代理在对话中建议修改。因为技能文件是团队共识的载体自动修改会破坏这种共识的严肃性。代理可以提出“这个测试命令似乎过期了建议更新为xxx”但最终修改由人来做。3. 核心细节解析与实操要点3.1 技能文件的标准结构一个完整的agent-skill文件通常包含四个部分元数据、适用场景、操作步骤、验证方式。我拿一个实际项目里的database-migration.md来举例说明。元数据部分用YAML front matter写在文件最上方--- name: database-migration version: 1.2.0 dependencies: - run-tests triggers: - 创建迁移 - 修改表结构 - 添加字段 ---这里name是技能唯一标识version用于版本管理dependencies声明依赖的其他技能triggers是触发关键词。当用户在对话中提到“给用户表加一个手机号字段”时Claude Code会匹配到triggers里的“添加字段”自动加载这个技能。适用场景部分用自然语言描述这个技能解决什么问题、不解决什么问题。比如“本技能适用于使用Prisma作为ORM的PostgreSQL数据库迁移。不适用于MongoDB或手写SQL迁移的场景。”这部分看起来简单但非常重要因为它防止代理在不合适的场景下错误应用技能。操作步骤部分是核心需要写得足够具体让代理能按步骤执行。我通常会写成有序列表每一步都包含具体的命令或文件路径。比如在prisma/schema.prisma中修改模型定义运行npx prisma migrate dev --name 迁移名称生成迁移文件检查生成的SQL文件是否符合预期运行npx prisma generate更新客户端执行npm run test:db验证迁移不影响现有测试验证方式部分定义“怎么算完成了”。这一步是很多技能文件缺失的导致代理不知道什么时候该停。我会写清楚具体的命令和预期输出比如“运行npm run test:db预期所有测试通过且输出中不包含migration failed字样。”3.2 技能加载的优先级与冲突处理当一个项目里有多个技能文件时加载顺序和冲突处理就变得很重要。我遇到过的情况是一个通用技能说“提交前运行npm test”另一个项目特定技能说“提交前运行npm run test:ci”。两个技能都匹配当前场景代理该听谁的我的处理原则是具体优先于通用。在技能元数据里可以加一个priority字段数值越大优先级越高。项目特定技能的priority设为100通用技能设为10。当冲突发生时高优先级技能覆盖低优先级技能的同名步骤。另一个原则是后加载覆盖先加载。skills CLI在加载技能时按依赖顺序排列被依赖的技能先加载依赖别人的后加载。如果两个技能没有依赖关系按文件名字母序加载。这个规则需要在团队内达成共识否则不同人本地加载顺序不一致会导致代理行为不一致。我还建议在技能文件里显式声明“本技能覆盖哪些技能”。比如项目特定的测试技能可以写overrides: [run-tests]这样skills CLI在加载时会自动禁用被覆盖的技能避免冲突。3.3 如何写出代理能“看懂”的操作步骤这是我在实践中踩坑最多的地方。一开始我写的技能文件像给人看的文档比如“确保代码质量”“遵循项目规范”。结果代理完全不知道该怎么执行因为它需要的是可操作的具体指令。后来我总结了一个原则每个步骤必须包含一个可执行的命令或一个可检查的文件状态。比如“确保代码质量”应该写成“运行npm run lint如果输出中有error则修复对应文件后重新运行直到输出为空”。再比如“遵循项目规范”应该写成“检查src/下所有新建的.ts文件确保每个文件头部有// ts-check注释如果没有则添加”。另一个技巧是用条件语句描述分支逻辑。代理在执行技能时需要知道“如果A情况则做X如果B情况则做Y”。比如数据库迁移技能里可以写“如果迁移涉及删除列则先运行npm run test:db确认没有测试依赖该列如果迁移只涉及添加列则直接执行迁移。”这种条件描述让代理能根据实际情况调整行为。还有一个容易忽略的点是错误处理。技能文件里应该写清楚“如果某一步失败了该怎么办”。比如“如果npx prisma migrate dev失败检查prisma/migrations/目录下是否有冲突的迁移文件如果有则手动解决冲突后重新运行”。没有错误处理的技能代理在遇到失败时往往会卡住或者胡乱尝试。3.4 技能与项目目录的绑定方式agent-skills放在哪里决定了它的作用范围。我目前采用三级目录结构项目根目录的.agent/skills/项目特定技能只对当前项目生效用户主目录的.agent/skills/个人通用技能对所有项目生效skills CLI的全局注册表社区共享技能通过skills install安装到本地加载优先级是项目特定 个人通用 社区共享。这样设计的好处是我可以在个人通用技能里放一些“我习惯用vim”“我偏好函数式风格”之类的个人偏好而在项目特定技能里放“这个项目用Prisma”“这个项目测试覆盖率要求80%”之类的项目约束。需要注意的是项目特定技能应该提交到代码仓库个人通用技能不应该提交。我在.gitignore里加了.agent/skills/local/来排除个人技能目录只提交.agent/skills/project/。这样团队共享的是项目约束个人偏好不会污染仓库。4. 实操过程与核心环节实现4.1 从零搭建一个agent-skills工作流我拿一个真实的Express TypeScript项目来演示完整搭建过程。这个项目有大约五十个接口使用Jest做测试Prisma做数据库访问。第一步是安装skills CLI。在项目根目录运行npm install -g agent-skills/cli skills initskills init会生成.agent/skills/目录和skills.json清单文件。默认会创建三个基础技能code-style.md、run-tests.md、commit-message.md。我通常会先修改这三个文件让它们符合项目实际情况。run-tests.md的修改重点是测试命令和测试文件命名规则。这个项目用的是npm test测试文件放在src/**/*.test.ts。我会在技能里写清楚“运行npm test执行所有测试运行npm test -- --testPathPattern模块名执行单个模块测试测试文件必须与被测文件同目录命名格式为文件名.test.ts。”code-style.md需要写清楚格式化工具和lint规则。这个项目用ESLint Prettier我会写“提交前运行npm run lint:fix自动修复格式问题import顺序按eslint-plugin-import规则排序禁止使用any类型除非在注释中说明理由。”第二步是添加项目特定技能。我创建了database-migration.md和api-endpoint.md两个文件。api-endpoint.md定义了新增接口的标准流程先在src/routes/下创建路由文件然后在src/controllers/下创建控制器再在src/services/下创建服务层最后在src/__tests__/下创建集成测试。每一步都有对应的文件路径和命名规范。第三步是配置Claude Code加载技能。在项目根目录的.claude/config.json里添加{ skills: { enabled: true, directory: .agent/skills, autoLoad: true } }这样Claude Code启动时会自动读取技能目录。我实测下来从启动到技能加载完成大约需要两到三秒对于日常开发来说完全可以接受。4.2 用TDD技能完成一个真实功能我拿“用户手机号绑定”这个功能来演示TDD技能的实际执行过程。这个功能的需求是用户可以在个人设置页面绑定手机号绑定后可以通过手机号登录。在配置了TDD技能的情况下我在Claude Code里输入“实现用户手机号绑定功能包括数据库字段、接口和测试。”代理的执行过程如下。首先它读取了tdd-workflow.md技能确认工作流程是“先写测试再写实现”。然后它读取了database-migration.md技能知道需要先修改Prisma schema。它先在prisma/schema.prisma的User模型里添加了phone String? unique字段然后运行npx prisma migrate dev --name add_phone_to_user生成迁移文件。接着它进入TDD循环。第一步写测试在src/__tests__/phone-binding.test.ts里写了三个测试用例——绑定成功、绑定已存在的手机号返回错误、未登录用户绑定返回401。然后运行npm test -- --testPathPatternphone-binding预期看到三个失败用例。代理在终端里实际执行了这个命令确认测试失败。第二步写实现在src/services/user.service.ts里添加bindPhone方法在src/controllers/user.controller.ts里添加对应的控制器方法在src/routes/user.routes.ts里注册路由。然后再次运行测试命令这次预期全部通过。代理执行后确认三个测试都通过了。第三步重构代理检查了新增代码是否符合code-style.md里的规范发现bindPhone方法有点长于是拆分成两个小方法。然后再次运行测试确认重构没有破坏功能。整个过程代理在终端里执行了六次命令每次都有明确的预期输出。我只需要在最后审查一下代码确认业务逻辑正确即可。这个功能从开始到完成大约用了八分钟其中大部分时间是代理在写代码和运行测试我实际参与的时间不到两分钟。4.3 技能文件的版本管理与团队协作当团队有多个人使用agent-skills时版本管理就变得很重要。我的做法是把.agent/skills/目录纳入Git管理但遵循几条规则。第一条规则是技能变更需要代码审查。技能文件修改和代码修改一样需要走Pull Request流程。审查重点是新技能是否与现有技能冲突、操作步骤是否可执行、验证方式是否明确。我见过一个团队因为技能文件没有审查导致某个人加了一个“提交前运行npm run deploy”的技能结果AI代理在每次提交时都尝试部署到生产环境。第二条规则是技能版本与项目版本对齐。在skills.json里记录每个技能的版本号当项目发布新版本时检查技能是否需要同步更新。比如项目从Express迁移到Fastifyapi-endpoint.md技能里的框架相关命令就需要更新。第三条规则是定期清理过期技能。我每季度会检查一次技能目录删除不再使用的技能合并重复的技能。一个超过六个月没有被任何对话触发的技能大概率已经过期了。4.4 技能执行日志与效果评估为了知道技能是否真的在起作用我会让Claude Code记录技能执行日志。在.claude/config.json里开启日志{ logging: { skills: true, logFile: .agent/logs/skills.log } }日志会记录每次对话中加载了哪些技能、执行了哪些步骤、验证结果如何。我每周会花十分钟看一下日志主要关注三个指标技能触发频率、步骤失败率、平均执行时间。技能触发频率反映哪些技能真正被用到。如果一个技能一个月都没有被触发要么是触发关键词设置不对要么是这个技能根本不需要。步骤失败率反映技能的可执行性。如果某个技能的某一步经常失败说明这一步的描述可能有问题需要优化。平均执行时间反映技能是否过于冗长。如果一个简单任务因为加载了太多技能而变慢就需要考虑拆分或精简技能。我实测下来一个配置良好的agent-skills体系可以把AI代理的任务完成率从大约60%提升到85%以上。剩下的15%失败案例大部分是因为需求本身模糊或者涉及项目外的依赖这些不是技能能解决的。5. 常见问题与排查技巧实录5.1 技能不生效的排查思路这是最常见的问题明明配置了技能文件但AI代理的行为没有任何变化。我总结了一个排查顺序按这个顺序走基本能定位到问题。第一步检查技能目录路径是否正确。Claude Code默认读取.agent/skills/如果你放在.claude/skills/或者skills/它不会自动加载。我建议在项目根目录运行skills list命令它会列出当前加载的所有技能。如果列表为空说明路径配置有问题。第二步检查技能文件格式是否正确。YAML front matter必须以---开头和结尾中间不能有语法错误。我遇到过因为triggers列表里用了中文引号导致解析失败的情况。可以用skills validate命令检查所有技能文件的格式。第三步检查触发关键词是否匹配。技能只有在对话内容匹配triggers时才会加载。如果你说“帮我改一下用户表”但技能的trigger是“数据库迁移”它就不会触发。我通常会在trigger里加多个同义词比如[数据库迁移, 改表, 加字段, 修改schema]。第四步检查技能优先级是否被覆盖。如果两个技能冲突高优先级的会覆盖低优先级的。可以在日志里看到实际加载了哪个技能。如果发现加载的不是你期望的技能检查一下priority设置。5.2 代理执行技能时卡住的常见原因代理在执行技能步骤时卡住通常是因为某一步的预期结果不明确或者命令执行失败后没有处理逻辑。一个典型场景是测试命令返回了非零退出码但技能里只写了“运行测试”没有写“如果测试失败该怎么办”。代理会停在那一页反复运行同一个命令。解决方法是在技能里加错误处理分支“如果npm test返回非零退出码检查失败用例的输出修复对应代码后重新运行。如果连续三次失败停止并输出失败原因。”另一个场景是命令需要交互式输入。比如npx prisma migrate dev在某些情况下会询问迁移名称。如果技能里没有提供--name参数代理会卡在等待输入。解决方法是在技能里写清楚所有需要预先提供的参数。还有一个场景是文件路径不存在。代理尝试读取一个不存在的文件时会报错如果技能里没有说明“如果文件不存在则创建”它就会卡住。我通常会在涉及文件操作的步骤里加上“如果文件不存在先创建空文件”的说明。5.3 技能冲突与覆盖的实战案例我遇到过一个真实的冲突案例项目里有两个技能都定义了“提交前检查”。code-style.md说“提交前运行npm run lint”run-tests.md说“提交前运行npm test”。两个技能同时加载时代理只执行了其中一个导致另一个检查被跳过。解决方法是引入一个pre-commit.md技能专门定义提交前的完整检查流程并在元数据里声明overrides: [code-style, run-tests]。这样加载pre-commit时另外两个技能的提交前步骤会被自动禁用避免冲突。这个案例给我的教训是技能之间的边界要清晰。每个技能应该只负责一个任务类型提交前检查这种跨任务类型的流程应该单独成一个技能。我现在会在技能设计阶段就画一个依赖图确保没有两个技能定义相同的步骤。5.4 常见问题速查表问题现象可能原因排查方法解决方案技能完全不生效目录路径错误运行skills list确认技能在.agent/skills/下技能偶尔生效触发关键词不匹配查看日志中的触发记录增加同义词到triggers代理执行到一半卡住缺少错误处理分支检查技能文件是否有失败处理补充“如果失败则...”逻辑两个技能行为矛盾优先级冲突查看日志中加载的技能顺序设置priority或使用overrides技能更新后不生效缓存未刷新重启Claude Code运行skills reload代理忽略技能步骤步骤描述不可执行检查步骤是否有具体命令改为可执行的命令或文件检查技能加载太慢技能文件过多查看加载日志耗时合并或删除不常用技能5.5 几个我踩过的坑和对应的技巧第一个坑是技能文件写得太长。我一开始写了一个三百行的backend-development.md结果代理加载后经常忽略中间步骤。后来我把它拆成五个小技能每个不超过八十行执行效果明显改善。技巧是一个技能文件如果超过一百行就应该考虑拆分。第二个坑是在技能里写死绝对路径。我写过/Users/myname/project/src/这样的路径结果团队其他人克隆项目后技能完全不能用。技巧是所有路径都相对于项目根目录用src/而不是绝对路径。第三个坑是技能里的命令依赖全局安装的工具。我写了一个技能用ts-node运行脚本但团队新人的机器上没有全局安装ts-node。技巧是所有命令都用npx前缀确保使用项目本地依赖。第四个坑是技能没有版本号。当技能更新后代理有时会混用新旧版本的步骤。技巧是每个技能文件都加version字段skills CLI会在加载时检查版本一致性。第五个坑是忽略技能的测试。我修改技能后直接投入使用结果代理执行时才发现步骤有误。技巧是修改技能后用一个简单的测试任务验证一遍确认代理能按新步骤正确执行。6. 技能体系的扩展与个人经验分享6.1 从单项目到多项目的技能复用当你在多个项目之间切换时每个项目都维护一套技能文件会很累。我的做法是建立一个“基础技能层”和“项目技能层”的两层结构。基础技能层放在用户主目录的.agent/skills/base/下包含所有项目通用的技能比如git-commit.md、code-review.md、debugging.md。这些技能不涉及具体技术栈只定义通用工作流程。项目技能层放在各项目根目录的.agent/skills/下只包含项目特定的技能比如database-migration.md、api-endpoint.md。项目技能可以依赖基础技能但不能反过来。这样设计的好处是当我换到一个新项目时只需要配置项目技能基础技能自动继承。我实测下来新项目初始化时间从原来的半小时缩短到五分钟。6.2 技能与CI/CD的联动agent-skills不仅可以用于本地开发还可以和CI/CD流水线联动。我在GitHub Actions里加了一个步骤在运行测试前先检查技能文件是否与代码一致。具体做法是在CI里运行skills validate --strict它会检查所有技能文件格式是否正确、依赖是否满足、版本是否一致。如果技能文件有语法错误或者依赖缺失CI会直接失败。这个检查帮我避免了好几次因为技能文件错误导致的代理行为异常。另一个联动点是技能驱动的代码生成。我配置了一个技能当检测到src/routes/下有新文件时自动生成对应的测试文件骨架和API文档骨架。这个技能在CI里以“检查模式”运行如果发现新路由没有对应测试就输出警告。6.3 我个人在实际操作中的体会用了大半年agent-skills之后我最大的体会是这套体系的价值不在于让AI代理更聪明而在于让它的行为更可预测。模型本身的能力已经很强了但它的输出质量波动很大同样的需求今天做得好明天做得差。技能体系通过固化操作流程和验证标准把这种波动控制在一个可接受的范围内。另一个体会是技能文件需要持续迭代。我最初写的技能文件现在回头看有很多问题比如步骤太粗、验证不明确、错误处理缺失。每次代理执行失败我都会问自己是模型能力不够还是技能没写清楚大部分时候是后者。把失败案例转化为技能改进是提升整体效率的最快路径。还有一个反直觉的发现技能不是越多越好。我一度给项目加了二十多个技能结果代理加载时间变长而且经常在多个技能之间混淆。后来精简到八个核心技能执行效果反而更好。我的经验是一个项目的技能数量控制在五到十个之间比较合适超过十五个就需要考虑合并或分层。6.4 后续可以扩展的方向如果你已经跑通了基础的agent-skills工作流有几个方向可以继续深入。第一个方向是技能的市场化共享。skills CLI支持从远程注册表安装技能你可以把自己团队沉淀的技能发布上去也可以安装别人分享的技能。我目前关注的是测试和重构类的技能这两个领域的最佳实践比较通用。第二个方向是技能与代码审查的深度集成。我尝试过让AI代理在代码审查时自动检查提交是否符合技能定义的标准比如“新增的API是否有对应的测试文件”“数据库迁移是否有回滚方案”。这个方向还在探索中目前的效果是能发现大约七成的不规范提交。第三个方向是技能执行数据的分析。通过收集技能执行日志可以分析哪些技能最常用、哪些步骤最容易失败、哪些技能组合效果最好。这些数据可以用来优化技能设计也可以用来评估AI代理在团队中的实际贡献。第四个方向是技能与项目文档的同步。我理想中的状态是技能文件既是AI代理的操作手册也是人类开发者的项目文档。新人加入项目时读一遍技能文件就能了解项目的开发流程和规范。目前我还在调整技能文件的写法让它对人类和代理都友好。6.5 给刚接触agent-skills的朋友几个实用建议如果你刚开始接触agent-skills我建议从最小的技能开始。不要一上来就写一个覆盖整个开发流程的大技能而是先写一个run-tests.md把测试命令和测试文件规范写清楚。这个技能最简单也最容易看到效果。然后逐步添加技能。每当你发现自己在对话里重复描述同一件事超过三次就应该考虑把它写成一个技能。比如你总是要告诉代理“这个项目用pnpm不用npm”那就写一个package-manager.md技能。技能写好后一定要实际跑一遍验证。用一个真实的小任务测试代理是否能按技能步骤正确执行。如果代理跳过了某个步骤或者执行结果不符合预期就修改技能描述直到它能稳定复现。最后把技能文件纳入代码审查流程。技能是团队共识的载体它的修改应该和代码修改一样被认真对待。我见过太多团队因为技能文件没人审查导致代理行为越来越混乱最后不得不放弃整个体系。这个方向还在快速演进我目前也在持续调整自己的技能配置。如果你也在用类似的方式管理AI编码代理欢迎交流你的经验和踩过的坑。 
长河君 · 2026/10/8 21:26:43 · 阅读 1.2k agent-skills实战：用技能体系让AI编码代理真正融入开发流程
1. 从“agent-skills”说起为什么AI编码代理需要一套技能体系第一次看到“agent-skills”这个词很多人会以为它只是某个仓库的名字或者某个AI工具的插件集合。但如果你真正在终端里跑过Claude Code、用过skills CLI、尝试过让AI代理帮你完成一个完整的开发任务你就会明白agent-skills本质上是一套让AI编码代理从“能聊天”进化到“能干活”的能力封装规范。我最初接触这个概念是在一个自动化重构项目里。当时我用Claude Code帮我改一个遗留的Python服务代码量大概三千行涉及数据库迁移、接口兼容和单元测试。第一次跑的时候AI代理确实能理解我的意图也能生成代码但问题在于它每次都要我重复描述项目结构、测试命令、代码风格约束。更麻烦的是它生成的测试用例经常不符合项目已有的pytest规范导致CI直接挂掉。后来我意识到问题不在于模型能力不够而在于我没有把“这个项目该怎么干活”这件事告诉它。agent-skills就是解决这个问题的。简单来说agent-skills是一组可复用的技能定义文件通常以Markdown或YAML格式存在放在项目的特定目录下。每个技能描述了一类任务的标准操作流程、约束条件和验证方式。当AI编码代理启动时它会自动加载这些技能从而知道“在这个项目里写测试要用什么框架”“提交代码前要跑哪些检查”“数据库迁移文件放在哪里”。这就像给一个新入职的工程师发了一本团队内部的操作手册而不是让他每次遇到问题都来问你。这套体系解决的核心问题是AI编码代理的上下文一致性和任务可复现性。没有agent-skills的时候你每次和AI代理对话都像是在重新培训一个新人有了agent-skills之后代理的行为变得可预测、可审计、可版本控制。对于团队协作来说这意味着你可以把“如何用AI代理完成某类任务”的最佳实践固化下来而不是靠某个人的提示词技巧。适合阅读这篇文章的人包括正在使用或准备使用Claude Code的开发者、需要为团队搭建AI编码工作流的技术负责人、对skills CLI和test-driven-development结合感兴趣的工具爱好者以及任何想让AI代理真正融入自己日常开发流程的人。不管你是刚接触AI编码代理的新手还是已经用过一段时间但觉得“效果不稳定”的老用户下面这些从实际项目中踩出来的经验应该都能帮到你。2. agent-skills的核心设计思路与方案选型2.1 为什么是“技能”而不是“提示词”很多人第一次听说agent-skills的时候会下意识地把它等同于“一套写得很好的提示词”。这个理解不能说错但不够准确。提示词是单次对话的输入而技能是跨会话、跨任务、跨项目成员共享的能力单元。两者的区别有点像“临时给同事发一条微信说怎么改这个bug”和“写一份团队内部的代码审查清单”。我试过两种方式。早期我是在Claude Code的对话里直接粘贴一大段项目说明包括目录结构、测试命令、代码规范。这种方式在单次任务里有效但每次新开一个会话就要重新粘贴而且一旦项目结构变了那段说明就过期了。更麻烦的是团队里其他人不知道我用了什么提示词他们和AI代理协作时得到的结果完全不一样。后来我转向agent-skills的方式在项目根目录下建一个.agent/skills/目录里面放若干个Markdown文件每个文件定义一个技能。比如run-tests.md里写清楚测试命令、测试文件命名规则、覆盖率要求code-style.md里写清楚格式化工具、lint规则、import排序方式。Claude Code在启动时会自动读取这个目录后续所有对话都基于这些技能约束来执行。这个转变带来的最大好处是可版本控制。技能文件跟着代码仓库一起提交新人克隆项目后他的AI代理自动就具备了和团队一致的“工作常识”。代码审查时如果发现AI代理总是犯某个错误我们可以直接修改对应的技能文件而不是在聊天记录里翻找当时的提示词。2.2 skills CLI的角色让技能可发现、可组合skills CLI是这套体系里的另一个关键组件。它的作用不是“运行技能”而是“管理技能”。你可以把它理解为一个轻量级的包管理器专门用来发现、安装、更新和组合agent-skills。我实际使用skills CLI的场景主要有三个。第一是初始化在一个新项目里运行skills init它会生成标准的技能目录结构和几个基础技能模板包括测试、代码风格、提交信息规范。第二是安装社区技能比如我想让AI代理支持TDD工作流可以直接skills install tdd-workflow它会从注册表拉取对应的技能定义并放到本地目录。第三是组合技能有些技能之间有依赖关系比如“数据库迁移”技能可能依赖“测试”技能skills CLI会自动解析这些依赖并确保加载顺序正确。为什么需要这样一个CLI工具因为手动管理技能文件在项目规模变大后会变得很痛苦。我见过一个项目有二十多个技能文件分散在不同目录有些是团队自研的有些是从社区复制的版本混乱更新时经常漏掉某个文件。skills CLI通过一个skills.json清单文件来记录所有技能的来源和版本更新时只需要skills update就能全部同步。2.3 与test-driven-development的天然契合agent-skills和test-driven-development的结合是我认为最有价值的一个设计方向。TDD的核心循环是“红-绿-重构”先写一个失败的测试然后写最少的代码让测试通过最后重构。这个循环对AI代理来说其实非常友好因为每一步都有明确的验证信号。我在一个Node.js项目里配置了TDD技能后AI代理的工作方式发生了明显变化。以前我让它“实现一个用户注册接口”它会直接生成路由、控制器、数据库操作和测试但测试往往是最后补的而且经常和实现不匹配。配置了TDD技能后代理会先写测试文件运行测试确认失败然后才写实现代码再运行测试确认通过。整个过程它会在终端里实际执行命令而不是只在对话里描述。这个技能定义的关键在于明确每一步的验证命令和预期输出。比如技能文件里会写“写测试后运行npm test -- --grep 用户注册预期看到至少一个失败用例实现后再次运行同一命令预期全部通过。”这样AI代理就知道什么时候该继续什么时候该停下来检查。2.4 方案选型的几个关键取舍在设计agent-skills体系时有几个取舍点值得展开说。第一个取舍是技能粒度。技能太粗比如一个“后端开发”技能包揽所有事情代理就失去了灵活性技能太细比如“写一个Express路由”单独成一个技能又会导致技能文件数量爆炸。我的经验是按“任务类型”而不是“代码单元”来划分。测试、迁移、部署、代码审查、文档更新这些是任务类型而“写控制器”“写模型”是代码单元不应该单独成技能。第二个取舍是技能文件的格式。Markdown可读性最好适合人类维护YAML结构化程度高适合程序解析。我目前的做法是混合技能的主体描述用Markdown但元数据如依赖、触发条件、验证命令用YAML front matter放在文件开头。这样既方便人读也方便skills CLI解析。第三个取舍是是否允许代理修改技能。有些团队希望AI代理在发现技能不完善时自动更新技能文件。我个人的做法是禁止自动修改但允许代理在对话中建议修改。因为技能文件是团队共识的载体自动修改会破坏这种共识的严肃性。代理可以提出“这个测试命令似乎过期了建议更新为xxx”但最终修改由人来做。3. 核心细节解析与实操要点3.1 技能文件的标准结构一个完整的agent-skill文件通常包含四个部分元数据、适用场景、操作步骤、验证方式。我拿一个实际项目里的database-migration.md来举例说明。元数据部分用YAML front matter写在文件最上方--- name: database-migration version: 1.2.0 dependencies: - run-tests triggers: - 创建迁移 - 修改表结构 - 添加字段 ---这里name是技能唯一标识version用于版本管理dependencies声明依赖的其他技能triggers是触发关键词。当用户在对话中提到“给用户表加一个手机号字段”时Claude Code会匹配到triggers里的“添加字段”自动加载这个技能。适用场景部分用自然语言描述这个技能解决什么问题、不解决什么问题。比如“本技能适用于使用Prisma作为ORM的PostgreSQL数据库迁移。不适用于MongoDB或手写SQL迁移的场景。”这部分看起来简单但非常重要因为它防止代理在不合适的场景下错误应用技能。操作步骤部分是核心需要写得足够具体让代理能按步骤执行。我通常会写成有序列表每一步都包含具体的命令或文件路径。比如在prisma/schema.prisma中修改模型定义运行npx prisma migrate dev --name 迁移名称生成迁移文件检查生成的SQL文件是否符合预期运行npx prisma generate更新客户端执行npm run test:db验证迁移不影响现有测试验证方式部分定义“怎么算完成了”。这一步是很多技能文件缺失的导致代理不知道什么时候该停。我会写清楚具体的命令和预期输出比如“运行npm run test:db预期所有测试通过且输出中不包含migration failed字样。”3.2 技能加载的优先级与冲突处理当一个项目里有多个技能文件时加载顺序和冲突处理就变得很重要。我遇到过的情况是一个通用技能说“提交前运行npm test”另一个项目特定技能说“提交前运行npm run test:ci”。两个技能都匹配当前场景代理该听谁的我的处理原则是具体优先于通用。在技能元数据里可以加一个priority字段数值越大优先级越高。项目特定技能的priority设为100通用技能设为10。当冲突发生时高优先级技能覆盖低优先级技能的同名步骤。另一个原则是后加载覆盖先加载。skills CLI在加载技能时按依赖顺序排列被依赖的技能先加载依赖别人的后加载。如果两个技能没有依赖关系按文件名字母序加载。这个规则需要在团队内达成共识否则不同人本地加载顺序不一致会导致代理行为不一致。我还建议在技能文件里显式声明“本技能覆盖哪些技能”。比如项目特定的测试技能可以写overrides: [run-tests]这样skills CLI在加载时会自动禁用被覆盖的技能避免冲突。3.3 如何写出代理能“看懂”的操作步骤这是我在实践中踩坑最多的地方。一开始我写的技能文件像给人看的文档比如“确保代码质量”“遵循项目规范”。结果代理完全不知道该怎么执行因为它需要的是可操作的具体指令。后来我总结了一个原则每个步骤必须包含一个可执行的命令或一个可检查的文件状态。比如“确保代码质量”应该写成“运行npm run lint如果输出中有error则修复对应文件后重新运行直到输出为空”。再比如“遵循项目规范”应该写成“检查src/下所有新建的.ts文件确保每个文件头部有// ts-check注释如果没有则添加”。另一个技巧是用条件语句描述分支逻辑。代理在执行技能时需要知道“如果A情况则做X如果B情况则做Y”。比如数据库迁移技能里可以写“如果迁移涉及删除列则先运行npm run test:db确认没有测试依赖该列如果迁移只涉及添加列则直接执行迁移。”这种条件描述让代理能根据实际情况调整行为。还有一个容易忽略的点是错误处理。技能文件里应该写清楚“如果某一步失败了该怎么办”。比如“如果npx prisma migrate dev失败检查prisma/migrations/目录下是否有冲突的迁移文件如果有则手动解决冲突后重新运行”。没有错误处理的技能代理在遇到失败时往往会卡住或者胡乱尝试。3.4 技能与项目目录的绑定方式agent-skills放在哪里决定了它的作用范围。我目前采用三级目录结构项目根目录的.agent/skills/项目特定技能只对当前项目生效用户主目录的.agent/skills/个人通用技能对所有项目生效skills CLI的全局注册表社区共享技能通过skills install安装到本地加载优先级是项目特定 个人通用 社区共享。这样设计的好处是我可以在个人通用技能里放一些“我习惯用vim”“我偏好函数式风格”之类的个人偏好而在项目特定技能里放“这个项目用Prisma”“这个项目测试覆盖率要求80%”之类的项目约束。需要注意的是项目特定技能应该提交到代码仓库个人通用技能不应该提交。我在.gitignore里加了.agent/skills/local/来排除个人技能目录只提交.agent/skills/project/。这样团队共享的是项目约束个人偏好不会污染仓库。4. 实操过程与核心环节实现4.1 从零搭建一个agent-skills工作流我拿一个真实的Express TypeScript项目来演示完整搭建过程。这个项目有大约五十个接口使用Jest做测试Prisma做数据库访问。第一步是安装skills CLI。在项目根目录运行npm install -g agent-skills/cli skills initskills init会生成.agent/skills/目录和skills.json清单文件。默认会创建三个基础技能code-style.md、run-tests.md、commit-message.md。我通常会先修改这三个文件让它们符合项目实际情况。run-tests.md的修改重点是测试命令和测试文件命名规则。这个项目用的是npm test测试文件放在src/**/*.test.ts。我会在技能里写清楚“运行npm test执行所有测试运行npm test -- --testPathPattern模块名执行单个模块测试测试文件必须与被测文件同目录命名格式为文件名.test.ts。”code-style.md需要写清楚格式化工具和lint规则。这个项目用ESLint Prettier我会写“提交前运行npm run lint:fix自动修复格式问题import顺序按eslint-plugin-import规则排序禁止使用any类型除非在注释中说明理由。”第二步是添加项目特定技能。我创建了database-migration.md和api-endpoint.md两个文件。api-endpoint.md定义了新增接口的标准流程先在src/routes/下创建路由文件然后在src/controllers/下创建控制器再在src/services/下创建服务层最后在src/__tests__/下创建集成测试。每一步都有对应的文件路径和命名规范。第三步是配置Claude Code加载技能。在项目根目录的.claude/config.json里添加{ skills: { enabled: true, directory: .agent/skills, autoLoad: true } }这样Claude Code启动时会自动读取技能目录。我实测下来从启动到技能加载完成大约需要两到三秒对于日常开发来说完全可以接受。4.2 用TDD技能完成一个真实功能我拿“用户手机号绑定”这个功能来演示TDD技能的实际执行过程。这个功能的需求是用户可以在个人设置页面绑定手机号绑定后可以通过手机号登录。在配置了TDD技能的情况下我在Claude Code里输入“实现用户手机号绑定功能包括数据库字段、接口和测试。”代理的执行过程如下。首先它读取了tdd-workflow.md技能确认工作流程是“先写测试再写实现”。然后它读取了database-migration.md技能知道需要先修改Prisma schema。它先在prisma/schema.prisma的User模型里添加了phone String? unique字段然后运行npx prisma migrate dev --name add_phone_to_user生成迁移文件。接着它进入TDD循环。第一步写测试在src/__tests__/phone-binding.test.ts里写了三个测试用例——绑定成功、绑定已存在的手机号返回错误、未登录用户绑定返回401。然后运行npm test -- --testPathPatternphone-binding预期看到三个失败用例。代理在终端里实际执行了这个命令确认测试失败。第二步写实现在src/services/user.service.ts里添加bindPhone方法在src/controllers/user.controller.ts里添加对应的控制器方法在src/routes/user.routes.ts里注册路由。然后再次运行测试命令这次预期全部通过。代理执行后确认三个测试都通过了。第三步重构代理检查了新增代码是否符合code-style.md里的规范发现bindPhone方法有点长于是拆分成两个小方法。然后再次运行测试确认重构没有破坏功能。整个过程代理在终端里执行了六次命令每次都有明确的预期输出。我只需要在最后审查一下代码确认业务逻辑正确即可。这个功能从开始到完成大约用了八分钟其中大部分时间是代理在写代码和运行测试我实际参与的时间不到两分钟。4.3 技能文件的版本管理与团队协作当团队有多个人使用agent-skills时版本管理就变得很重要。我的做法是把.agent/skills/目录纳入Git管理但遵循几条规则。第一条规则是技能变更需要代码审查。技能文件修改和代码修改一样需要走Pull Request流程。审查重点是新技能是否与现有技能冲突、操作步骤是否可执行、验证方式是否明确。我见过一个团队因为技能文件没有审查导致某个人加了一个“提交前运行npm run deploy”的技能结果AI代理在每次提交时都尝试部署到生产环境。第二条规则是技能版本与项目版本对齐。在skills.json里记录每个技能的版本号当项目发布新版本时检查技能是否需要同步更新。比如项目从Express迁移到Fastifyapi-endpoint.md技能里的框架相关命令就需要更新。第三条规则是定期清理过期技能。我每季度会检查一次技能目录删除不再使用的技能合并重复的技能。一个超过六个月没有被任何对话触发的技能大概率已经过期了。4.4 技能执行日志与效果评估为了知道技能是否真的在起作用我会让Claude Code记录技能执行日志。在.claude/config.json里开启日志{ logging: { skills: true, logFile: .agent/logs/skills.log } }日志会记录每次对话中加载了哪些技能、执行了哪些步骤、验证结果如何。我每周会花十分钟看一下日志主要关注三个指标技能触发频率、步骤失败率、平均执行时间。技能触发频率反映哪些技能真正被用到。如果一个技能一个月都没有被触发要么是触发关键词设置不对要么是这个技能根本不需要。步骤失败率反映技能的可执行性。如果某个技能的某一步经常失败说明这一步的描述可能有问题需要优化。平均执行时间反映技能是否过于冗长。如果一个简单任务因为加载了太多技能而变慢就需要考虑拆分或精简技能。我实测下来一个配置良好的agent-skills体系可以把AI代理的任务完成率从大约60%提升到85%以上。剩下的15%失败案例大部分是因为需求本身模糊或者涉及项目外的依赖这些不是技能能解决的。5. 常见问题与排查技巧实录5.1 技能不生效的排查思路这是最常见的问题明明配置了技能文件但AI代理的行为没有任何变化。我总结了一个排查顺序按这个顺序走基本能定位到问题。第一步检查技能目录路径是否正确。Claude Code默认读取.agent/skills/如果你放在.claude/skills/或者skills/它不会自动加载。我建议在项目根目录运行skills list命令它会列出当前加载的所有技能。如果列表为空说明路径配置有问题。第二步检查技能文件格式是否正确。YAML front matter必须以---开头和结尾中间不能有语法错误。我遇到过因为triggers列表里用了中文引号导致解析失败的情况。可以用skills validate命令检查所有技能文件的格式。第三步检查触发关键词是否匹配。技能只有在对话内容匹配triggers时才会加载。如果你说“帮我改一下用户表”但技能的trigger是“数据库迁移”它就不会触发。我通常会在trigger里加多个同义词比如[数据库迁移, 改表, 加字段, 修改schema]。第四步检查技能优先级是否被覆盖。如果两个技能冲突高优先级的会覆盖低优先级的。可以在日志里看到实际加载了哪个技能。如果发现加载的不是你期望的技能检查一下priority设置。5.2 代理执行技能时卡住的常见原因代理在执行技能步骤时卡住通常是因为某一步的预期结果不明确或者命令执行失败后没有处理逻辑。一个典型场景是测试命令返回了非零退出码但技能里只写了“运行测试”没有写“如果测试失败该怎么办”。代理会停在那一页反复运行同一个命令。解决方法是在技能里加错误处理分支“如果npm test返回非零退出码检查失败用例的输出修复对应代码后重新运行。如果连续三次失败停止并输出失败原因。”另一个场景是命令需要交互式输入。比如npx prisma migrate dev在某些情况下会询问迁移名称。如果技能里没有提供--name参数代理会卡在等待输入。解决方法是在技能里写清楚所有需要预先提供的参数。还有一个场景是文件路径不存在。代理尝试读取一个不存在的文件时会报错如果技能里没有说明“如果文件不存在则创建”它就会卡住。我通常会在涉及文件操作的步骤里加上“如果文件不存在先创建空文件”的说明。5.3 技能冲突与覆盖的实战案例我遇到过一个真实的冲突案例项目里有两个技能都定义了“提交前检查”。code-style.md说“提交前运行npm run lint”run-tests.md说“提交前运行npm test”。两个技能同时加载时代理只执行了其中一个导致另一个检查被跳过。解决方法是引入一个pre-commit.md技能专门定义提交前的完整检查流程并在元数据里声明overrides: [code-style, run-tests]。这样加载pre-commit时另外两个技能的提交前步骤会被自动禁用避免冲突。这个案例给我的教训是技能之间的边界要清晰。每个技能应该只负责一个任务类型提交前检查这种跨任务类型的流程应该单独成一个技能。我现在会在技能设计阶段就画一个依赖图确保没有两个技能定义相同的步骤。5.4 常见问题速查表问题现象可能原因排查方法解决方案技能完全不生效目录路径错误运行skills list确认技能在.agent/skills/下技能偶尔生效触发关键词不匹配查看日志中的触发记录增加同义词到triggers代理执行到一半卡住缺少错误处理分支检查技能文件是否有失败处理补充“如果失败则...”逻辑两个技能行为矛盾优先级冲突查看日志中加载的技能顺序设置priority或使用overrides技能更新后不生效缓存未刷新重启Claude Code运行skills reload代理忽略技能步骤步骤描述不可执行检查步骤是否有具体命令改为可执行的命令或文件检查技能加载太慢技能文件过多查看加载日志耗时合并或删除不常用技能5.5 几个我踩过的坑和对应的技巧第一个坑是技能文件写得太长。我一开始写了一个三百行的backend-development.md结果代理加载后经常忽略中间步骤。后来我把它拆成五个小技能每个不超过八十行执行效果明显改善。技巧是一个技能文件如果超过一百行就应该考虑拆分。第二个坑是在技能里写死绝对路径。我写过/Users/myname/project/src/这样的路径结果团队其他人克隆项目后技能完全不能用。技巧是所有路径都相对于项目根目录用src/而不是绝对路径。第三个坑是技能里的命令依赖全局安装的工具。我写了一个技能用ts-node运行脚本但团队新人的机器上没有全局安装ts-node。技巧是所有命令都用npx前缀确保使用项目本地依赖。第四个坑是技能没有版本号。当技能更新后代理有时会混用新旧版本的步骤。技巧是每个技能文件都加version字段skills CLI会在加载时检查版本一致性。第五个坑是忽略技能的测试。我修改技能后直接投入使用结果代理执行时才发现步骤有误。技巧是修改技能后用一个简单的测试任务验证一遍确认代理能按新步骤正确执行。6. 技能体系的扩展与个人经验分享6.1 从单项目到多项目的技能复用当你在多个项目之间切换时每个项目都维护一套技能文件会很累。我的做法是建立一个“基础技能层”和“项目技能层”的两层结构。基础技能层放在用户主目录的.agent/skills/base/下包含所有项目通用的技能比如git-commit.md、code-review.md、debugging.md。这些技能不涉及具体技术栈只定义通用工作流程。项目技能层放在各项目根目录的.agent/skills/下只包含项目特定的技能比如database-migration.md、api-endpoint.md。项目技能可以依赖基础技能但不能反过来。这样设计的好处是当我换到一个新项目时只需要配置项目技能基础技能自动继承。我实测下来新项目初始化时间从原来的半小时缩短到五分钟。6.2 技能与CI/CD的联动agent-skills不仅可以用于本地开发还可以和CI/CD流水线联动。我在GitHub Actions里加了一个步骤在运行测试前先检查技能文件是否与代码一致。具体做法是在CI里运行skills validate --strict它会检查所有技能文件格式是否正确、依赖是否满足、版本是否一致。如果技能文件有语法错误或者依赖缺失CI会直接失败。这个检查帮我避免了好几次因为技能文件错误导致的代理行为异常。另一个联动点是技能驱动的代码生成。我配置了一个技能当检测到src/routes/下有新文件时自动生成对应的测试文件骨架和API文档骨架。这个技能在CI里以“检查模式”运行如果发现新路由没有对应测试就输出警告。6.3 我个人在实际操作中的体会用了大半年agent-skills之后我最大的体会是这套体系的价值不在于让AI代理更聪明而在于让它的行为更可预测。模型本身的能力已经很强了但它的输出质量波动很大同样的需求今天做得好明天做得差。技能体系通过固化操作流程和验证标准把这种波动控制在一个可接受的范围内。另一个体会是技能文件需要持续迭代。我最初写的技能文件现在回头看有很多问题比如步骤太粗、验证不明确、错误处理缺失。每次代理执行失败我都会问自己是模型能力不够还是技能没写清楚大部分时候是后者。把失败案例转化为技能改进是提升整体效率的最快路径。还有一个反直觉的发现技能不是越多越好。我一度给项目加了二十多个技能结果代理加载时间变长而且经常在多个技能之间混淆。后来精简到八个核心技能执行效果反而更好。我的经验是一个项目的技能数量控制在五到十个之间比较合适超过十五个就需要考虑合并或分层。6.4 后续可以扩展的方向如果你已经跑通了基础的agent-skills工作流有几个方向可以继续深入。第一个方向是技能的市场化共享。skills CLI支持从远程注册表安装技能你可以把自己团队沉淀的技能发布上去也可以安装别人分享的技能。我目前关注的是测试和重构类的技能这两个领域的最佳实践比较通用。第二个方向是技能与代码审查的深度集成。我尝试过让AI代理在代码审查时自动检查提交是否符合技能定义的标准比如“新增的API是否有对应的测试文件”“数据库迁移是否有回滚方案”。这个方向还在探索中目前的效果是能发现大约七成的不规范提交。第三个方向是技能执行数据的分析。通过收集技能执行日志可以分析哪些技能最常用、哪些步骤最容易失败、哪些技能组合效果最好。这些数据可以用来优化技能设计也可以用来评估AI代理在团队中的实际贡献。第四个方向是技能与项目文档的同步。我理想中的状态是技能文件既是AI代理的操作手册也是人类开发者的项目文档。新人加入项目时读一遍技能文件就能了解项目的开发流程和规范。目前我还在调整技能文件的写法让它对人类和代理都友好。6.5 给刚接触agent-skills的朋友几个实用建议如果你刚开始接触agent-skills我建议从最小的技能开始。不要一上来就写一个覆盖整个开发流程的大技能而是先写一个run-tests.md把测试命令和测试文件规范写清楚。这个技能最简单也最容易看到效果。然后逐步添加技能。每当你发现自己在对话里重复描述同一件事超过三次就应该考虑把它写成一个技能。比如你总是要告诉代理“这个项目用pnpm不用npm”那就写一个package-manager.md技能。技能写好后一定要实际跑一遍验证。用一个真实的小任务测试代理是否能按技能步骤正确执行。如果代理跳过了某个步骤或者执行结果不符合预期就修改技能描述直到它能稳定复现。最后把技能文件纳入代码审查流程。技能是团队共识的载体它的修改应该和代码修改一样被认真对待。我见过太多团队因为技能文件没人审查导致代理行为越来越混乱最后不得不放弃整个体系。这个方向还在快速演进我目前也在持续调整自己的技能配置。如果你也在用类似的方式管理AI编码代理欢迎交流你的经验和踩过的坑。