1. 从“agent-skills”说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我的直觉是这大概率不是一个“工具”而是一套给 AI coding agent 用的能力包。后来翻了一圈资料基本印证了这个判断——它本质上是一个围绕skills CLI构建的、面向Claude Code这类 AI coding agents 的技能集合与调度层。你可以把它理解成给 AI 编程助手装上一套“可插拔的手艺”让它不只是会补全代码而是能按既定流程去写测试、跑测试、改代码、再验证也就是热词里反复出现的test-driven-development。我为什么会对这个东西感兴趣因为过去大半年我一直在折腾claude code相关的落地从claude code 安装、vscode 配置 claude code、ubuntu 配置 claude code到claude code 使用过程中怎么让它稳定执行终端命令、怎么接第三方模型、怎么在团队里推广。踩过的坑不少最大的感受是模型能力本身不是瓶颈真正卡人的是“怎么把模型的能力组织成可复用的工作流”。agent-skills恰好切在这个点上。它解决的问题很具体你有一个 AI coding agent比如 Claude Code你希望它在特定任务上表现得像一个有经验的工程师而不是一个只会聊天的助手。那你就需要给它“技能”——比如 TDD 技能、代码审查技能、重构技能、调试技能。agent-skills提供的就是这样一套技能定义和加载机制配合skills CLI你可以按需启用、组合、扩展。适合谁看三类人一是已经在用claude code或类似 AI coding agent 的开发者想把自己的工作流沉淀下来二是团队里负责 AI 工具链建设的人想找一套可复制的技能管理方案三是对AI coding agents感兴趣、想了解“技能”这层抽象怎么设计的人。哪怕你还没装claude code看完这篇也能明白这套东西的设计思路迁移到别的 agent 上。下面我按自己的理解把agent-skills拆成几个层面来讲整体设计思路、核心细节与实操要点、完整落地过程、常见问题排查。中间会穿插我在claude code 安装、vscode 接入 claude code、ubuntu 安装 claude code这些环节的实际经验尽量让不同基础的读者都能抄作业。2. 整体设计与思路拆解为什么是“技能”而不是“插件”2.1 核心抽象把工作流从模型里抽出来传统做法是你把需求丢给 AI coding agent靠提示词让它按你的意图干活。问题是提示词是易耗品今天写得好明天换个任务就失效而且提示词散落在各个对话里没法版本化、没法复用、没法团队共享。agent-skills的思路是把“怎么做一件事”从提示词里抽出来变成一个独立的、可命名的技能单元。一个技能通常包含技能名、触发条件、执行步骤、依赖的工具或命令、验证标准。比如一个 TDD 技能它会规定先写失败测试、再写最小实现、再跑测试、再重构。这套流程不依赖某一次对话的上下文而是作为技能定义存在。这样做的好处很明显。第一可复用同一个 TDD 技能可以用在任何需要 TDD 的任务上。第二可组合你可以把“写测试”和“跑测试”拆成两个技能按需组合。第三可验证技能有明确的验证标准agent 执行完能自检而不是靠你肉眼判断。第四可迭代技能定义是文件可以进版本控制可以 code review。我自己的体会是这层抽象一旦建立起来AI coding agent 的使用方式就从“聊天”变成了“调用能力”。这跟claude code本身的设计哲学是一致的——它强调在终端里直接执行命令、直接改文件而不是只给建议。agent-skills相当于给这种执行能力加了一层“操作规程”。2.2 为什么选 skills CLI 作为入口热词里有skills CLI这不是偶然。CLI 作为入口有几个天然优势一是跟claude code的使用场景契合它本身就是终端工具用户在终端里操作CLI 是最自然的交互方式二是 CLI 容易脚本化可以嵌到 CI、嵌到 git hook、嵌到自动化流程里三是 CLI 的权限边界清晰能执行什么、不能执行什么容易审计。相比之下如果做成 GUI 或者 IDE 插件虽然上手门槛低但灵活性和可组合性会打折扣。agent-skills选择 CLI说明它面向的是愿意折腾、愿意把工作流沉淀下来的用户而不是只想点按钮的用户。这也解释了为什么热词里claude code for vs code、vscode 接入 claude code的搜索量很高——大家还是希望在 IDE 里有入口但底层能力还是靠 CLI 承载。2.3 与 Claude Code 的关系不是替代是增强需要说清楚一点agent-skills不是claude code的替代品也不是必须依赖claude code才能用。它更像是一个技能层理论上可以对接不同的 AI coding agent。但因为它跟claude code的配合最紧密所以热词里两者经常一起出现。claude code提供的是基础能力读写文件、执行终端命令、跟模型对话。agent-skills提供的是上层能力在什么场景下、按什么顺序、用什么标准去调用这些基础能力。打个比方claude code是发动机和方向盘agent-skills是驾驶手册和路线图。没有驾驶手册你也能开但有了手册新手也能开得像个老司机。2.4 方案选型的取舍为什么不做成一个大而全的框架我见过不少类似项目一上来就想做“AI 编程全流程框架”结果复杂度爆炸用户装完就劝退。agent-skills相对克制它聚焦在“技能”这一个概念上把技能的定义、加载、执行、验证做扎实其他事情交给claude code本身或者用户自己。这种克制是有道理的。AI coding agent 这个领域变化太快今天流行的模型明天可能就换了今天好用的提示词明天可能就失效了。如果框架绑定了太多具体实现很容易过时。而“技能”这层抽象相对稳定——不管底层模型怎么换TDD 的流程还是那几步代码审查的要点还是那些。把稳定的部分抽出来把易变的部分留给底层这是比较聪明的做法。提示如果你在评估要不要引入agent-skills先问自己一个问题我有没有至少一个反复出现、步骤相对固定的开发任务如果有它就值得试如果全是探索性、一次性的任务可能直接用claude code更省事。3. 核心细节解析与实操要点技能到底长什么样3.1 技能定义的几个关键字段虽然agent-skills的具体实现可能随版本变化但根据我对这类项目的理解一个技能定义通常包含以下字段。我按自己的经验整理成表格方便对照字段作用实操建议技能名唯一标识用于调用用动词开头如write-failing-test描述说明技能做什么一句话说清避免模糊触发条件什么时候用这个技能写具体如“当任务涉及新增函数时”执行步骤具体做什么分步写每步可验证依赖工具需要哪些命令或工具如pytest、git、npm验证标准怎么算执行成功如“测试从红变绿”回滚策略失败怎么办如“git checkout 恢复”这些字段看起来简单但真正写起来最容易出问题的是“触发条件”和“验证标准”。触发条件写得太宽技能会被滥用写得太窄又用不上。验证标准写得太松agent 会自欺欺人写得太严又容易卡住。我的经验是触发条件用“任务类型 文件类型”双重限定验证标准用可执行的命令输出作为依据。3.2 TDD 技能拆解一个具体例子热词里有test-driven-development我就拿 TDD 技能举例。一个完整的 TDD 技能我通常会拆成四个子技能写失败测试根据需求在测试文件里新增一个测试用例运行它确认它失败。这一步的关键是“确认失败”——很多人跳过这步结果测试写了个永远通过的等于没写。写最小实现只写让测试通过的最少代码不提前优化不提前抽象。这一步的关键是“最小”抵抗住“顺便把别的也改了”的冲动。跑测试确认通过运行测试确认从红变绿。如果没变绿回到第二步。重构在测试保护下优化代码结构。重构后必须再跑一次测试确认还是绿的。这四个子技能可以串成一个主技能tdd-cycle也可以单独调用。我在实际用claude code的时候会先让它加载tdd-cycle然后给它一个具体任务它就会按这个流程走。实测下来比直接说“你帮我写个函数”要靠谱得多因为流程约束了它的行为。注意TDD 技能对 agent 的“自律性”要求很高。如果底层模型倾向于“一步到位”它可能会跳过写失败测试这步。这时候需要在技能定义里加硬性检查比如“运行测试命令后必须看到失败输出才能进入下一步”。3.3 技能加载与调用的机制agent-skills通过skills CLI来加载技能。我理解的大致流程是CLI 读取技能定义文件解析成 agent 能理解的格式然后注入到claude code的上下文里。调用的时候你可以显式指定技能名也可以让 agent 根据触发条件自动匹配。显式调用适合你知道自己要干什么的场景比如“用 TDD 技能写这个模块”。自动匹配适合探索性场景比如“帮我看看这段代码有什么问题”agent 根据触发条件决定用代码审查技能还是调试技能。这里有个实操要点技能不要加载太多。我试过一次加载十几个技能结果 agent 的上下文被占满反而变笨了。后来我改成按任务加载一次最多三到五个相关技能效果好很多。这跟人一样同时想着十几件事哪件都做不好。3.4 与第三方模型的配合热词里有使用 cc switch 接入 deepseek v4, qwen, glm 等模型这说明很多人不满足于只用官方模型想接第三方。agent-skills作为技能层理论上跟底层模型解耦所以可以配合第三方模型使用。但这里有几个坑要注意。第一不同模型对技能定义的理解能力不一样。有些模型对结构化指令遵循得好有些则容易跑偏。第二第三方模型的工具调用能力参差不齐如果技能依赖终端命令执行模型得能正确生成命令。第三上下文窗口大小不同技能定义太长可能被截断。我的建议是如果要用第三方模型先从简单技能开始试确认模型能稳定遵循技能定义再逐步加复杂度。不要一上来就上 TDD 这种多步骤技能容易翻车。3.5 技能版本管理与团队协作技能定义是文件这就意味着可以进 git。我在团队里推的时候会把技能定义放在一个独立仓库里按目录分类testing/、review/、refactor/、debug/。每个技能一个文件文件名就是技能名。这样 review 的时候一目了然改了什么、为什么改都有记录。团队协作还有个好处技能可以沉淀团队的最佳实践。比如我们团队对代码审查有特定要求就写成一个审查技能新人用claude code的时候加载这个技能出来的审查意见就符合团队标准。这比写文档有效因为文档没人看技能是 agent 直接执行的。4. 实操过程与核心环节实现从零到跑通4.1 环境准备先把 Claude Code 装明白在聊agent-skills之前得先把claude code装好。热词里claude code 安装、claude code 下载、mac 安装 claude code、ubuntu 安装 claude code的搜索量都很高说明这一步卡了不少人。我按自己的经验梳理一下。claude code本质是一个终端工具安装方式通常是通过包管理器或者官方脚本。在 macOS 上我一般用 Homebrew 或者官方提供的安装命令在 Ubuntu 上用 npm 全局安装或者下载二进制。具体命令以官方文档为准因为版本更新快我这里不写死命令避免误导。安装完之后第一件事是验证在终端里输入claude或者对应的命令看能不能启动。如果提示找不到命令大概率是 PATH 没配好。Ubuntu 上常见的问题是 npm 全局 bin 目录不在 PATH 里需要手动加。提示热词里有一条 “note: claude code might not be available in your country. check supported co”这说明可用性可能因地区而异。如果你遇到安装或登录问题先确认自己所在地区是否在支持范围内这是第一步排查。4.2 配置 VS Code 接入vscode 配置 claude code、claude code for vs code、vscode 接入 claude code这些热词说明很多人希望在 IDE 里用。我的做法是终端里用claude code做主要操作VS Code 里装对应插件做辅助。插件的作用主要是提供入口和展示真正的执行还是在终端。配置的时候注意几点一是确保 VS Code 的终端能调用到claude code命令这跟系统 PATH 有关二是如果插件需要指定可执行文件路径填绝对路径更稳三是插件版本和claude code版本要匹配不然可能出现兼容问题。我踩过的一个坑是在 VS Code 里用集成终端跑claude code结果因为终端环境变量跟系统终端不一样导致找不到某些命令。解决办法是在 VS Code 设置里把终端环境继承改成系统环境或者直接在外部终端跑。4.3 安装与初始化 agent-skills假设claude code已经跑通接下来是agent-skills。通过skills CLI安装通常是一个包管理器命令。安装完之后一般需要初始化生成技能目录和配置文件。初始化的时候CLI 可能会问你技能目录放哪、要不要生成示例技能。我的建议是技能目录放在项目根目录下的.agent-skills/或者用户主目录下的~/.agent-skills/。放项目里适合团队共享放主目录适合个人全局使用。我一般两个都用通用技能放主目录项目特定技能放项目里。初始化完成后目录结构大概是这样.agent-skills/ skills/ tdd-cycle.md code-review.md debug.md config.yaml每个.md文件就是一个技能定义。config.yaml里配置技能加载路径、默认技能等。4.4 写第一个技能从“跑测试”开始不要一上来就写复杂的 TDD 技能。我建议从最简单的开始比如“跑测试并报告结果”。这个技能的定义大概是这样技能名run-tests描述运行项目测试套件并报告结果触发条件当用户要求验证代码正确性时执行步骤1. 识别项目使用的测试框架2. 运行对应测试命令3. 解析输出4. 报告通过/失败数量依赖工具项目测试框架对应的命令验证标准命令执行完成且输出被正确解析写完之后用skills CLI加载然后在claude code里调用。如果 agent 能正确识别测试框架、跑测试、报告结果说明技能定义没问题。这个过程中你可能会发现 agent 识别测试框架不准那就需要在技能定义里加更明确的判断逻辑比如“如果存在pytest.ini则用 pytest如果存在package.json且 scripts 里有 test 则用 npm test”。4.5 逐步叠加从单技能到技能链单技能跑通后开始叠加。比如把run-tests和write-failing-test组合成tdd-cycle。组合的方式有两种一种是在技能定义里直接引用其他技能一种是让 agent 根据流程自动调用。我倾向于第一种因为可控。在tdd-cycle的定义里明确写第一步调用write-failing-test第二步调用write-minimal-impl第三步调用run-tests第四步调用refactor。这样 agent 不会乱序执行。叠加过程中最容易出问题的是技能之间的数据传递。比如write-failing-test产出的测试文件路径要传给run-tests。如果技能定义里没写清楚agent 可能会重新猜路径导致跑错测试。解决办法是在技能定义里约定好输出格式比如“测试文件路径写入.agent-skills/tmp/last-test-file”下一个技能从这个文件读。4.6 参数计算与选择以测试超时为例技能执行过程中会涉及一些参数比如测试超时时间。设太短测试没跑完就超时设太长卡住了浪费时间。我的经验算法是先跑一次完整测试记录耗时然后超时时间设为耗时的 2 到 3 倍。如果是 CI 环境再乘 1.5 倍留余量。举个例子本地跑完整测试耗时 40 秒那超时设 120 秒比较合适。如果某个测试特别慢单独给它设更长的超时而不是全局调大。这个逻辑可以写进技能定义里让 agent 根据历史耗时动态调整。注意超时设置不要写死在技能定义里最好作为配置项不同环境用不同值。本地开发可以短一点CI 上长一点。4.7 实操现场记录一次完整的 TDD 技能执行我记录一次实际执行过程方便你对照。任务是给一个 Python 函数加参数校验。我在终端启动claude code加载tdd-cycle技能。我输入任务“给parse_config函数加参数校验空字符串要报错。”Agent 调用write-failing-test在test_config.py里新增测试用例运行pytest test_config.py::test_parse_config_empty确认失败。Agent 调用write-minimal-impl在parse_config里加了一行判断空字符串抛ValueError。Agent 调用run-tests跑pytest test_config.py确认通过。Agent 调用refactor把校验逻辑抽成独立函数再跑测试确认还是通过。Agent 报告完成附上改动摘要。整个过程大概两分钟比我手动写快而且流程规范不会漏掉写测试这步。当然前提是技能定义写得好agent 遵循得好。5. 常见问题与排查技巧实录5.1 技能不生效从加载到触发的排查链技能不生效是最常见的问题。排查顺序我一般是这样确认技能文件被加载用skills CLI的列表命令看技能在不在列表里。不在的话检查技能目录路径配置对不对。确认技能格式正确技能定义文件如果有语法错误CLI 可能静默跳过。检查 YAML front matter 或者 Markdown 结构是否符合要求。确认触发条件匹配如果技能是自动触发检查你的输入是否满足触发条件。可以临时改成显式调用看能不能跑。确认 agent 上下文里有技能有些实现是把技能注入到系统提示里如果上下文太长被截断技能可能没进去。减少同时加载的技能数量试试。我遇到过一次技能文件明明在目录里但 CLI 列表里没有。后来发现是文件扩展名不对应该是.md我写成了.markdown。这种低级错误排查起来最费时间所以第一步永远是确认文件本身没问题。5.2 Agent 不遵循技能步骤原因与对策技能加载了但 agent 不按步骤走比如跳过写失败测试直接写实现。原因可能有几个一是模型本身倾向于“一步到位”需要更强的约束二是技能定义里的步骤不够具体agent 有解释空间三是上下文里有其他指令跟技能冲突。对策在技能定义里加硬性检查点。比如“在运行测试并看到失败输出之前禁止修改实现文件”。这种否定式指令比肯定式指令更有效。另外可以把大步骤拆成更小的技能每个技能只做一件事减少 agent 的自由发挥空间。5.3 第三方模型接入后的兼容问题用cc switch接入deepseek v4、qwen、glm等模型后常见问题是技能执行不稳定。有的模型能理解技能定义有的则把技能定义当成普通文本忽略掉。排查方法是先用一个极简技能测试比如“打印当前目录”看模型能不能执行。如果能再逐步加复杂度。还有一个问题是工具调用格式不兼容。claude code期望的工具调用格式第三方模型可能生成得不一样。这时候需要在中间层做适配或者选择工具调用能力强的模型。我的经验是技能越依赖工具调用对模型的要求越高纯文本推理的技能兼容性好很多。5.4 常见问题速查表问题现象可能原因排查方法解决方向技能列表为空路径配置错误检查 config 里的技能目录改成绝对路径技能加载但不用触发条件不匹配改显式调用测试放宽或明确触发条件Agent 跳过步骤约束不够强看执行日志加硬性检查点测试跑错文件技能间数据传递丢失检查中间文件约定输出格式第三方模型不遵循模型能力不足换简单技能测试换模型或加适配层执行超时超时设置太短记录实际耗时按耗时倍数调整上下文被占满加载技能太多减少同时加载数按任务加载5.5 独家避坑技巧几个我从实践中总结的技巧常规文档里不会写第一技能定义里写“不要做什么”比“要做什么”更重要。Agent 很容易过度发挥明确禁止某些行为比如“不要修改测试文件以外的文件”能省很多事。第二给技能加一个“干跑”模式。第一次执行新技能时让 agent 只报告计划不实际执行你确认没问题再真跑。这能避免 agent 乱改代码。第三技能目录用 git 管理但加 .gitignore 排除临时文件。技能执行过程中产生的中间文件比如上次测试文件路径不要提交。第四定期清理不再用的技能。技能多了会互相干扰而且加载慢。我每个月 review 一次删掉三个月没用的。第五技能命名用英文描述用中文。英文名方便命令行调用中文描述方便团队理解。混用没问题关键是保持一致。5.6 关于注册与账号的说明热词里有claude code 注册账号和不注册有啥不同、claude code harness 可以不登录用其他模型吗。我的理解是注册账号通常能获得更完整的功能和更高的配额不注册可能有限制。至于用其他模型取决于具体实现有些配置下可以接第三方模型有些则绑定官方服务。这部分建议以官方文档为准因为政策可能变化。我个人的做法是如果只是试用可以先不注册跑通基本流程如果要长期用、要团队协作还是注册账号更稳妥。6. 技能设计的进阶思路从能用 to 好用6.1 技能粒度怎么把握技能太粗比如一个“开发功能”技能包打天下agent 执行起来容易失控技能太细比如“打开文件”“写一行代码”都做成技能调用起来又太琐碎。我的经验是一个技能对应一个可验证的产出。比如“写失败测试”的产出是一个失败的测试用例“跑测试”的产出是测试结果报告。产出明确粒度就合适。判断标准很简单如果这个技能执行完你能明确说“成了”或“没成”那粒度就对了。如果执行完你还要问“这算完成了吗”那说明粒度太粗或者验证标准不清。6.2 技能之间的依赖管理技能之间会有依赖比如tdd-cycle依赖run-tests。依赖管理有两种方式一种是显式声明在技能定义里写depends_on: [run-tests]一种是隐式约定靠 agent 自己判断。我倾向于显式声明因为可控。显式声明还有个好处加载tdd-cycle的时候CLI 可以自动把依赖的技能也加载进来不用手动一个个加。但要注意循环依赖A 依赖 BB 又依赖 A会导致加载死循环。写技能的时候画个依赖图避免成环。6.3 技能的可观测性技能执行过程中你希望知道它进行到哪一步、每步花了多久、有没有异常。这就需要可观测性。我的做法是让技能在关键步骤输出日志写到统一的地方比如.agent-skills/logs/。日志格式用结构化格式方便后续分析。有了日志你可以统计哪些技能用得多、哪些步骤容易失败、平均执行时间多少。这些数据反过来指导技能优化。比如某个技能经常在第三步失败那可能是第三步的定义有问题需要改。6.4 技能与 CI 的集成技能不光能在本地用还能集成到 CI 里。比如在 PR 流程里自动跑代码审查技能把结果作为评论发出来。这样每次 PR 都有一轮自动审查人工审查可以聚焦在更高层的问题上。集成的时候注意权限控制。CI 里跑技能agent 能改文件、能执行命令权限要给得恰到好处。我的做法是CI 里的技能只读不写只做分析和报告不改代码。要改代码的场景走人工确认流程。6.5 技能库的长期维护技能库跟代码库一样需要长期维护。我的维护节奏是每周看一次日志找出失败率高的技能每月做一次 review删掉没用的、合并重复的、更新过时的每季度做一次大版本整理重新组织目录结构。维护的时候有个原则技能定义要跟着实践走不要为了定义而定义。如果一个技能在实际中从来不用那它就没有存在价值删掉比留着好。技能库的价值在于精不在于多。7. 我个人的一些体会折腾agent-skills这段时间最大的感受是AI coding agent 的上限不取决于模型取决于你怎么组织它的工作流。同样的claude code有人用起来像个高级补全有人用起来像个靠谱的结对程序员差别就在技能这层。另一个体会是技能定义的过程其实是你梳理自己工作流的过程。写 TDD 技能的时候我被迫想清楚 TDD 到底分几步、每步的输入输出是什么、怎么验证。这个思考过程本身就有价值哪怕最后不用 agent你对流程的理解也更清晰了。最后分享一个小技巧如果你刚开始接触不要急着写复杂技能。先写一个“跑测试”技能跑通感受一下 agent 按技能执行是什么体验。然后再写第二个、第三个慢慢叠加。技能库是长出来的不是设计出来的。我见过太多人一上来就想设计完美技能体系结果卡在设计阶段一个都没跑起来。先跑起来再优化这是我踩过坑之后最想说的。 agent-skills 与 Claude Code：用技能包驱动 AI 编程工作流
1. 从“agent-skills”说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我的直觉是这大概率不是一个“工具”而是一套给 AI coding agent 用的能力包。后来翻了一圈资料基本印证了这个判断——它本质上是一个围绕skills CLI构建的、面向Claude Code这类 AI coding agents 的技能集合与调度层。你可以把它理解成给 AI 编程助手装上一套“可插拔的手艺”让它不只是会补全代码而是能按既定流程去写测试、跑测试、改代码、再验证也就是热词里反复出现的test-driven-development。我为什么会对这个东西感兴趣因为过去大半年我一直在折腾claude code相关的落地从claude code 安装、vscode 配置 claude code、ubuntu 配置 claude code到claude code 使用过程中怎么让它稳定执行终端命令、怎么接第三方模型、怎么在团队里推广。踩过的坑不少最大的感受是模型能力本身不是瓶颈真正卡人的是“怎么把模型的能力组织成可复用的工作流”。agent-skills恰好切在这个点上。它解决的问题很具体你有一个 AI coding agent比如 Claude Code你希望它在特定任务上表现得像一个有经验的工程师而不是一个只会聊天的助手。那你就需要给它“技能”——比如 TDD 技能、代码审查技能、重构技能、调试技能。agent-skills提供的就是这样一套技能定义和加载机制配合skills CLI你可以按需启用、组合、扩展。适合谁看三类人一是已经在用claude code或类似 AI coding agent 的开发者想把自己的工作流沉淀下来二是团队里负责 AI 工具链建设的人想找一套可复制的技能管理方案三是对AI coding agents感兴趣、想了解“技能”这层抽象怎么设计的人。哪怕你还没装claude code看完这篇也能明白这套东西的设计思路迁移到别的 agent 上。下面我按自己的理解把agent-skills拆成几个层面来讲整体设计思路、核心细节与实操要点、完整落地过程、常见问题排查。中间会穿插我在claude code 安装、vscode 接入 claude code、ubuntu 安装 claude code这些环节的实际经验尽量让不同基础的读者都能抄作业。2. 整体设计与思路拆解为什么是“技能”而不是“插件”2.1 核心抽象把工作流从模型里抽出来传统做法是你把需求丢给 AI coding agent靠提示词让它按你的意图干活。问题是提示词是易耗品今天写得好明天换个任务就失效而且提示词散落在各个对话里没法版本化、没法复用、没法团队共享。agent-skills的思路是把“怎么做一件事”从提示词里抽出来变成一个独立的、可命名的技能单元。一个技能通常包含技能名、触发条件、执行步骤、依赖的工具或命令、验证标准。比如一个 TDD 技能它会规定先写失败测试、再写最小实现、再跑测试、再重构。这套流程不依赖某一次对话的上下文而是作为技能定义存在。这样做的好处很明显。第一可复用同一个 TDD 技能可以用在任何需要 TDD 的任务上。第二可组合你可以把“写测试”和“跑测试”拆成两个技能按需组合。第三可验证技能有明确的验证标准agent 执行完能自检而不是靠你肉眼判断。第四可迭代技能定义是文件可以进版本控制可以 code review。我自己的体会是这层抽象一旦建立起来AI coding agent 的使用方式就从“聊天”变成了“调用能力”。这跟claude code本身的设计哲学是一致的——它强调在终端里直接执行命令、直接改文件而不是只给建议。agent-skills相当于给这种执行能力加了一层“操作规程”。2.2 为什么选 skills CLI 作为入口热词里有skills CLI这不是偶然。CLI 作为入口有几个天然优势一是跟claude code的使用场景契合它本身就是终端工具用户在终端里操作CLI 是最自然的交互方式二是 CLI 容易脚本化可以嵌到 CI、嵌到 git hook、嵌到自动化流程里三是 CLI 的权限边界清晰能执行什么、不能执行什么容易审计。相比之下如果做成 GUI 或者 IDE 插件虽然上手门槛低但灵活性和可组合性会打折扣。agent-skills选择 CLI说明它面向的是愿意折腾、愿意把工作流沉淀下来的用户而不是只想点按钮的用户。这也解释了为什么热词里claude code for vs code、vscode 接入 claude code的搜索量很高——大家还是希望在 IDE 里有入口但底层能力还是靠 CLI 承载。2.3 与 Claude Code 的关系不是替代是增强需要说清楚一点agent-skills不是claude code的替代品也不是必须依赖claude code才能用。它更像是一个技能层理论上可以对接不同的 AI coding agent。但因为它跟claude code的配合最紧密所以热词里两者经常一起出现。claude code提供的是基础能力读写文件、执行终端命令、跟模型对话。agent-skills提供的是上层能力在什么场景下、按什么顺序、用什么标准去调用这些基础能力。打个比方claude code是发动机和方向盘agent-skills是驾驶手册和路线图。没有驾驶手册你也能开但有了手册新手也能开得像个老司机。2.4 方案选型的取舍为什么不做成一个大而全的框架我见过不少类似项目一上来就想做“AI 编程全流程框架”结果复杂度爆炸用户装完就劝退。agent-skills相对克制它聚焦在“技能”这一个概念上把技能的定义、加载、执行、验证做扎实其他事情交给claude code本身或者用户自己。这种克制是有道理的。AI coding agent 这个领域变化太快今天流行的模型明天可能就换了今天好用的提示词明天可能就失效了。如果框架绑定了太多具体实现很容易过时。而“技能”这层抽象相对稳定——不管底层模型怎么换TDD 的流程还是那几步代码审查的要点还是那些。把稳定的部分抽出来把易变的部分留给底层这是比较聪明的做法。提示如果你在评估要不要引入agent-skills先问自己一个问题我有没有至少一个反复出现、步骤相对固定的开发任务如果有它就值得试如果全是探索性、一次性的任务可能直接用claude code更省事。3. 核心细节解析与实操要点技能到底长什么样3.1 技能定义的几个关键字段虽然agent-skills的具体实现可能随版本变化但根据我对这类项目的理解一个技能定义通常包含以下字段。我按自己的经验整理成表格方便对照字段作用实操建议技能名唯一标识用于调用用动词开头如write-failing-test描述说明技能做什么一句话说清避免模糊触发条件什么时候用这个技能写具体如“当任务涉及新增函数时”执行步骤具体做什么分步写每步可验证依赖工具需要哪些命令或工具如pytest、git、npm验证标准怎么算执行成功如“测试从红变绿”回滚策略失败怎么办如“git checkout 恢复”这些字段看起来简单但真正写起来最容易出问题的是“触发条件”和“验证标准”。触发条件写得太宽技能会被滥用写得太窄又用不上。验证标准写得太松agent 会自欺欺人写得太严又容易卡住。我的经验是触发条件用“任务类型 文件类型”双重限定验证标准用可执行的命令输出作为依据。3.2 TDD 技能拆解一个具体例子热词里有test-driven-development我就拿 TDD 技能举例。一个完整的 TDD 技能我通常会拆成四个子技能写失败测试根据需求在测试文件里新增一个测试用例运行它确认它失败。这一步的关键是“确认失败”——很多人跳过这步结果测试写了个永远通过的等于没写。写最小实现只写让测试通过的最少代码不提前优化不提前抽象。这一步的关键是“最小”抵抗住“顺便把别的也改了”的冲动。跑测试确认通过运行测试确认从红变绿。如果没变绿回到第二步。重构在测试保护下优化代码结构。重构后必须再跑一次测试确认还是绿的。这四个子技能可以串成一个主技能tdd-cycle也可以单独调用。我在实际用claude code的时候会先让它加载tdd-cycle然后给它一个具体任务它就会按这个流程走。实测下来比直接说“你帮我写个函数”要靠谱得多因为流程约束了它的行为。注意TDD 技能对 agent 的“自律性”要求很高。如果底层模型倾向于“一步到位”它可能会跳过写失败测试这步。这时候需要在技能定义里加硬性检查比如“运行测试命令后必须看到失败输出才能进入下一步”。3.3 技能加载与调用的机制agent-skills通过skills CLI来加载技能。我理解的大致流程是CLI 读取技能定义文件解析成 agent 能理解的格式然后注入到claude code的上下文里。调用的时候你可以显式指定技能名也可以让 agent 根据触发条件自动匹配。显式调用适合你知道自己要干什么的场景比如“用 TDD 技能写这个模块”。自动匹配适合探索性场景比如“帮我看看这段代码有什么问题”agent 根据触发条件决定用代码审查技能还是调试技能。这里有个实操要点技能不要加载太多。我试过一次加载十几个技能结果 agent 的上下文被占满反而变笨了。后来我改成按任务加载一次最多三到五个相关技能效果好很多。这跟人一样同时想着十几件事哪件都做不好。3.4 与第三方模型的配合热词里有使用 cc switch 接入 deepseek v4, qwen, glm 等模型这说明很多人不满足于只用官方模型想接第三方。agent-skills作为技能层理论上跟底层模型解耦所以可以配合第三方模型使用。但这里有几个坑要注意。第一不同模型对技能定义的理解能力不一样。有些模型对结构化指令遵循得好有些则容易跑偏。第二第三方模型的工具调用能力参差不齐如果技能依赖终端命令执行模型得能正确生成命令。第三上下文窗口大小不同技能定义太长可能被截断。我的建议是如果要用第三方模型先从简单技能开始试确认模型能稳定遵循技能定义再逐步加复杂度。不要一上来就上 TDD 这种多步骤技能容易翻车。3.5 技能版本管理与团队协作技能定义是文件这就意味着可以进 git。我在团队里推的时候会把技能定义放在一个独立仓库里按目录分类testing/、review/、refactor/、debug/。每个技能一个文件文件名就是技能名。这样 review 的时候一目了然改了什么、为什么改都有记录。团队协作还有个好处技能可以沉淀团队的最佳实践。比如我们团队对代码审查有特定要求就写成一个审查技能新人用claude code的时候加载这个技能出来的审查意见就符合团队标准。这比写文档有效因为文档没人看技能是 agent 直接执行的。4. 实操过程与核心环节实现从零到跑通4.1 环境准备先把 Claude Code 装明白在聊agent-skills之前得先把claude code装好。热词里claude code 安装、claude code 下载、mac 安装 claude code、ubuntu 安装 claude code的搜索量都很高说明这一步卡了不少人。我按自己的经验梳理一下。claude code本质是一个终端工具安装方式通常是通过包管理器或者官方脚本。在 macOS 上我一般用 Homebrew 或者官方提供的安装命令在 Ubuntu 上用 npm 全局安装或者下载二进制。具体命令以官方文档为准因为版本更新快我这里不写死命令避免误导。安装完之后第一件事是验证在终端里输入claude或者对应的命令看能不能启动。如果提示找不到命令大概率是 PATH 没配好。Ubuntu 上常见的问题是 npm 全局 bin 目录不在 PATH 里需要手动加。提示热词里有一条 “note: claude code might not be available in your country. check supported co”这说明可用性可能因地区而异。如果你遇到安装或登录问题先确认自己所在地区是否在支持范围内这是第一步排查。4.2 配置 VS Code 接入vscode 配置 claude code、claude code for vs code、vscode 接入 claude code这些热词说明很多人希望在 IDE 里用。我的做法是终端里用claude code做主要操作VS Code 里装对应插件做辅助。插件的作用主要是提供入口和展示真正的执行还是在终端。配置的时候注意几点一是确保 VS Code 的终端能调用到claude code命令这跟系统 PATH 有关二是如果插件需要指定可执行文件路径填绝对路径更稳三是插件版本和claude code版本要匹配不然可能出现兼容问题。我踩过的一个坑是在 VS Code 里用集成终端跑claude code结果因为终端环境变量跟系统终端不一样导致找不到某些命令。解决办法是在 VS Code 设置里把终端环境继承改成系统环境或者直接在外部终端跑。4.3 安装与初始化 agent-skills假设claude code已经跑通接下来是agent-skills。通过skills CLI安装通常是一个包管理器命令。安装完之后一般需要初始化生成技能目录和配置文件。初始化的时候CLI 可能会问你技能目录放哪、要不要生成示例技能。我的建议是技能目录放在项目根目录下的.agent-skills/或者用户主目录下的~/.agent-skills/。放项目里适合团队共享放主目录适合个人全局使用。我一般两个都用通用技能放主目录项目特定技能放项目里。初始化完成后目录结构大概是这样.agent-skills/ skills/ tdd-cycle.md code-review.md debug.md config.yaml每个.md文件就是一个技能定义。config.yaml里配置技能加载路径、默认技能等。4.4 写第一个技能从“跑测试”开始不要一上来就写复杂的 TDD 技能。我建议从最简单的开始比如“跑测试并报告结果”。这个技能的定义大概是这样技能名run-tests描述运行项目测试套件并报告结果触发条件当用户要求验证代码正确性时执行步骤1. 识别项目使用的测试框架2. 运行对应测试命令3. 解析输出4. 报告通过/失败数量依赖工具项目测试框架对应的命令验证标准命令执行完成且输出被正确解析写完之后用skills CLI加载然后在claude code里调用。如果 agent 能正确识别测试框架、跑测试、报告结果说明技能定义没问题。这个过程中你可能会发现 agent 识别测试框架不准那就需要在技能定义里加更明确的判断逻辑比如“如果存在pytest.ini则用 pytest如果存在package.json且 scripts 里有 test 则用 npm test”。4.5 逐步叠加从单技能到技能链单技能跑通后开始叠加。比如把run-tests和write-failing-test组合成tdd-cycle。组合的方式有两种一种是在技能定义里直接引用其他技能一种是让 agent 根据流程自动调用。我倾向于第一种因为可控。在tdd-cycle的定义里明确写第一步调用write-failing-test第二步调用write-minimal-impl第三步调用run-tests第四步调用refactor。这样 agent 不会乱序执行。叠加过程中最容易出问题的是技能之间的数据传递。比如write-failing-test产出的测试文件路径要传给run-tests。如果技能定义里没写清楚agent 可能会重新猜路径导致跑错测试。解决办法是在技能定义里约定好输出格式比如“测试文件路径写入.agent-skills/tmp/last-test-file”下一个技能从这个文件读。4.6 参数计算与选择以测试超时为例技能执行过程中会涉及一些参数比如测试超时时间。设太短测试没跑完就超时设太长卡住了浪费时间。我的经验算法是先跑一次完整测试记录耗时然后超时时间设为耗时的 2 到 3 倍。如果是 CI 环境再乘 1.5 倍留余量。举个例子本地跑完整测试耗时 40 秒那超时设 120 秒比较合适。如果某个测试特别慢单独给它设更长的超时而不是全局调大。这个逻辑可以写进技能定义里让 agent 根据历史耗时动态调整。注意超时设置不要写死在技能定义里最好作为配置项不同环境用不同值。本地开发可以短一点CI 上长一点。4.7 实操现场记录一次完整的 TDD 技能执行我记录一次实际执行过程方便你对照。任务是给一个 Python 函数加参数校验。我在终端启动claude code加载tdd-cycle技能。我输入任务“给parse_config函数加参数校验空字符串要报错。”Agent 调用write-failing-test在test_config.py里新增测试用例运行pytest test_config.py::test_parse_config_empty确认失败。Agent 调用write-minimal-impl在parse_config里加了一行判断空字符串抛ValueError。Agent 调用run-tests跑pytest test_config.py确认通过。Agent 调用refactor把校验逻辑抽成独立函数再跑测试确认还是通过。Agent 报告完成附上改动摘要。整个过程大概两分钟比我手动写快而且流程规范不会漏掉写测试这步。当然前提是技能定义写得好agent 遵循得好。5. 常见问题与排查技巧实录5.1 技能不生效从加载到触发的排查链技能不生效是最常见的问题。排查顺序我一般是这样确认技能文件被加载用skills CLI的列表命令看技能在不在列表里。不在的话检查技能目录路径配置对不对。确认技能格式正确技能定义文件如果有语法错误CLI 可能静默跳过。检查 YAML front matter 或者 Markdown 结构是否符合要求。确认触发条件匹配如果技能是自动触发检查你的输入是否满足触发条件。可以临时改成显式调用看能不能跑。确认 agent 上下文里有技能有些实现是把技能注入到系统提示里如果上下文太长被截断技能可能没进去。减少同时加载的技能数量试试。我遇到过一次技能文件明明在目录里但 CLI 列表里没有。后来发现是文件扩展名不对应该是.md我写成了.markdown。这种低级错误排查起来最费时间所以第一步永远是确认文件本身没问题。5.2 Agent 不遵循技能步骤原因与对策技能加载了但 agent 不按步骤走比如跳过写失败测试直接写实现。原因可能有几个一是模型本身倾向于“一步到位”需要更强的约束二是技能定义里的步骤不够具体agent 有解释空间三是上下文里有其他指令跟技能冲突。对策在技能定义里加硬性检查点。比如“在运行测试并看到失败输出之前禁止修改实现文件”。这种否定式指令比肯定式指令更有效。另外可以把大步骤拆成更小的技能每个技能只做一件事减少 agent 的自由发挥空间。5.3 第三方模型接入后的兼容问题用cc switch接入deepseek v4、qwen、glm等模型后常见问题是技能执行不稳定。有的模型能理解技能定义有的则把技能定义当成普通文本忽略掉。排查方法是先用一个极简技能测试比如“打印当前目录”看模型能不能执行。如果能再逐步加复杂度。还有一个问题是工具调用格式不兼容。claude code期望的工具调用格式第三方模型可能生成得不一样。这时候需要在中间层做适配或者选择工具调用能力强的模型。我的经验是技能越依赖工具调用对模型的要求越高纯文本推理的技能兼容性好很多。5.4 常见问题速查表问题现象可能原因排查方法解决方向技能列表为空路径配置错误检查 config 里的技能目录改成绝对路径技能加载但不用触发条件不匹配改显式调用测试放宽或明确触发条件Agent 跳过步骤约束不够强看执行日志加硬性检查点测试跑错文件技能间数据传递丢失检查中间文件约定输出格式第三方模型不遵循模型能力不足换简单技能测试换模型或加适配层执行超时超时设置太短记录实际耗时按耗时倍数调整上下文被占满加载技能太多减少同时加载数按任务加载5.5 独家避坑技巧几个我从实践中总结的技巧常规文档里不会写第一技能定义里写“不要做什么”比“要做什么”更重要。Agent 很容易过度发挥明确禁止某些行为比如“不要修改测试文件以外的文件”能省很多事。第二给技能加一个“干跑”模式。第一次执行新技能时让 agent 只报告计划不实际执行你确认没问题再真跑。这能避免 agent 乱改代码。第三技能目录用 git 管理但加 .gitignore 排除临时文件。技能执行过程中产生的中间文件比如上次测试文件路径不要提交。第四定期清理不再用的技能。技能多了会互相干扰而且加载慢。我每个月 review 一次删掉三个月没用的。第五技能命名用英文描述用中文。英文名方便命令行调用中文描述方便团队理解。混用没问题关键是保持一致。5.6 关于注册与账号的说明热词里有claude code 注册账号和不注册有啥不同、claude code harness 可以不登录用其他模型吗。我的理解是注册账号通常能获得更完整的功能和更高的配额不注册可能有限制。至于用其他模型取决于具体实现有些配置下可以接第三方模型有些则绑定官方服务。这部分建议以官方文档为准因为政策可能变化。我个人的做法是如果只是试用可以先不注册跑通基本流程如果要长期用、要团队协作还是注册账号更稳妥。6. 技能设计的进阶思路从能用 to 好用6.1 技能粒度怎么把握技能太粗比如一个“开发功能”技能包打天下agent 执行起来容易失控技能太细比如“打开文件”“写一行代码”都做成技能调用起来又太琐碎。我的经验是一个技能对应一个可验证的产出。比如“写失败测试”的产出是一个失败的测试用例“跑测试”的产出是测试结果报告。产出明确粒度就合适。判断标准很简单如果这个技能执行完你能明确说“成了”或“没成”那粒度就对了。如果执行完你还要问“这算完成了吗”那说明粒度太粗或者验证标准不清。6.2 技能之间的依赖管理技能之间会有依赖比如tdd-cycle依赖run-tests。依赖管理有两种方式一种是显式声明在技能定义里写depends_on: [run-tests]一种是隐式约定靠 agent 自己判断。我倾向于显式声明因为可控。显式声明还有个好处加载tdd-cycle的时候CLI 可以自动把依赖的技能也加载进来不用手动一个个加。但要注意循环依赖A 依赖 BB 又依赖 A会导致加载死循环。写技能的时候画个依赖图避免成环。6.3 技能的可观测性技能执行过程中你希望知道它进行到哪一步、每步花了多久、有没有异常。这就需要可观测性。我的做法是让技能在关键步骤输出日志写到统一的地方比如.agent-skills/logs/。日志格式用结构化格式方便后续分析。有了日志你可以统计哪些技能用得多、哪些步骤容易失败、平均执行时间多少。这些数据反过来指导技能优化。比如某个技能经常在第三步失败那可能是第三步的定义有问题需要改。6.4 技能与 CI 的集成技能不光能在本地用还能集成到 CI 里。比如在 PR 流程里自动跑代码审查技能把结果作为评论发出来。这样每次 PR 都有一轮自动审查人工审查可以聚焦在更高层的问题上。集成的时候注意权限控制。CI 里跑技能agent 能改文件、能执行命令权限要给得恰到好处。我的做法是CI 里的技能只读不写只做分析和报告不改代码。要改代码的场景走人工确认流程。6.5 技能库的长期维护技能库跟代码库一样需要长期维护。我的维护节奏是每周看一次日志找出失败率高的技能每月做一次 review删掉没用的、合并重复的、更新过时的每季度做一次大版本整理重新组织目录结构。维护的时候有个原则技能定义要跟着实践走不要为了定义而定义。如果一个技能在实际中从来不用那它就没有存在价值删掉比留着好。技能库的价值在于精不在于多。7. 我个人的一些体会折腾agent-skills这段时间最大的感受是AI coding agent 的上限不取决于模型取决于你怎么组织它的工作流。同样的claude code有人用起来像个高级补全有人用起来像个靠谱的结对程序员差别就在技能这层。另一个体会是技能定义的过程其实是你梳理自己工作流的过程。写 TDD 技能的时候我被迫想清楚 TDD 到底分几步、每步的输入输出是什么、怎么验证。这个思考过程本身就有价值哪怕最后不用 agent你对流程的理解也更清晰了。最后分享一个小技巧如果你刚开始接触不要急着写复杂技能。先写一个“跑测试”技能跑通感受一下 agent 按技能执行是什么体验。然后再写第二个、第三个慢慢叠加。技能库是长出来的不是设计出来的。我见过太多人一上来就想设计完美技能体系结果卡在设计阶段一个都没跑起来。先跑起来再优化这是我踩过坑之后最想说的。