★ FEATURED ARTICLE 1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套“插件化的能力说明书”把测试驱动开发、代码审查、提交规范、重构流程这些工程实践拆成一个个可被 agent 识别、加载、执行的 skill 模块。它解决的核心问题很直接AI 写代码不差但它不知道你们团队的规矩也不懂什么叫“先写测试再写实现”。agent-skills这类项目通常围绕一个skills CLI展开配合 Claude Code 这类 AI coding agent 使用。你装好 CLI把 skill 目录挂进去agent 在干活时就能按需调用对应技能。适合谁来参考三类人最该看一是已经在用 Claude Code 或类似 agent 写代码的开发者二是想给团队统一 AI 编码规范的 tech lead三是单纯好奇“agent 到底怎么被约束”的技术爱好者。哪怕你还没上手 Claude Code理解 skill 的组织方式对你设计自己的 prompt 工作流也有直接帮助。我实测下来最大的感受是agent 的能力上限往往不取决于模型本身而取决于你给它喂了什么结构化的上下文。agent-skills干的就是这件事——把散落在文档、口头约定、老员工脑子里的工程经验变成 agent 能读懂的技能文件。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从提示词堆砌到技能模块化早期大家用 AI 写代码基本靠一段长长的 system prompt把“你要先写测试”“你要遵循 PEP8”“提交信息要规范”全塞进去。问题是提示词一长模型注意力就散了而且不同任务需要的规则不一样全塞一起反而互相干扰。agent-skills的思路是把这些规则按场景拆成独立技能每个技能有自己的触发条件、执行步骤和验收标准。打个比方这就像公司新员工培训你不会把财务报销、代码规范、请假流程全写在一张纸上让他背而是分成不同手册用到哪本翻哪本。skill 就是这个“手册”agent 在遇到“写新功能”时加载 TDD skill遇到“提交代码”时加载 commit skill。这种模块化带来的好处是可维护、可组合、可测试——你可以单独改一个 skill 而不影响其他也能把多个 skill 串成一条工作流。2.2 为什么 TDD 会成为热门 skill热搜词里test-driven-development出现频率很高这不是偶然。TDD 天然适合做成 agent skill因为它有明确的阶段划分和可验证的中间产物先写失败测试再写实现让测试通过最后重构。每个阶段都有客观的“完成信号”——测试从红变绿。agent 最怕的就是“做到什么程度算完”这种模糊指令而 TDD 恰好把这个问题解决了。我在实际配置时发现给 agent 加上 TDD skill 后它写出来的代码结构明显更清晰因为它被迫先想清楚接口和边界条件。当然代价是 token 消耗增加生成速度变慢这个后面会细说怎么权衡。2.3 skills CLI 的定位与选型考量skills CLI在这套体系里扮演的是“技能管理器”的角色负责技能的安装、注册、版本管理和调用分发。为什么不做成纯配置文件而要做成 CLI我的理解是技能需要跨项目复用也需要版本迭代。CLI 能让你像装 npm 包一样装 skill还能锁定版本避免今天能用的 skill 明天因为更新就行为不一致了。选型上如果你已经在用 Claude Code优先走它原生的 skill 加载机制兼容性最好。如果是其他 agent 框架就得看它是否支持外部技能目录挂载。这里有个坑不同 agent 对 skill 文件的格式要求不一样有的要 YAML front matter有的要特定目录结构迁移时不能直接复制粘贴。3. 核心细节解析与实操要点3.1 skill 文件的典型结构长什么样一个标准的 skill 通常包含几个部分元信息名称、描述、触发条件、执行指令、示例、验收标准。元信息里的触发条件最关键它决定了 agent 什么时候会想起用这个 skill。写得太宽泛agent 动不动就加载浪费上下文写得太窄该用的时候想不起来。我一般这样写触发条件用“当用户要求新增功能且项目已配置测试框架时”这种场景前提的组合而不是“当用户想写代码时”这种大而全的描述。执行指令部分要写成步骤化的最好带编号因为 agent 对有序列表的遵循度明显高于大段散文。3.2 技能加载的优先级与冲突处理当你装了多个 skill冲突是难免的。比如一个 skill 说“提交前必须跑全量测试”另一个说“小改动可以跳过测试直接提交”。这时候 agent 会懵。我的做法是给 skill 设优先级或者在项目级配置里明确覆盖规则。agent-skills这类项目一般会支持一个priority字段数值高的先执行。另一个实操要点是不要把互相矛盾的 skill 同时启用。我见过有人把“严格 TDD”和“快速原型模式”两个 skill 一起挂上结果 agent 在写测试和跳过测试之间反复横跳输出质量反而下降。技能不是越多越好按当前任务类型启用对应的两三个就够了。3.3 与 Claude Code 的集成方式Claude Code 对 skill 的支持相对成熟基本流程是在项目根目录建一个 skills 文件夹每个 skill 一个子目录里面放 skill 定义文件。然后在 Claude Code 的配置里指向这个目录。启动后 agent 会自动扫描可用技能在对话中根据上下文决定是否加载。这里有个细节值得注意skill 目录不要放在会被 git 忽略的位置否则团队其他人拉代码后没有这些技能行为就不一致了。我一般把 skill 纳入版本控制和代码一起管理。另外skill 文件里的路径引用要用相对路径绝对路径换台机器就失效了。提示skill 文件写完先自己读一遍问自己“一个不了解项目背景的人只看这个文件能不能照着做”。如果答案是否定的agent 大概率也做不好。4. 实操过程与核心环节实现4.1 环境准备与 skills CLI 安装假设你在 Ubuntu 或 macOS 上已经装好了 Node.js 环境。skills CLI 一般通过包管理器安装命令类似npm install -g skills-cli或项目提供的安装脚本。装完后用skills --version验证。如果是 Windows建议走 WSL因为部分 skill 脚本依赖 shell 环境。安装完成后初始化一个技能仓库skills init会在当前目录生成 skills 文件夹和示例 skill。你可以直接改示例也可以从零写。我建议先跑通示例确认 agent 能正确加载再写自己的。4.2 编写第一个 TDD skill 的完整过程我以 TDD skill 为例走一遍编写流程。首先建目录skills/tdd/在里面创建SKILL.md。文件开头写元信息--- name: test-driven-development description: 当需要新增功能或修复 bug 时按 TDD 流程执行 trigger: 用户要求实现新功能且项目已配置测试框架 priority: 10 ---然后写执行步骤。我把它分成四步第一步理解需求并写出至少一个失败测试第二步运行测试确认它失败且失败原因是功能未实现而非语法错误第三步写最小实现让测试通过第四步重构并确保测试仍通过。每一步都写清楚“完成标志”是什么比如第一步的完成标志是“测试文件已创建且包含至少一个断言”。写完后再加一段示例展示一个简单的输入输出场景。示例很重要agent 会模仿示例的风格。最后写验收标准所有测试通过、无跳过测试、覆盖率不低于某个阈值。4.3 参数选择与效果验证TDD skill 里有个关键参数是“测试粒度”。太细agent 会写一堆琐碎测试拖慢速度太粗又起不到驱动设计的作用。我的经验值是每个测试对应一个公开方法或一个明确的行为分支。比如一个解析函数正常输入、空输入、非法输入各一个测试就够了。验证 skill 是否生效可以给 agent 一个简单任务观察它是否先创建测试文件。如果它直接写实现说明触发条件没写对或者 skill 没被加载。这时候检查 CLI 的日志输出看它扫描到了哪些 skill。我踩过的坑是skill 文件名大小写和配置里写的不一致导致加载失败但没有任何报错排查了半天。5. 常见问题与排查技巧实录5.1 skill 不生效的排查顺序遇到 skill 不生效按这个顺序查先确认 CLI 能列出该 skillskills list再确认 agent 配置指向了正确目录然后看 skill 的触发条件是否匹配当前任务最后检查 skill 文件格式是否有语法错误。大部分问题出在第二步和第三步。我整理了一个速查表现象可能原因解决方式skill 列表为空目录路径错误检查配置中的绝对/相对路径skill 列出但不加载触发条件不匹配放宽 trigger 描述或手动指定加载后行为异常文件格式错误用 YAML 校验工具检查 front matter多个 skill 冲突优先级未设置给关键 skill 设更高 priority5.2 token 消耗与速度的平衡启用 TDD skill 后token 消耗大概增加 30% 到 50%因为 agent 要多写测试文件、多跑几轮。如果项目对速度敏感可以只在核心模块启用 TDD skill边缘代码用轻量 skill。另一个技巧是把 skill 里的示例精简示例占的 token 往往比指令本身还多。5.3 团队协作中的 skill 管理团队用 skill 最大的问题是版本漂移有人改了 skill 没通知别人拉下来行为就变了。我的做法是给 skill 仓库打 tag项目里锁定版本号。另外skill 的修改要走 code review因为一个错误的触发条件可能让所有人的 agent 都跑偏。还有一点新成员入职时先让他读一遍 skill 文件这比读文档更直接因为 skill 就是团队工程规范的 executable 版本。6. 技能扩展与个人经验补充agent-skills这套东西最吸引我的地方是可扩展性。除了 TDD我还见过有人写 code-review skill、commit-message skill、甚至“解释这段代码”的 skill。我的建议是从你最痛的那个环节开始写不要一上来就搞大而全的技能库。先写一个用一周根据实际效果迭代比一次性写十个然后全都不用要强。另外skill 不是越细越好。我试过把“写测试”和“跑测试”拆成两个 skill结果 agent 经常只加载其中一个流程就断了。后来合并成一个反而稳定。判断标准很简单如果两个步骤总是成对出现就放一个 skill 里。最后分享一个小技巧在 skill 文件末尾加一段“如果遇到不确定的情况先问用户而不是猜测”。这句话能显著减少 agent 自作主张导致的返工。我实测下来加了这句之后需要人工纠正的次数大概少了一半。
阅读完成 · 觉得有帮助？
