1. 从agent-skills这个标题里能读出什么第一次看到agent-skills这个项目名我的直觉是这不是一个普通工具库而是一套给 AI coding agent 用的技能包。关键词里同时出现了skills CLI、Claude Code、test-driven-development基本可以确定它的定位——把可复用的工程能力封装成 agent 能直接调用的技能单元再通过一个命令行入口做安装、管理和分发。为什么这个方向值得关注因为现在大多数人用 AI 写代码卡点根本不在模型智商而在流程约束。你让模型自由发挥它可能一口气生成三百行没人敢 review 的代码你给它一套明确的技能和流程它就能像训练有素的工程师一样先写测试、再实现、最后自检。agent-skills想解决的正是后者把怎么做才对这件事从人的脑子里搬到 agent 可执行的技能定义里。这篇文章我会按一个真实使用者的视角来拆这个项目到底解决什么问题、skills CLI 的工作机制、怎么和 Claude Code 这类 coding agent 配合、TDD 技能为什么是核心、以及我在实际配置中踩过的坑。不管你是刚接触 AI coding agent 的新手还是已经在用 Claude Code 写生产代码的老手都能从中找到能直接抄的配置和思路。2. agent-skills 到底在解决什么痛点2.1 裸用 AI coding agent 的三个典型翻车场景先说清楚问题才能理解这个项目的价值。我自己用 Claude Code 这类工具写代码有一段时间了最常见的翻车场景有三个。第一个是上下文漂移。你让它改一个函数它顺手把整个文件的风格都重构了还引入了两个你没要求的依赖。原因很简单agent 没有最小改动这个默认约束它只对当前 prompt 负责。第二个是流程缺失。你让它实现一个功能它直接给你实现代码没有测试、没有边界处理、没有错误分支。你追问测试呢它才补上。这不是模型不会而是它默认走最短路径。第三个是技能不可复用。你这次教会它我们项目用 pytest fixture 组织测试下次开新会话它又忘了。每次都要重新交代一遍规范效率极低。agent-skills这类项目的核心思路就是把上述约束和流程外化成可安装、可版本管理的技能包。agent 启动时加载这些技能行为就被框住了。2.2 技能skill和提示词prompt的本质区别很多人会把 skill 和 prompt 混为一谈其实差别很大。维度普通 PromptAgent Skill生命周期单次会话跨会话持久组织方式一段文字结构化定义 触发条件可复用性靠复制粘贴靠 CLI 安装/更新可组合性弱强可叠加多个技能版本管理无可 git 追踪Prompt 是你这次告诉它什么skill 是它长期知道该怎么做。前者是临时指令后者是能力沉淀。agent-skills提供的 skills CLI本质就是这套能力沉淀的分发管道——类似 npm 之于 JS 包只不过装的是agent 的行为规范。2.3 为什么是现在coding agent 进入工程化阶段早两年大家还在比哪个模型写代码强现在比的已经是哪个 agent 工作流更可靠。这个转变背后是需求变了从帮我写个 demo变成帮我在生产仓库里安全地改代码。生产环境对 agent 的要求完全不同——要可预测、要可审计、要能回滚、要遵守团队规范。这些都不是模型能力问题而是工程约束问题。agent-skills恰好卡在这个位置上它不提升模型智商但显著提升 agent 的工程可靠性。这也是为什么它和test-driven-development这种关键词绑在一起——TDD 本身就是最强的工程约束之一。3. skills CLI 的工作机制与安装实操3.1 skills CLI 的定位agent 能力的包管理器把 skills CLI 理解成agent 世界的 npm最贴切。它的职责链条是从某个源拉取技能定义 → 解析依赖 → 安装到 agent 能读取的目录 → 让 agent 在运行时加载。这个设计的好处是解耦。技能作者只管写技能不用管用户用什么 agent用户只管装技能不用管技能内部怎么实现。中间由 CLI 做适配层。提示不同 agent 对技能目录的约定不一样安装前务必确认你的 agent 读取的是哪个路径否则装了也不生效。3.2 环境准备Node 版本与包管理器选择skills CLI 通常是 Node 生态的工具所以第一步是确认 Node 版本。我实测下来Node 18 是底线20 LTS 最稳。低于 18 会在解析某些 ESM 依赖时直接报错。node -v # 期望输出 v20.x.x 或更高 # 如果版本太低用 nvm 切换 nvm install 20 nvm use 20包管理器我建议用pnpm原因是 skills 依赖树往往比较深pnpm 的硬链接机制能省不少磁盘而且安装速度明显快于 npm。当然 npm 也能用只是慢一点。# 全局安装 skills CLI示例命令具体以项目 README 为准 npm install -g skills-cli # 验证安装 skills --version3.3 安装第一个技能从 TDD 技能开始技能安装的通用命令形态是skills install skill-name。我建议第一个装test-driven-development因为它是所有工程技能里收益最直接的一个。# 安装 TDD 技能 skills install test-driven-development # 查看已安装技能列表 skills list # 查看某个技能的详情和触发条件 skills info test-driven-development装完之后agent 在遇到实现新功能修复 bug这类任务时会自动加载 TDD 技能按先写失败测试 → 实现 → 重构的节奏走。这个变化非常明显——以前它上来就写实现现在它会先问你测试放哪、用什么框架。3.4 技能目录结构装完之后文件长什么样理解目录结构出问题时才知道去哪查。一个典型的技能安装后大致是这样.agent-skills/ ├── manifest.json # 技能清单记录版本和依赖 ├── test-driven-development/ │ ├── skill.md # 技能主定义含触发条件和行为规范 │ ├── examples/ # 示例给 agent 参考 │ └── config.json # 技能级配置 └── shared/ # 跨技能共享的规则片段skill.md是最关键的文件它决定了 agent 什么时候加载这个技能、加载后遵守什么规则。如果你发现技能没生效第一件事就是打开这个文件看触发条件写的是什么。4. 把 agent-skills 接进 Claude Code 的完整链路4.1 Claude Code 读取技能的路径约定Claude Code 这类 coding agent 一般会从项目根目录或用户主目录下的约定路径读取技能定义。常见的是项目级.claude/或.agent/目录。skills CLI 安装时如果没指定目标默认可能装到全局目录导致项目里读不到。我的做法是项目级安装把技能跟着仓库走这样团队每个人 clone 下来就有一致的行为规范。# 在项目根目录执行安装到项目级目录 skills install test-driven-development --scope project # 确认文件落到了项目里 ls -la .agent-skills/4.2 让技能真正被加载触发条件调试装好不等于生效。技能生效依赖两个条件agent 能读到文件且当前任务命中了技能的触发条件。调试方法很土但有效故意给 agent 一个应该触发技能的任务然后观察它的第一步动作。比如给一个给用户模块加一个邮箱校验函数的任务如果 TDD 技能生效它应该先问测试框架、先写测试如果它直接写实现说明技能没加载。# 查看技能是否被 agent 识别部分 CLI 支持 skills doctor # 或直接检查 agent 的加载日志 # Claude Code 通常在启动时打印已加载的技能列表注意技能触发条件写得越窄越不容易误触发写得越宽越容易在无关任务上浪费上下文。TDD 技能建议只在实现/修复类任务触发别在解释代码类任务触发。4.3 多技能叠加时的优先级冲突当你装了多个技能冲突就来了。比如 TDD 技能要求先写测试而某个快速原型技能要求先出可运行代码两者直接矛盾。处理原则是显式声明优先级。在manifest.json里给技能排个序或者用技能级的priority字段。我的经验是约束类技能TDD、代码规范优先级高于效率类技能快速原型、批量重构。因为约束一旦被绕过后面补测试的成本远高于一开始就写。技能类型建议优先级理由测试约束类高保证质量底线代码规范类高保证可维护性效率优化类中锦上添花实验探索类低可随时关闭5. TDD 技能为什么是 agent-skills 的核心5.1 TDD 给 agent 装上了自我验证能力这是我认为整个项目最有价值的一点。AI 写代码最大的问题是它不知道自己写对没有。它生成一段代码看起来合理但可能边界条件全错。而 TDD 技能强制它先写测试测试就成了它的自我验证器——跑不过测试它就知道自己错了会主动修。这个机制把 agent 从生成器变成了生成 验证的闭环。实测下来开了 TDD 技能的 agent交付代码的一次通过率明显高于裸用。5.2 红-绿-重构在 agent 场景下的具体落地经典 TDD 是红写失败测试→ 绿写最小实现让测试通过→ 重构优化代码保持测试通过。在 agent 场景下每一步都有具体表现红agent 先写测试文件运行确认失败。这一步很关键它逼 agent 明确我要实现什么。绿agent 写最小实现运行测试直到通过。注意是最小不是最优雅。重构测试通过后agent 再优化代码结构每次改动后重跑测试。我观察到的现象是agent 在绿阶段特别容易过度实现一次写一大堆。这时候 TDD 技能的约束就起作用了——它会提醒 agent只写让测试通过的最少代码。5.3 测试框架适配pytest、jest 还是别的TDD 技能本身不绑定框架但它需要知道你的项目用什么。所以安装后通常要配一下{ test-driven-development: { framework: pytest, testDir: tests/, command: pytest -x --tbshort } }command字段尤其重要它决定了 agent 用什么命令跑测试。我建议加上-x遇到第一个失败就停这样 agent 能快速拿到反馈不用等全部跑完。提示如果你的项目测试跑得很慢agent 的 TDD 循环会非常低效。建议给 agent 配一个快速测试子集命令只跑相关模块的测试。6. 实战中踩过的坑与排查链路6.1 技能装了但 agent 完全没反应这是我遇到的第一个坑。skills list显示装好了但 agent 行为毫无变化。排查链路是这样的第一步确认安装路径。skills list --verbose看技能实际落在哪个目录。结果发现装到了全局~/.agent-skills/而我的 agent 只读项目级目录。第二步确认 agent 的读取路径。翻 agent 文档确认它读的是项目根目录下的.agent-skills/。第三步重装到正确位置。skills install test-driven-development --scope project问题解决。这个坑的教训是CLI 的默认 scope 和 agent 的读取 scope 经常不一致装完一定要验证路径。6.2 技能触发了但行为不符合预期第二个坑更隐蔽。技能确实加载了但 agent 执行 TDD 时跳过了红阶段直接写实现再补测试。这等于没做 TDD。根因在skill.md的措辞。原技能定义写的是建议先写测试建议这个词太软agent 会选择性忽略。我改成必须先写测试并确认失败才能开始实现行为立刻正常。这告诉我一个经验给 agent 的技能定义要用强约束词必须禁止在...之前这类词比建议尽量有效得多。6.3 多技能叠加导致上下文爆炸第三个坑是性能问题。我一次性装了七八个技能结果 agent 每次响应都变慢而且经常精神分裂——一会儿遵守这个技能一会儿遵守那个。原因是所有技能的规则都被塞进了上下文互相干扰。解决方案是按需加载只装当前任务需要的技能或者用技能的条件加载机制让不相关的技能不进入上下文。问题现象根因解决方式技能不生效安装路径与读取路径不一致用--scope project重装行为不符预期技能定义措辞太软改用强约束词响应变慢/行为混乱技能过多上下文爆炸按需加载控制数量6.4 技能更新后旧行为残留技能是有版本的更新后可能出现新旧行为混杂。我遇到过一次更新 TDD 技能后agent 同时表现出新旧两套测试组织方式。排查发现是缓存问题。agent 可能缓存了旧的技能定义。解决方式是清缓存后重启 agentskills cache clean # 然后重启 agent养成习惯每次更新技能后清缓存 重启确保加载的是新版本。7. 技能组合的进阶玩法与个人经验7.1 把团队规范写成自定义技能agent-skills最被低估的用法是写自己的技能。官方技能解决通用问题但每个团队都有自己的规范——命名约定、目录结构、提交信息格式。这些完全可以写成自定义技能。一个最小自定义技能的结构--- name: team-conventions trigger: 实现新功能、修改现有代码 priority: high --- # 团队规范 - 所有新函数必须有类型注解 - 提交信息遵循 Conventional Commits - 新增依赖必须在 PR 描述里说明理由 - 禁止在业务代码里直接 print用 logger写完放进技能目录agent 就会遵守。这比每次开会强调规范有效多了。7.2 技能与 CI 的配合让约束真正落地技能约束的是 agent 的行为但 agent 可能出错。真正的兜底是 CI。我的做法是让技能和 CI 用同一套规则——技能里写的测试命令、lint 命令和 CI 里跑的一致。这样 agent 本地跑通了CI 基本也能过。# CI 配置片段和技能里的 command 保持一致 test: script: - pytest -x --tbshort - ruff check .一致性是关键。如果技能里用 pytestCI 里用 unittestagent 的自我验证就失去意义了。7.3 我个人的技能清单与使用节奏最后分享下我目前常驻的几个技能以及使用节奏test-driven-development常驻所有实现类任务都开。team-conventions常驻自定义的团队规范。code-review-checklist按需提交前开。refactor-safely按需重构时开。节奏上我遵循少而精原则。常驻技能不超过三个其余按任务临时装。技能不是越多越好每个技能都占上下文都会和别的技能抢注意力。提示定期用skills list清理不用的技能。我每个月清一次把三个月没用的技能卸掉保持环境干净。这套东西用下来最大的感受是AI coding agent 的可靠性七分靠约束三分靠模型。agent-skills提供的正是那七分约束的分发机制。把技能配好agent 才真正从会写代码的玩具变成能进生产流程的同事。至于具体装哪些技能、怎么写自定义技能建议从 TDD 一个开始跑顺了再逐步加别一上来就堆一堆那样只会把自己绕进去。