1. 从“agent-skills”说起为什么AI编码代理需要一套技能库第一次看到agent-skills这个项目名很多人会以为它又是一个“提示词合集”或者“工具函数包”。但如果你最近深度用过 Claude Code、Cursor、Windsurf 这类 AI coding agents就会发现一个很现实的问题模型本身很聪明可一旦落到具体项目里它经常不知道“这个团队到底怎么做事”。比如提交前必须跑哪些测试、代码风格用哪套规范、数据库迁移脚本放在哪个目录、接口文档更新流程是什么。这些知识不在模型参数里也不在通用文档里它散落在团队日常的肌肉记忆里。agent-skills要解决的就是这件事。它本质上是一套面向 AI coding agents 的技能描述与执行框架通过skills CLI把“项目上下文、操作规范、验证步骤”组织成代理可读取、可调用、可复用的技能单元。你可以把它理解成给 AI 代理配了一本“岗位操作手册”而不是每次都在对话里重复交代。它适合谁适合已经在用 Claude Code 做真实项目开发的人适合想把 test-driven-development 真正塞进 AI 工作流的人也适合那些被“AI 写代码很快但返工更多”折磨过的工程团队。我最初接触这个方向是因为一个很具体的痛点让 Claude Code 改一个订单状态机它改完代码后信誓旦旦说“已完成”结果一跑测试三个边界条件全挂。问题不在于模型不会写代码而在于它没有把“验证”当成技能的一部分。agent-skills的思路就是把技能拆成可组合的单元每个单元包含触发条件、操作步骤、验证方式和失败回退策略。这样一来AI 代理不再是“一次性问答机器”而是能按技能库执行任务的协作伙伴。提示如果你还没安装 Claude Code建议先完成基础环境配置再来看 agent-skills 的集成方式。否则很多 CLI 交互你会缺少直观感受。2. agent-skills 的核心设计思路拆解2.1 为什么不是“更大的提示词”而是“技能单元”很多人第一反应是我直接把所有规范写进 system prompt 不就行了我试过短期可行长期灾难。一个中型项目的规范文档动辄几千字全塞进上下文会导致两个问题一是 token 成本飙升二是模型注意力被稀释真正关键的那几条反而被忽略。agent-skills的做法是按需加载每个技能是一个独立单元代理在执行特定任务时才读取对应技能用完即走。这背后的逻辑和人类团队管理是一样的。你不会让一个新员工入职第一天背完公司所有制度而是告诉他“部署服务时看这份文档写数据库迁移时看那份文档”。技能单元就是这种“按场景索引的知识包”。它的优势在于可维护、可测试、可版本控制。你可以给每个技能写单元测试验证代理在给定输入下是否按预期执行。2.2 skills CLI 的角色技能库的包管理器skills CLI是这个项目里最容易被低估的部分。它不只是“安装工具”更像是技能库的包管理器加运行时。常见操作包括初始化技能目录、拉取远程技能、本地调试技能、把技能注入到 Claude Code 的上下文里。我实测下来它解决了一个很烦的问题不同项目需要不同技能组合手动复制粘贴容易出错用 CLI 可以做到声明式管理。举个例子你有一个前端项目和一个后端项目。前端项目需要“组件测试技能”“可访问性检查技能”后端项目需要“数据库迁移技能”“接口契约测试技能”。通过skills CLI你可以为每个项目维护独立的技能清单切换项目时自动加载对应技能。这种隔离性对多项目并行的开发者来说非常实用。2.3 与 test-driven-development 的深度绑定热词里出现test-driven-development不是偶然。agent-skills的设计哲学里测试不是事后补充而是技能执行的前置条件。一个典型的技能定义会包含前置检查、操作步骤、验证命令、预期输出、失败处理。这五段式结构天然契合 TDD 的 red-green-refactor 循环。我自己的做法是把“写测试”和“写实现”拆成两个技能。代理先调用“测试编写技能”生成失败测试再调用“实现技能”让测试通过最后调用“重构技能”在测试保护下优化代码。这样每一步都有明确验证点不会出现“改了一大堆最后不知道哪里坏了”的情况。相比让模型一次性生成所有代码这种分步技能执行虽然慢一点但返工率大幅下降。3. 核心细节解析与实操要点3.1 技能目录结构约定优于配置一个标准的 agent-skills 项目目录通常长这样.agent-skills/ skills/ test-driven-development/ SKILL.md scripts/ run-tests.sh fixtures/ example-input.json code-review/ SKILL.md checklist.md config.jsonSKILL.md是技能的核心描述文件里面用结构化格式写明技能名称、触发条件、输入输出、执行步骤和验证方式。scripts/放可执行脚本fixtures/放测试数据。config.json定义技能加载顺序和依赖关系。这种结构的精髓是约定优于配置只要按规范放置文件CLI 就能自动发现和加载不需要额外写注册代码。注意技能名称建议用短横线分隔的小写英文避免空格和特殊字符。我踩过一次坑用了中文技能名结果在某些终端环境下路径解析出错排查了半小时。3.2 SKILL.md 的写法让代理“看得懂、做得到”SKILL.md不是写给人类看的普通文档它需要兼顾可读性和可解析性。我的经验是采用“YAML frontmatter Markdown 正文”的混合格式。Frontmatter 放元数据正文放操作说明。元数据包括技能名、版本、适用代理、依赖技能。正文用编号步骤描述操作流程每一步都尽量具体到命令级别。比如一个“运行单元测试”的技能正文不会写“请运行测试”而是写“在项目根目录执行npm test -- --watchAllfalse如果退出码非零读取test-results.xml并提取失败用例名称”。这种具体程度直接决定代理能否可靠执行。我见过太多技能文档写得像散文代理读完还是一头雾水。3.3 技能加载与上下文注入机制skills CLI加载技能时并不是把所有技能全文塞进上下文。它通常采用索引加按需读取的策略先加载技能名称和简短描述代理判断需要某个技能时再通过工具调用读取完整内容。这样做的好处是上下文占用小代理决策速度快。实操中你可以在 Claude Code 的配置里指定技能目录然后通过自然语言触发。比如你说“帮我给这个函数补测试”代理会先匹配到test-driven-development技能读取完整步骤然后按步骤执行。这里的关键是触发词设计技能描述里要包含足够多的同义触发词否则代理可能匹配不到。我一般会在技能描述里列出五到八个常见说法覆盖不同表达习惯。3.4 验证环节的设计别让代理“自说自话”这是我认为 agent-skills 最有价值的部分。很多 AI 编码工具的通病是代理说“已完成”但你不知道它到底做了什么。agent-skills要求每个技能必须定义可执行的验证命令和预期输出。验证命令可以是测试套件、lint 检查、类型检查、构建命令甚至是自定义脚本。我通常会把验证分成三层第一层是语法和类型检查快速失败第二层是单元测试验证逻辑正确性第三层是集成测试或端到端测试验证系统行为。代理每完成一个技能步骤都要跑对应验证。如果验证失败技能定义里要写明回退策略是重试、是回滚、还是请求人工介入。这种设计让 AI 编码从“黑盒生成”变成“白盒执行”。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 skills CLI 的安装配置先确保 Claude Code 可用。不同系统安装方式略有差异Mac 和 Ubuntu 下通常通过包管理器或官方脚本安装。安装完成后在项目根目录初始化 agent-skillsskills init这个命令会创建.agent-skills/目录和默认配置文件。接着安装技能包skills install test-driven-development skills install code-review如果你有私有技能库也可以指定远程地址。安装完成后用skills list确认技能已就绪。然后在 Claude Code 的配置中启用技能目录通常是在项目级配置里加一行skillsPath: .agent-skills/skills。重启 Claude Code 后代理就能感知到技能库的存在。提示如果你在 VS Code 里用 Claude Code 插件配置路径可能需要在插件设置里单独指定。我建议先用终端版验证技能加载正常再迁移到插件环境。4.2 编写第一个技能以“新增 API 端点”为例假设我们要让代理学会“新增一个 REST API 端点”。这个技能涉及路由注册、控制器编写、参数校验、单元测试、接口文档更新。手动做要半小时写成技能后代理可以自动执行。先创建技能目录mkdir -p .agent-skills/skills/add-api-endpoint/scripts然后写SKILL.md--- name: add-api-endpoint version: 1.0.0 triggers: - 新增接口 - 添加API - 创建端点 dependencies: - test-driven-development --- ## 步骤 1. 在 src/routes/ 下创建路由文件命名遵循 kebab-case。 2. 在 src/controllers/ 下创建控制器导出处理函数。 3. 在 src/validators/ 下添加请求参数校验 schema。 4. 在 tests/ 下添加对应单元测试覆盖正常和异常分支。 5. 运行 npm test -- --testPathPattern新端点名确保测试通过。 6. 更新 docs/api.md添加端点说明。 ## 验证 - 测试命令退出码为 0。 - lint 检查无错误。 - 文档文件包含新端点路径。写完后用skills validate add-api-endpoint检查格式。然后在 Claude Code 里说“帮我新增一个用户查询接口”代理应该能匹配到这个技能并按步骤执行。4.3 技能执行现场一次真实的订单状态机改造我拿一个真实场景演示。需求是订单状态从“待支付”变为“已支付”时需要校验支付金额、更新库存、发送通知。这个任务涉及多个技能组合。代理首先匹配到test-driven-development技能生成失败测试def test_order_paid_updates_inventory(): order create_order(statuspending, amount100) pay_order(order.id, amount100) assert order.status paid assert inventory.get(order.item_id) initial_stock - 1测试运行失败符合预期。接着代理匹配到implement-feature技能编写实现代码。实现完成后再次运行测试通过。然后代理匹配到code-review技能检查是否有遗漏的边界条件比如金额不匹配、库存不足、重复支付。发现重复支付未处理补充测试和实现。最后运行完整测试套件和 lint全部通过。整个过程我只需要在关键决策点确认比如“库存不足时是抛异常还是返回错误码”。这种协作模式比我自己写快很多而且因为每步都有验证质量可控。4.4 参数计算与选择技能粒度怎么定技能粒度太粗代理执行时容易迷失太细调用次数太多效率低。我的经验法则是一个技能对应一个可独立验证的交付物。比如“新增 API 端点”是一个技能因为端点完成后可以独立测试。“重构数据库访问层”也是一个技能因为重构后可以跑回归测试。但“优化代码”太模糊不适合作为技能。另一个参数是技能依赖深度。我建议依赖层级不超过三层。A 依赖 BB 依赖 C可以A 依赖 BB 依赖 CC 依赖 D就太深了调试困难。如果发现依赖太深考虑合并或拆分技能。5. 常见问题与排查技巧实录5.1 技能匹配失败代理为什么不调用我的技能最常见的原因是触发词不够。代理匹配技能靠的是语义相似度如果你的技能描述里只有“新增接口”用户说“加一个路由”可能就匹配不到。解决办法是在triggers里尽量多列同义表达包括中英文、口语和书面语。另一个原因是技能加载失败用skills list确认技能是否在列表中。如果不在检查目录结构和config.json路径配置。5.2 验证命令执行超时或挂起有些测试命令会进入 watch 模式导致代理一直等待。解决办法是在技能定义里明确加上非交互参数比如--watchAllfalse、--ci、--no-interactive。另外给验证命令设置超时时间超过时间视为失败。我在config.json里统一配置了 120 秒超时避免个别技能卡死整个流程。5.3 代理跳过验证步骤直接说“完成”这是最危险的情况。原因通常是技能描述里验证步骤不够显眼或者代理认为任务简单就偷懒。解决办法有两个一是把验证步骤放在技能正文最前面用加粗强调二是在 CLI 层面强制验证代理不跑验证命令就无法标记技能完成。我倾向于第二种因为靠提示词约束代理始终不够可靠。5.4 多技能冲突两个技能都想改同一个文件当多个技能涉及同一文件时可能出现冲突。比如add-api-endpoint和update-api-docs都要改docs/api.md。解决办法是在技能依赖里声明顺序或者把文档更新合并到端点技能里。我的做法是能合并的合并不能合并的用依赖锁顺序。冲突检测可以在 CLI 里加一个预检查发现同一文件被多个技能修改时给出警告。5.5 常见问题速查表问题现象可能原因排查方法解决措施代理不调用技能触发词不足查看技能描述补充同义触发词技能加载失败目录结构错误运行skills list检查路径和配置验证命令挂起进入交互模式查看命令输出添加非交互参数代理跳过验证技能描述不明确检查 SKILL.md强制验证或加粗提示多技能文件冲突依赖顺序未定义查看依赖配置合并技能或加锁技能执行结果不稳定上下文不足检查输入数据补充 fixtures 和示例注意技能库需要版本控制。每次修改技能后提交到 Git这样出问题可以回滚。我吃过亏改了一个技能后代理行为异常因为没有版本记录排查了很久。6. 技能库的维护与团队协作经验6.1 技能评审像评审代码一样评审技能技能写完后不能直接合并要经过评审。评审重点包括触发词是否覆盖常见说法、步骤是否具体到可执行、验证命令是否可靠、失败处理是否明确。我们团队的做法是每个技能至少两人评审一人写一人跑。跑的人按照技能描述手动执行一遍看是否顺畅。如果人工执行都卡壳代理更不可能顺利执行。6.2 技能复用与组合避免重复造轮子随着技能增多会出现重复。比如多个技能都需要“运行测试”那就把“运行测试”抽成基础技能其他技能依赖它。agent-skills支持技能组合一个技能可以调用另一个技能。我的经验是基础技能保持稳定上层技能灵活组合。基础技能改动要谨慎因为影响面大。6.3 技能效果度量怎么知道技能有没有用我跟踪三个指标首次通过率、平均执行时间、人工介入次数。首次通过率指代理第一次执行技能就验证通过的比例。平均执行时间指从触发到完成的时间。人工介入次数指需要我手动干预的次数。这三个指标能直观反映技能质量。如果首次通过率低说明技能描述或验证有问题如果人工介入多说明技能粒度或触发设计有问题。6.4 与 Claude Code 工作流的深度集成Claude Code 支持自定义命令和工具调用可以把技能触发绑定到特定命令。比如配置/tdd命令直接触发 test-driven-development 技能。这样日常开发中我只需要输入简短命令代理就按技能库执行。集成时注意权限控制有些技能涉及文件删除或数据库操作要加确认步骤避免代理误操作。7. 从 agent-skills 看 AI 编码代理的演进方向用了几个月 agent-skills我最大的感受是AI 编码代理的瓶颈正在从“模型能力”转向“工程化能力”。模型写代码越来越强但怎么让它在真实项目里稳定、可靠、可验证地工作是另一回事。agent-skills这类项目代表了一个方向把软件工程的最佳实践——版本控制、测试驱动、代码评审、持续集成——翻译成代理能理解和执行的技能单元。这个方向后续可以扩展的地方很多。比如技能市场团队之间共享和交易技能包比如技能自动生成从代码提交历史里挖掘常用操作模式比如技能效果分析用数据驱动技能优化。我现在已经在尝试把日常重复性操作都技能化让代理承担更多执行工作自己专注于决策和设计。这个过程不是一蹴而就的但每技能化一个流程就少一份重复劳动多一份质量保障。最后分享一个小技巧刚开始不要贪多先挑一个你最熟悉、最稳定的流程写成技能跑通后再扩展。我第一个技能是“运行单元测试”简单但高频跑通后信心大增。技能库是长出来的不是设计出来的。