1. 从“agent-skills”说起为什么AI编程助手需要一套技能体系第一次看到“agent-skills”这个词很多人会以为它只是某个开源仓库的名字。但如果你真正在终端里跑过Claude Code、用过skills CLI、尝试过让AI coding agents帮你完成一个完整功能你就会明白agent-skills本质上是一套让AI编程助手从“会聊天”变成“会干活”的能力封装规范。我最初接触这个概念是在一个内部工具链项目里。当时团队用Claude Code做日常开发辅助写单测、改bug、重构小模块都挺顺手但一旦涉及跨文件、多步骤的任务比如“给这个模块补一套集成测试并跑通”AI就开始丢三落四——要么忘了改配置文件要么测试写完不执行要么执行了但没检查结果。后来我们发现问题不在于模型能力不够而在于缺少一套可复用、可组合、可验证的技能定义。agent-skills就是来解决这个问题的。简单来说agent-skills是一组结构化的指令包每个skill描述了一类具体任务的操作流程、约束条件和验证标准。它可以是“写一个符合TDD规范的单元测试”也可以是“用skills CLI初始化一个项目脚手架”还可以是“在Claude Code里执行终端命令并解析输出”。这些skill被AI coding agents加载后就相当于给AI装上了一本操作手册让它知道在什么场景下该调用什么工具、按什么顺序执行、遇到什么情况该停下来确认。这套东西适合谁三类人最应该关注第一类是日常使用Claude Code或类似AI编程助手的开发者你不需要自己写skill但理解它的机制能让你更高效地指挥AI干活第二类是团队里的工具链维护者你需要为团队定制一套skill库让不同成员用AI时行为一致、输出可控第三类是对AI coding agents底层机制好奇的技术爱好者你想知道skills CLI到底在做什么、test-driven-development怎么和AI结合。我写这篇东西的出发点很简单网上关于Claude Code安装、vscode配置claude code、claude code使用的内容已经很多了但很少有人把agent-skills这套机制讲清楚。很多人卡在“claude code harness可以不登录用其他模型吗”这种问题上其实背后就是对skill加载和模型路由的关系没搞明白。下面我会从设计思路、核心细节、实操过程、常见问题四个维度把agent-skills这套东西拆开讲透。2. 内容整体设计与思路拆解2.1 为什么不是“一个万能提示词”而是“技能集合”很多人第一反应是我写一个超长的系统提示词把所有规则都塞进去不就行了我试过不行。原因有三个。第一上下文窗口是有限资源。你把所有场景的规则都写进系统提示AI在每次对话时都要重新消化一遍token消耗大不说还容易“注意力分散”——该关注当前任务细节的时候它被无关规则干扰了。agent-skills的做法是按需加载当前任务涉及测试就只加载test-driven-development相关的skill涉及CLI操作就只加载skills CLI的skill。这样AI的注意力始终聚焦在当前任务上。第二技能需要版本管理和复用。一个团队里不同项目可能都需要“写单测”这个能力。如果每个项目都复制一份提示词改一处就要同步多处维护成本极高。agent-skills把每个技能做成独立文件可以单独版本控制、单独测试、单独发布。skills CLI就是用来管理这些技能文件的工具类似npm之于JavaScript包。第三验证标准需要独立于执行逻辑。一个skill不仅告诉AI“怎么做”还告诉它“做到什么程度算完成”。比如test-driven-development这个skill它明确规定先写测试、测试必须失败、再写实现、测试必须通过、最后重构。每一步都有明确的验证点。如果只是写在系统提示里AI很容易跳过“测试必须失败”这一步直接写实现因为它觉得“反正最后能跑就行”。但TDD的核心价值恰恰在于那个失败的红灯阶段。2.2 技能加载的三种模式与选型考量在实际使用中agent-skills的加载方式主要有三种我分别说说各自的适用场景和坑。第一种是全局加载。把skill文件放在用户目录下的固定位置比如~/.claude/skills/Claude Code启动时自动扫描并加载。这种方式适合那些“任何时候都可能用到”的基础技能比如“如何安全执行终端命令”“如何读取和修改文件”。优点是省心不用每次手动指定缺点是如果技能太多启动时会有一点点延迟而且所有项目共享同一套技能难以做项目级定制。第二种是项目级加载。在项目根目录放一个.claude/skills/文件夹Claude Code在该项目下工作时优先加载这里的技能。这种方式适合团队协作场景项目A需要严格的TDD流程项目B可能更偏向快速原型各自维护自己的skill集合。我目前大部分项目都用这种方式因为不同项目的技术栈和规范差异很大全局技能反而容易造成干扰。第三种是显式调用。通过skills CLI在对话中临时加载某个技能比如/skill load test-driven-development。这种方式适合探索性场景你平时不用TDD但今天想试试就临时加载一下。缺点是每次都要手动操作容易忘。我的经验是把常用技能做成项目级加载把实验性技能用显式调用两者结合最舒服。注意技能加载顺序会影响AI的行为。如果全局技能和项目级技能有冲突项目级通常优先级更高。但不同版本的Claude Code对优先级的处理可能略有差异建议在项目README里明确写清楚依赖哪些技能避免团队成员之间行为不一致。2.3 与Claude Code、skills CLI的协作关系这里要理清一个容易混淆的点agent-skills是规范skills CLI是工具Claude Code是运行环境。三者关系可以类比成agent-skills是菜谱skills CLI是厨房管理系统Claude Code是厨师。skills CLI负责技能的安装、更新、卸载、列表查看。比如你从某个仓库clone了一套skill用skills install ./my-skill把它注册到本地技能库用skills list查看当前有哪些技能可用用skills update拉取最新版本。这些操作不涉及AI本身纯粹是文件管理和依赖解析。Claude Code在启动时读取技能库根据当前对话上下文决定加载哪些技能。当你发出一个请求比如“帮我给这个函数写单测”Claude Code会检查已加载的技能中是否有匹配的如果有test-driven-development技能就按照技能定义的流程执行如果没有就按默认行为处理。我踩过的一个坑是以为安装了skill就万事大吉结果Claude Code根本没加载。后来发现是skill文件的元数据格式不对——skills CLI能识别但Claude Code解析时要求更严格的字段。所以每次写完skill我都会用skills validate检查一遍再用Claude Code实际跑一个任务验证。3. 核心细节解析与实操要点3.1 一个skill文件到底长什么样skill文件通常是一个Markdown文件带YAML front matter。我拿一个简化版的test-driven-development skill举例--- name: test-driven-development version: 1.2.0 description: 按照红-绿-重构循环编写代码 triggers: - 写测试 - TDD - 单元测试 tools: - terminal - file_editor --- ## 执行流程 1. 阅读需求列出所有需要测试的行为点 2. 为第一个行为点编写测试用例 3. 运行测试确认测试失败红灯 4. 编写最简实现使测试通过绿灯 5. 运行全部测试确认没有破坏其他功能 6. 重构代码保持测试通过 7. 重复步骤2-6直到所有行为点覆盖 ## 约束条件 - 禁止在测试失败前编写实现代码 - 每次只处理一个行为点 - 重构阶段不得改变外部行为 - 如果测试连续失败3次停下来向用户确认需求 ## 验证标准 - 每个行为点都有对应的测试用例 - 测试覆盖率不低于80% - 所有测试必须实际执行并通过这个文件里front matter定义了技能的元信息名称、版本、描述、触发词、需要的工具权限。正文部分定义了执行流程、约束条件和验证标准。触发词的设计很关键。如果触发词太宽泛比如只写“测试”那用户说“帮我看看这个测试为什么失败”也会触发TDD流程但用户其实只是想调试不想走完整TDD。如果触发词太窄又可能该触发的时候没触发。我的经验是触发词要覆盖用户可能表达的同义说法同时用约束条件里的“如果...则...”来排除误触发场景。3.2 skills CLI的常用命令与参数解析skills CLI的命令不多但每个都有一些值得注意的参数。我整理了一个速查表命令作用常用参数注意事项skills init初始化技能库--dir ./skills默认在当前目录创建skills文件夹skills install path安装技能--force覆盖已存在安装前会校验元数据格式skills list列出已安装技能--verbose显示详情只显示当前项目可见的技能skills update更新技能--all更新全部会检查版本兼容性skills validate path校验技能文件--strict严格模式建议每次修改后都跑一遍skills remove name卸载技能--keep-config保留配置不会删除技能文件本身我重点说两个容易出问题的命令。skills install在安装时会做依赖解析。如果skill A依赖skill B而B没安装install会报错并提示你先装B。这个设计是合理的但有时候你从网上clone了一个skill集合里面互相依赖一个个装很麻烦。我的做法是写一个skills.json清单文件把所有依赖列进去然后skills install --from skills.json一次性搞定。skills validate的严格模式会检查一些容易被忽略的细节比如front matter里triggers字段是否为空、tools字段是否包含未定义的权限、正文中是否有未闭合的代码块。我建议把validate加到CI流程里每次提交skill修改都自动跑一遍避免把格式错误的skill推到共享库。3.3 技能与模型路由的配合方式热词里有个问题很典型“claude code harness可以不登录用其他模型吗”。这涉及到技能加载和模型选择的关系。Claude Code本身是一个harness运行框架它负责加载技能、管理对话、调用模型。模型可以是Claude系列也可以配置成其他兼容接口的模型。技能定义里不绑定具体模型它只描述“做什么”和“怎么做”至于“用哪个模型做”是harness层面的配置。这意味着你可以用同一套agent-skills今天跑在Claude上明天切换到其他模型上。但要注意不同模型对技能指令的遵循程度不同。我实测下来技能里越具体的步骤描述模型之间的表现差异越小越依赖“常识推理”的部分差异越大。所以写skill时我尽量把关键步骤写成明确的、可验证的指令减少对模型自由发挥的依赖。另外技能里的tools字段定义了该技能需要哪些工具权限。如果harness配置的模型不支持某个工具比如某些模型不支持函数调用加载该技能时会报错。这时候要么换模型要么修改技能去掉对那个工具的依赖。提示在团队里共享skill时建议在README里注明“本技能已在哪些模型上验证通过”。我遇到过同一个skill在A模型上表现完美在B模型上完全跑偏的情况提前标注能省很多沟通成本。4. 实操过程与核心环节实现4.1 从零搭建一个项目级技能库假设你有一个新项目想为它配置一套agent-skills。下面是完整流程。第一步初始化技能目录。在项目根目录执行skills init --dir .claude/skills这会在.claude/skills/下创建一个空的技能库并生成一个skills.json清单文件。我习惯把技能库放在.claude/skills/而不是项目根目录的skills/因为这样Claude Code能自动发现不需要额外配置路径。第二步编写第一个技能。我建议从最简单的开始比如“代码格式化”技能。创建文件.claude/skills/format-code.md--- name: format-code version: 1.0.0 description: 对指定文件执行代码格式化 triggers: - 格式化 - format - 整理代码 tools: - terminal - file_editor --- ## 执行流程 1. 确认目标文件路径 2. 检查项目根目录是否有格式化配置文件.prettierrc、.eslintrc等 3. 如果有配置文件使用项目配置执行格式化 4. 如果没有配置文件使用默认配置并提示用户 5. 格式化后运行一次lint检查确认没有引入新错误 ## 约束条件 - 不得修改格式化配置文件 - 如果格式化导致lint错误增加回滚并报告 - 每次只格式化用户指定的文件不批量处理 ## 验证标准 - 目标文件格式化成功 - lint错误数量不增加 - 用户确认修改内容第三步校验并安装。执行skills validate .claude/skills/format-code.md --strict skills install .claude/skills/format-code.md第四步在Claude Code中验证。启动Claude Code输入“帮我格式化src/utils.js”观察它是否按照技能定义的流程执行。如果它跳过了lint检查步骤说明技能约束条件写得不够强需要调整措辞。4.2 用TDD技能完成一个真实功能开发我拿一个实际例子来演示给一个JavaScript工具函数库添加“计算两个日期之间工作日天数”的功能。准备阶段。确保test-driven-development技能已加载。在Claude Code中输入“用TDD方式实现calculateWorkdays函数计算两个日期之间的工作日天数排除周末。”红灯阶段。Claude Code根据技能流程先写测试// test/calculateWorkdays.test.js const { calculateWorkdays } require(../src/calculateWorkdays); describe(calculateWorkdays, () { test(同一日期返回0, () { expect(calculateWorkdays(2024-01-01, 2024-01-01)).toBe(0); }); test(周一到周五返回5, () { expect(calculateWorkdays(2024-01-01, 2024-01-05)).toBe(5); }); test(跨周末正确排除, () { expect(calculateWorkdays(2024-01-05, 2024-01-08)).toBe(1); }); });然后运行测试确认失败。这一步很关键——如果测试直接通过了说明要么测试写错了要么函数已经存在。Claude Code会报告失败信息确认是“函数未定义”而不是其他错误。绿灯阶段。编写最简实现// src/calculateWorkdays.js function calculateWorkdays(start, end) { const startDate new Date(start); const endDate new Date(end); let count 0; const current new Date(startDate); while (current endDate) { const day current.getDay(); if (day ! 0 day ! 6) { count; } current.setDate(current.getDate() 1); } return count; } module.exports { calculateWorkdays };运行测试确认全部通过。重构阶段。检查代码是否有优化空间。比如可以用更函数式的方式重写或者处理时区问题。但重构的前提是测试保持通过。Claude Code会先跑一遍测试确认绿灯然后提出重构方案执行后再跑一遍测试。边界情况补充。技能流程要求覆盖所有行为点。我让Claude Code继续补充跨月、跨年、起始日期是周末、结束日期是周末等情况。每补充一个测试就走一遍红-绿-重构循环。整个过程中我只需要在关键节点确认比如“测试失败信息是否正确”“重构方案是否合理”。其余步骤Claude Code按技能定义自动执行。实测下来一个中等复杂度的函数从零到测试覆盖完整大约15-20分钟比我自己写快不少而且测试覆盖更全面。4.3 技能组合与流水线编排单个技能解决单点问题但实际开发往往是多技能串联。比如“添加一个新API端点”这个任务可能涉及读取现有路由结构、编写处理函数、写单测、更新API文档、运行集成测试。我的做法是定义一个“复合技能”它不直接执行具体操作而是编排其他技能的调用顺序--- name: add-api-endpoint version: 1.0.0 description: 添加一个新的API端点包含实现、测试和文档 triggers: - 添加API - 新增端点 - add endpoint tools: - terminal - file_editor depends_on: - test-driven-development - update-api-docs - run-integration-tests --- ## 执行流程 1. 调用test-driven-development技能实现端点逻辑和单元测试 2. 调用update-api-docs技能更新API文档 3. 调用run-integration-tests技能运行集成测试 4. 如果集成测试失败回到步骤1修复 5. 所有测试通过后输出变更摘要 ## 约束条件 - 任一步骤失败不得跳过继续 - 集成测试必须实际运行不得只做静态检查 - 变更摘要需包含新增文件列表和测试结果这种复合技能的好处是把跨领域的流程固化下来避免AI在步骤之间“偷懒”。我试过不写复合技能直接让Claude Code“添加一个API端点”它经常写完实现就停了忘了更新文档和跑集成测试。有了复合技能后每一步都有明确的调用和验证遗漏率大幅降低。注意复合技能的依赖关系要显式声明在depends_on字段里。skills CLI在安装时会检查依赖是否满足Claude Code在加载时会按依赖顺序初始化。如果依赖的技能没安装复合技能会加载失败并给出明确提示。5. 常见问题与排查技巧实录5.1 技能不生效的排查思路这是最高频的问题。我整理了一个排查清单按顺序检查排查项检查方法常见原因技能是否安装skills list忘记执行install技能是否加载Claude Code启动日志路径不对或权限问题触发词是否匹配手动输入触发词测试用户表达与触发词差异大元数据是否合法skills validate --strictfront matter格式错误工具权限是否足够检查harness配置模型不支持所需工具技能间是否冲突逐个禁用测试多个技能触发条件重叠我遇到最多的是触发词不匹配。比如技能里写的是“写测试”用户说的是“帮我补个测试用例”虽然语义相近但字面不匹配技能没触发。解决办法是在触发词里加入更多同义表达或者用更宽泛的匹配规则。但宽泛匹配又容易误触发需要权衡。另一个坑是技能文件编码问题。我有一次从Windows复制了一个skill文件到Linux环境文件带了BOM头skills CLI能识别但Claude Code解析失败。后来统一用UTF-8无BOM格式保存问题消失。5.2 技能执行中途卡住的处理有时候Claude Code执行到一半停住了既不报错也不继续。常见原因和应对原因一等待用户确认但提示不明显。技能流程里如果有“向用户确认”的步骤Claude Code会暂停等待输入。但有时候提示信息被淹没在输出里用户没注意到。我的做法是在技能里明确要求“用醒目的格式输出确认请求”比如用引用块包裹。原因二工具调用失败但未正确处理。比如执行终端命令返回非零退出码技能里如果没有定义错误处理逻辑Claude Code可能就停在那里。解决办法是在技能约束条件里加上“如果命令返回非零退出码输出错误信息并询问用户是否继续”。原因三上下文超限。长流程任务中对话历史越来越长可能触及模型上下文窗口上限。这时候Claude Code会截断历史或报错。我的应对策略是把长流程拆成多个短技能每个技能完成后输出一个摘要下一个技能基于摘要继续而不是依赖完整历史。5.3 多模型切换时的技能适配前面提到技能不绑定模型但实际切换模型时还是有一些适配工作。第一检查工具支持。不同模型对函数调用的支持程度不同。如果技能依赖terminal工具但目标模型不支持就需要降级处理——比如让模型输出命令文本由用户手动执行。第二调整指令详细程度。能力强的模型可以接受更抽象的指令能力弱的模型需要更具体的步骤。我维护了两套技能版本一套“详细版”用于能力较弱的模型一套“精简版”用于能力强的模型。通过skills CLI的--variant参数切换。第三验证输出格式。有些模型对Markdown格式的遵循不够严格可能把代码块写成普通文本。如果技能后续步骤依赖解析代码块就会失败。我的做法是在技能里加入格式校验步骤如果输出格式不符合预期要求模型重新输出。提示切换模型后建议先用一个简单任务跑一遍完整技能流程确认没有兼容性问题再用于正式开发。我一般会准备一个“技能冒烟测试”脚本包含3-5个典型任务切换模型后自动跑一遍。5.4 技能版本管理与团队协作团队共享技能库时版本管理很重要。我踩过的坑包括有人改了技能但没更新版本号导致其他人拉取后行为不一致有人删除了某个技能但其他人的复合技能还依赖它加载时报错。现在的做法是每个技能文件必须包含version字段遵循语义化版本规范。修改技能时根据改动性质递增版本号修复bug递增patch新增功能递增minor破坏性变更递增major。复合技能的depends_on里指定版本范围比如test-driven-development^1.0.0skills CLI在安装时检查兼容性。另外技能库本身用Git管理每次修改走PR流程。CI里跑skills validate --strict和冒烟测试通过后才合并。这样虽然麻烦一点但避免了“在我机器上能跑”的问题。6. 我个人的一些实操体会写了这么多最后分享几个我在实际使用中总结的小经验不一定对所有人适用但至少帮我省了不少时间。第一个是关于技能粒度的。刚开始我总想把技能写得很全一个技能覆盖一大类任务。后来发现技能越聚焦AI执行越稳定。现在我的原则是一个技能只解决一个明确的问题步骤不超过7步。超过7步就拆成复合技能。第二个是关于触发词的。我习惯在技能里加一个“反触发词”列表明确列出哪些情况不该触发这个技能。比如test-driven-development技能的反触发词包括“调试测试”“查看测试结果”“解释测试失败原因”。这样能减少误触发。第三个是关于验证的。技能里的验证标准一定要可执行、可观测。不要写“代码质量良好”这种模糊标准要写“lint检查零错误”“测试覆盖率不低于80%”“所有测试实际执行并通过”。模糊标准等于没有标准。第四个是关于更新的。技能不是写完就完了随着项目演进和模型升级技能也需要迭代。我每个月会花半小时回顾一下常用技能看看有没有可以优化的地方。有时候只是调整一下步骤顺序执行效率就能提升不少。这套agent-skills的玩法核心思想就是把“让AI干活”这件事从“碰运气”变成“可工程化”。你不需要一开始就搭得很完善从一个最简单的技能开始跑通了再逐步扩展。我最初就是从“格式化代码”这一个技能起步的现在团队里已经有二十多个技能在用了。