1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起指向一个很明确的方向——用命令行工具管理技能包让编码智能体在真实项目里按测试驱动的方式干活。先把概念对齐。所谓agent skills可以理解成给 AI 编码助手准备的岗位操作手册 工具箱。它不是模型权重也不是插件市场里的黑盒而是一组可读、可改、可版本控制的文件集合通常包含技能描述、触发条件、执行步骤、参考脚本和验证方式。skills CLI则是管理这些技能包的命令行入口负责安装、列出、启用、禁用、更新技能。为什么这件事值得单独拿出来讲因为大多数人用 AI 写代码的现状是每次开新会话都要重新解释项目结构、编码规范、测试要求模型还经常自由发挥改完不跑测试就宣布完成。agent-skills 想解决的正是这个重复劳动和不可控问题——把怎么干活沉淀成技能让 agent 每次都能按同一套标准执行。这篇文章适合三类人看一是已经在用 Claude Code 或类似编码智能体、但觉得输出不稳定的开发者二是想给团队建立 AI 编码规范的技术负责人三是刚接触 skills CLI、想知道这套东西到底怎么落地的新手。我会从技能包的内部结构讲起一路讲到 TDD 工作流怎么和 agent 配合中间穿插我自己踩过的坑。需要说明的是输入里项目正文和关键词都是空的所以下面关于目录结构、命令用法、配置细节的部分是基于这类工具在社区中的常见实践做的合理补全具体字段名请以你实际安装的版本为准。2. 技能包到底长什么样拆开 agent-skills 的内部结构2.1 一个技能的最小构成单元很多人以为技能就是一个 markdown 文件写一段提示词就完事。实际用下来一个能稳定工作的技能通常包含四部分元信息、触发描述、执行指令、验证手段。元信息负责告诉 CLI 这个技能叫什么、版本多少、依赖哪些工具。触发描述决定 agent 在什么场景下会加载它——这部分写得含糊技能就永远不会被激活或者在不该激活的时候乱激活。执行指令是核心描述具体步骤。验证手段最容易被忽略但恰恰是 TDD 场景下最关键的一环怎么判断这个技能执行成功了。我见过太多人只写执行指令结果 agent 干完活自己说已完成实际测试全红。技能里如果没有明确的验证步骤agent 就会用看起来对来代替确实对。2.2 目录布局与文件职责一个典型的技能包目录大致是这样组织的agent-skills/ skills/ tdd-workflow/ SKILL.md # 技能主描述含触发条件与步骤 scripts/ run-tests.sh # 可被 agent 调用的脚本 references/ testing-guide.md code-review/ SKILL.md skills.config.json # CLI 读取的全局配置SKILL.md是入口CLI 扫描目录时主要认这个文件。scripts/放可执行脚本agent 可以直接调用而不是自己现编命令——这一点非常重要脚本是确定性的模型生成是概率性的能用脚本就别让模型自由发挥。references/放参考资料按需加载避免一次性把上下文塞满。skills.config.json管全局比如技能搜索路径、默认启用的技能、优先级顺序。优先级这个字段值得单独说当两个技能都能匹配当前任务时谁先加载会直接影响 agent 的行为配置不当会出现该用 TDD 的时候用了快速修复技能这种尴尬。2.3 触发描述为什么比执行步骤还难写执行步骤是怎么做触发描述是什么时候做。后者更难因为它要在自然语言层面和模型的意图识别对齐。我的经验是触发描述里要同时包含正向信号和负向信号。正向信号列出典型场景关键词负向信号明确排除不该触发的情况。比如一个 TDD 技能正向信号是新增功能修复 bug需要写测试负向信号是仅修改文档仅调整格式。只写正向信号技能会在文档修改时也被拉起来白白消耗上下文。只写负向信号又容易漏触发。两者结合命中率会明显提升。这个思路和写正则表达式有点像光有匹配规则不够还得有排除规则。提示触发描述里避免使用过于宽泛的词比如代码修改优化。这些词几乎在任何任务里都会出现等于没有过滤效果。2.4 技能之间的依赖与冲突技能不是孤立的。TDD 技能可能依赖运行测试技能代码审查技能可能依赖读取 diff技能。CLI 一般支持声明依赖加载时自动把依赖项一起拉进来。冲突则更隐蔽。两个技能如果都定义了修改文件前先备份这类步骤重复执行会浪费时间如果两个技能对同一类文件给出矛盾指令agent 会随机选一个行为不可预测。我的做法是给技能划分清晰的职责边界一个技能只干一件事交叉部分抽成公共技能被双方依赖。3. skills CLI 的安装与日常操作3.1 环境准备里最容易翻车的两步skills CLI 通常通过包管理器分发。以常见的 Node 生态为例安装命令大致是npm install -g agent-skills-cli装完之后先别急着用跑一下版本检查skills --version如果提示命令找不到九成是全局 bin 目录没进 PATH。这是新手最常卡的地方尤其在 macOS 和 Ubuntu 上npm 全局目录和系统 PATH 经常对不上。解决办法是查npm config get prefix把输出的 bin 路径加进 shell 配置。第二步容易翻车的是权限。在 Ubuntu 上用 sudo 装全局包后续普通用户运行时可能读不到配置目录。我的建议是配置 npm 使用用户级目录避免 sudo省掉后面一堆权限问题。3.2 安装、列出、启用技能的标准流程CLI 的核心命令就那么几个记住就能覆盖日常命令作用常用场景skills install name安装指定技能从仓库拉取技能包skills list列出已安装技能确认当前有哪些可用skills enable name启用技能让 agent 能加载它skills disable name禁用技能临时关掉不想要的skills update更新技能同步上游改动典型流程是先skills install tdd-workflow再skills list确认装上了然后skills enable tdd-workflow。注意安装和启用是两回事装了不启用agent 不会加载。我一开始就犯过这个错装完以为万事大吉结果 agent 行为毫无变化排查半天才发现忘了 enable。3.3 技能加载顺序与优先级调优当启用的技能变多加载顺序就成了关键。CLI 一般按配置文件里的优先级排序数字小的先加载。先加载的技能会先进入上下文对 agent 的初始行为影响更大。我的调优原则是约束性强的技能放前面辅助性的放后面。比如必须写测试这种硬约束应该优先于代码风格建议这种软引导。如果顺序反了agent 可能先被风格建议带偏再看到测试要求时已经生成了不合规的代码。调整优先级直接改skills.config.json里的顺序字段即可改完记得重启会话因为技能通常在会话初始化时加载运行中改配置不一定即时生效。3.4 用 CLI 做技能的健康检查技能写多了难免有失效的。CLI 一般提供校验命令检查技能文件格式、依赖是否满足、脚本是否可执行。定期跑一次能提前发现问题。我自己的习惯是每次改完技能就校验一遍尤其是改了脚本路径之后。脚本路径写错技能加载时不报错等 agent 真去调用才失败那时候排查成本高得多。提前校验能把这类问题挡在前面。4. 把 TDD 工作流塞进 agent 的执行循环4.1 为什么 TDD 特别适合交给 agent测试驱动开发的核心是先写测试再写实现最后重构。这个循环对人类来说有点反直觉需要刻意练习但对 agent 来说反而顺理成章因为每一步都有明确的、可验证的产出。红阶段写一个会失败的测试。绿阶段写最少的代码让测试通过。重构阶段在不破坏测试的前提下优化结构。每个阶段的完成标准都是测试结果而不是我觉得写完了。这正好补上了 agent 最容易出问题的地方——自我评估不可靠。把 TDD 做成技能等于给 agent 装了一个强制性的质量闸门。它不能跳过测试直接宣布完成因为技能里明确要求必须展示测试通过的结果。4.2 技能里怎么描述红绿重构三步在SKILL.md里我会把三步拆成独立的、带验证的子步骤红根据需求写测试运行测试确认它失败并记录失败原因。绿写最小实现运行测试确认全部通过。重构在测试保持绿色的前提下调整代码每次调整后重跑测试。关键在于每一步都要求 agent实际运行命令并展示输出而不是口头描述。技能里要明确写禁止在未运行测试的情况下声称完成。这句话看着啰嗦但确实能拦住不少偷懒行为。4.3 让 agent 真正执行测试而不是假装执行这是实操中最容易出问题的一环。agent 有时会生成一段测试代码然后直接说测试通过根本没运行。要杜绝这种情况技能里必须绑定可执行脚本。比如在scripts/run-tests.sh里封装好测试命令技能指令中要求 agent 调用这个脚本并把脚本的退出码作为判断依据。退出码为 0 才算通过非 0 一律视为失败。这样判断标准就从模型说通过变成了脚本返回 0确定性大大提高。#!/bin/bash # run-tests.sh set -e npm test echo EXIT_CODE$?技能里引用这个脚本agent 调用后拿到真实结果就没法糊弄了。4.4 测试失败时 agent 的自我修复边界测试失败后agent 应该尝试修复但要有边界。我的经验是设置最大重试次数比如三次。三次还修不好就停下来报告而不是无限循环。技能里可以这样描述修复失败时先分析失败原因再针对性修改每次修改后重跑测试连续三次失败则停止输出当前状态和已尝试的方案交回人工判断。这个边界很重要没有它agent 可能在一个死胡同里反复打转浪费大量 token 和时间。5. 和 Claude Code 配合时的配置细节5.1 技能目录与工作区的相对关系Claude Code 这类工具通常从当前工作区读取配置。技能目录放在哪直接影响它能不能被发现。常见做法是把agent-skills放在项目根目录或者放在用户主目录下的全局配置位置。项目级技能跟着仓库走团队成员共享全局技能跟着个人走跨项目复用。我的建议是项目特有的规范放项目级通用能力放全局。比如本项目的测试命令是 pnpm test属于项目级写测试前先确认测试框架属于全局。放错位置会导致技能要么找不到要么在不该出现的项目里冒出来干扰。5.2 上下文预算技能不是越多越好每个启用的技能都会占用上下文窗口。技能装太多留给实际代码的空间就被挤压模型反而变笨。我实测下来同时启用的技能控制在五到八个比较舒服超过十个就开始出现顾此失彼。选择启用哪些技能时按当前任务类型来。做新功能就启用 TDD 相关做代码审查就启用审查相关不要一股脑全开。CLI 的 enable/disable 就是为这种场景准备的养成按需开关的习惯。5.3 权限与命令执行的注意事项agent 执行终端命令涉及权限。Claude Code 一般会询问是否允许某类命令或者通过配置预先授权。技能里如果包含脚本调用要确保这些脚本在允许列表内否则每次都要人工确认体验很差。我的做法是把技能用到的脚本集中放在一个目录配置里对这个目录放行其他位置保持谨慎。这样既保证技能顺畅运行又不至于把整个终端权限都交出去。安全边界和便利性之间要找个平衡点。5.4 会话初始化时技能是怎么被加载的技能通常在会话启动时加载。这意味着会话中途改了技能文件当前会话不一定生效需要重开。理解这一点能省下不少困惑——改了配置没反应先想想是不是没重启会话。另外加载是有顺序的前面提到的优先级在这里起作用。如果发现 agent 行为和你预期的技能不符先检查加载顺序再看技能是否真的被启用最后才怀疑技能内容本身。排查要按这个顺序来从外到内。6. 我在实操中踩过的坑和总结的技巧6.1 技能描述写太满反而失效刚开始我恨不得把一个技能写成百科全书把所有可能的情况都覆盖。结果 agent 加载后反而抓不住重点执行时东一榔头西一棒子。后来我把技能拆小一个技能只解决一类问题每个技能的主描述控制在合理长度效果明显好转。技能不是文档是操作指令。指令要短、要准、要可执行。参考资料放references/里按需加载不要全塞进主描述。6.2 触发条件模糊导致的技能不生效技能明明启用了agent 却不用——这个问题我遇到不止一次。排查下来八成是触发描述太模糊。模型判断要不要加载技能靠的是当前任务和触发描述的语义匹配。描述里如果全是抽象词汇匹配不上具体任务技能就形同虚设。解决办法是往触发描述里加具体场景词。比如不要写处理代码质量问题而要写当需要为新功能编写测试时当测试失败需要定位原因时。越具体命中越准。6.3 脚本路径与执行环境的坑脚本路径写相对路径在不同工作目录下执行会找不到文件。我现在的习惯是一律用相对于技能目录的路径或者在脚本里先cd到确定位置。执行环境也要注意脚本用的解释器、依赖的命令行工具都要确认在目标环境里存在。跨平台更麻烦Windows 和 Unix 的路径分隔符、换行符都不一样。如果团队里有不同系统的成员脚本尽量写得兼容或者干脆用跨平台的运行时来写。6.4 版本管理技能也要进 Git技能是代码资产必须进版本控制。我见过有人把技能放在本地随便一个目录改来改去没有历史记录出了问题无法回滚。把agent-skills目录纳入 Git每次改动都有迹可循团队协作时也能通过 PR 评审技能变更。技能变更其实挺敏感的一个措辞改动可能让 agent 行为大变。有评审流程能拦住不少拍脑袋的修改。6.5 给新手的上手路径建议如果你刚接触这套东西我的建议是别一上来就自己写技能。先从社区现成的技能包开始装上、启用、观察 agent 行为理解技能是怎么影响输出的。跑通之后再尝试改一个现成技能最后才从零写自己的。这个顺序能让你先建立技能长什么样、怎么起作用的直觉再动手创作。直接上手写很容易写出不生效的技能然后陷入为什么没用的困惑里。7. 技能体系的扩展方向技能跑通之后可以往几个方向扩展。一是把技能和 CI 打通让 agent 的产出在提交前自动过一遍测试和检查。二是建立技能库团队共享常用技能新人入职直接拉取。三是给技能加指标统计每个技能的触发频率和成功率用数据指导优化。我最近在尝试的是把技能按项目阶段分组开发阶段启用一组上线前启用另一组通过 CLI 快速切换。这样上下文里永远只有当前阶段需要的技能既省空间又减少干扰。这套东西的价值不在于技术多复杂而在于它把怎么和 AI 协作这件事从口头约定变成了可执行、可版本化、可复用的资产。刚开始搭的时候会花点时间但一旦跑顺后面每个项目都能受益。我自己从零散提示词转到技能体系之后最大的感受是终于不用每次开新会话都从头解释一遍了。