1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新员工来培养的技能体系。事实也确实如此——它把散落在各种博客、推文、issue 里的 agent 使用经验收敛成了一套可安装、可复用、可版本管理的 skill 集合通过一个skillsCLI 分发到 Claude Code 这类 AI coding agent 的工作目录里。说白了它解决的是一个很具体的痛点你每次开一个新会话agent 都像失忆一样不知道你的代码规范、不知道你的测试习惯、不知道你踩过哪些坑。你要么每次手动贴一大段上下文要么写一个巨大的CLAUDE.md把所有东西塞进去结果就是上下文窗口被静态说明占满真正干活的空间被压缩。agent-skills的思路是把能力拆成一个个独立的 skill 单元按需加载。比如test-driven-development这个 skill只在你要写测试的时候才被激活code-review只在 review 阶段激活。这跟传统把所有规则写进系统提示的做法有本质区别——前者是按需检索后者是全量注入。适合谁看这篇三类人一是已经在用 Claude Code、但感觉它不够懂我的开发者二是想给自己的团队搭一套统一 agent 工作流的 tech lead三是纯粹好奇AI coding agent 的技能到底怎么组织的技术爱好者。不需要你懂 agent 内部实现但需要你对命令行和 Git 有基本概念。2. skills CLI 到底在做什么把经验变成可加载模块2.1 为什么不是简单复制文件很多人第一反应是不就是把 markdown 文件拷到~/.claude/skills/目录吗为什么要搞个 CLI我一开始也这么想直到我手动维护了十几个 skill 之后才发现问题。手动拷贝有三个绕不开的麻烦版本漂移你从 A 仓库拷了一份 skill改了两个字又从 B 仓库拷了一份同名的覆盖了。过两周你根本不知道本地这份是哪个版本。路径不一致Claude Code 在不同平台macOS、Linux、Windows WSL的配置目录不一样手动拷贝很容易放错地方agent 静默地加载不到你还以为是 skill 写错了。更新困难上游 skill 修了个 bug你得重新走一遍找到文件、对比、覆盖的流程。skillsCLI 把这三件事都收敛了它知道每个平台的正确安装路径知道每个 skill 的来源和版本支持一条命令更新全部。这跟npm、brew的存在逻辑是一样的——当手动管理的边际成本超过某个阈值工具化就是必然。2.2 安装与首次运行CLI 本身通常通过包管理器分发。以常见的 Node 生态为例安装命令大致是这样# 全局安装 skills CLI npm install -g agent-skills/cli # 验证安装 skills --version # 查看可用 skill 列表 skills list # 安装指定 skill 到 Claude Code 目录 skills install test-driven-development注意具体的包名和命令以仓库 README 为准不同版本可能有差异。我建议先跑skills --help看清楚子命令再动手。安装完成后CLI 会把 skill 文件放到 Claude Code 能识别的目录。这里有个很容易踩的坑Claude Code 读取 skill 的目录是分层的——有全局的用户级也有项目级的仓库内。全局的对你所有项目生效项目级的只对当前仓库生效。skills install默认装到全局如果你希望某个 skill 只在这个项目里用得加--local之类的参数。我的建议是通用能力比如 TDD、code review装全局项目特有的比如我们这个仓库的 API 命名规范装项目级。这样既不会污染其他项目也不会在新项目里丢失通用能力。2.3 skill 文件长什么样一个 skill 本质上是一个带 frontmatter 的 markdown 文件。结构大致如下--- name: test-driven-development description: 当用户要求编写新功能或修复 bug 时先写测试再写实现 trigger: 编写测试、TDD、红绿重构 --- ## 核心原则 1. 先写一个失败的测试 2. 写最少的代码让测试通过 3. 重构保持测试绿色 ## 具体步骤 ...关键字段是description和trigger。agent 不是把所有 skill 全文读进上下文而是先读这些元数据判断当前任务该激活哪个 skill再加载全文。这就是按需加载的实现方式也是它比巨型 CLAUDE.md更省上下文的原因。理解了这一点你写自己的 skill 时就知道重点在哪description要写得让 agent 能准确判断什么时候该用我正文才写具体怎么做。很多人把description写成一句废话这是一个关于测试的 skill结果 agent 永远不激活它。3. test-driven-development 这个 skill 为什么值得单独拎出来讲3.1 TDD 对 agent 的意义和人类不一样对人类开发者来说TDD 是一种设计方法论——先写测试逼你想清楚接口。但对 AI coding agent 来说TDD 的意义更实际它是防止 agent 幻觉式完成的最有效手段。我踩过太多次这个坑让 agent 实现一个函数它洋洋洒洒写了一大段还自信地说已完成。你一跑报错。或者更糟——它跑通了但逻辑是错的因为它偷偷改了你的调用方式去迁就自己的实现。TDD 把这个过程锁死了测试是你写的或者你审核过的agent 的任务只有一个——让测试变绿。它没有空间去重新定义什么叫完成。这就是为什么test-driven-development这个 skill 在 agent 场景下价值极高它不只是编码习惯而是一种约束 agent 行为的机制。3.2 红绿重构在 agent 工作流里的具体落地标准的红绿重构三步在 agent 协作里我会这样拆第一步红。你或 agent 根据你的描述先写测试运行确认它失败。这一步不能省。我见过太多人跳过确认失败结果测试写错了比如断言写反了一直是绿的agent 随便写点什么都通过。第二步绿。让 agent 写实现只要求测试通过。这时候要明确告诉它不要过度设计不要顺手重构别的代码。agent 有个坏习惯你让它改 A它觉得 B 也不顺眼一起改了然后 B 的测试挂了。第三步重构。测试绿了之后再优化结构。这一步可以交给 agent但前提是测试覆盖足够。重构完必须重跑测试。在 skill 里这三步会被写成明确的指令序列agent 每次激活这个 skill 就按这个流程走。关键价值在于流程固化——你不需要每次都在 prompt 里重复这套要求。3.3 一个真实的对比我做过一个不太严谨的对比。同一个任务实现一个带边界检查的日期解析函数两种方式方式首次通过率返工次数我的介入次数直接让 agent 实现约 40%平均 2.3 次3-4 次先写测试再让 agent 实现约 85%平均 0.6 次1-2 次数据样本很小不能当结论但趋势很明显前期多花 5 分钟写测试后期省下的是反复沟通和排查的时间。而且测试写完之后是可以复用的下次改这个函数测试还在。4. 把 agent-skills 接进 Claude Code 的完整链路4.1 环境准备里最容易被忽略的两件事第一件是目录权限。skill 文件要放到 Claude Code 能读的目录如果你用sudo装到了系统目录普通用户跑 Claude Code 时可能读不到。我建议全部装在用户目录下避免权限问题。第二件是确认 Claude Code 真的加载了 skill。很多人装完就以为生效了其实没有。验证方法很简单开一个新会话问 agent 你现在有哪些可用的 skill或者直接触发一个应该激活 skill 的场景看它的行为是否符合 skill 描述。如果没反应八成是路径不对或 frontmatter 格式有问题。4.2 项目级 vs 全局怎么选这个决策我前面提了一句这里展开说。判断标准是这个 skill 的知识是否跨项目通用。跨项目通用TDD 流程、code review 清单、commit message 规范、通用调试方法 → 装全局项目特有这个仓库的目录结构约定、内部 API 用法、特定的构建命令 → 装项目级项目级的 skill 通常会跟着仓库一起提交到 Git这样团队每个人 clone 下来就自动有了。这是agent-skills一个很聪明的设计——它让 agent 的团队知识可以像代码一样被版本管理。4.3 和 CLAUDE.md 的分工这里必须澄清一个常见误解skill 不是用来替代CLAUDE.md的两者分工不同。CLAUDE.md适合放永远需要知道的、简短的、全局的信息比如这个项目用 pnpm 不用 npm、测试命令是pnpm test。它是每次会话都会加载的。skill 适合放特定场景才需要的、较长的、流程性的信息比如完整的 TDD 步骤、详细的 review 清单。它是按需加载的。我的经验是CLAUDE.md控制在 50 行以内超过的内容就该考虑拆成 skill 了。一个臃肿的 CLAUDE.md 会持续消耗每次会话的上下文预算而 skill 只在需要时付费。5. 自己写一个 skill从踩坑到跑通5.1 什么样的经验值得写成 skill不是所有东西都值得 skill 化。我总结了一个简单的判断标准如果这件事你会反复向 agent 解释且解释内容基本固定那就值得写成 skill。反例一次性的调试过程、某个具体 bug 的修复方案——这些写进对话就行写成 skill 反而增加维护负担。正例你团队的代码风格、你偏好的重构手法、你要求 agent 遵守的安全检查清单——这些每次都要说且内容稳定。5.2 frontmatter 写不好skill 就是死的我前面强调过description和trigger的重要性这里给个具体的写法对比。差的写法description: 关于代码审查的 skill好的写法description: 当用户要求审查代码、检查 PR、或提到 code review 时激活。按安全性、可读性、性能三个维度逐项检查输出结构化问题列表。区别在于好的写法明确告诉 agent什么时候用触发条件和用了之后做什么行为预期。agent 判断是否激活 skill靠的就是这段文字。写得模糊它就永远不激活你装了等于没装。5.3 一个我实际在用的 skill 骨架以提交前检查为例我的 skill 大致长这样--- name: pre-commit-check description: 当用户准备提交代码、或提到 commit、提交前检查时激活。依次运行 lint、类型检查、单元测试任一失败则阻止提交并报告。 trigger: 提交、commit、pre-commit --- ## 执行顺序 1. 运行 pnpm lint失败则停止 2. 运行 pnpm typecheck失败则停止 3. 运行 pnpm test失败则停止 4. 全部通过后生成符合规范的 commit message ## 注意事项 - 不要自动执行 git commit只做检查并报告结果 - 如果 lint 有自动修复项先询问用户是否修复这个 skill 帮我省掉了每次都要打一长串提交前先跑 lint 再跑测试的麻烦。注意最后那条不要自动 commit——这是安全边界agent 不应该在没有明确指令的情况下改动 Git 历史。5.4 调试 skill 不生效的排查链路skill 装了但没反应按这个顺序查文件在不在正确目录ls一下 Claude Code 的 skill 目录确认文件真的在那frontmatter 格式对不对YAML 对缩进敏感多一个空格都可能解析失败description 是否可被匹配把你的触发词直接说给 agent 听看它是否激活是否有同名冲突全局和项目级有同名 skill 时加载哪个取决于实现容易出意外重启会话skill 通常在会话启动时加载改完文件要开新会话我遇到最多的是第 2 条。YAML 里description如果包含冒号必须加引号否则解析直接失败而且失败是静默的——agent 不会报错只是当这个 skill 不存在。6. 几个绕不开的实操问题6.1 skill 太多会不会拖慢 agent会但影响方式和你想的不一样。skill 的元数据name、description会被加载用于匹配正文不会。所以真正影响性能的是元数据的数量不是 skill 的总数。我的经验是几十个 skill 的元数据开销可以忽略但如果你装了几百个匹配准确率会下降——agent 可能激活错误的 skill。定期清理不用的 skill比无脑囤积更重要。6.2 团队协作时怎么同步 skill项目级 skill 跟着 Git 走这是最省心的方式。但要注意skill 里不要写死个人偏好。比如我喜欢用 2 空格缩进这种写进团队共享的 skill 会引发争议。团队 skill 只放共识个人偏好放全局 skill。另外skill 的变更应该走 code review。一个改错的 skill 会影响团队所有人的 agent 行为比改错一行代码影响面更大。6.3 和第三方模型的兼容性agent-skills的设计是围绕 Claude Code 的 skill 加载机制来的。如果你用的是其他支持 skill 概念的 agent 工具目录结构和 frontmatter 格式可能不同需要做适配。核心思路元数据匹配 按需加载正文是通用的但具体文件格式要按目标工具的要求来。我个人的做法是把 skill 的内容和格式分离。内容流程、清单、原则写在一个中立的 markdown 里然后用脚本生成各工具需要的格式。这样换工具时不用重写内容。7. 我用了几个月之后的真实体会最开始我是抱着试试看的心态装的觉得无非是把 prompt 模板换了个地方放。用了几个月之后最大的改变不是效率而是一致性。以前我让 agent 写代码质量波动很大——有时候它记得写测试有时候不记得有时候它遵守命名规范有时候乱来。这种波动让我不敢完全信任它每个输出都要仔细检查。装了 skill 之后至少在我定义了 skill 的场景里它的行为是可预期的。可预期比偶尔惊艳重要得多因为可预期才能放心地把任务交出去。另一个体会是写 skill 的过程其实是在逼自己把隐性经验显性化。很多规范我平时是凭感觉遵守的写 skill 时不得不把它拆成明确的步骤这个过程本身就让我对自己的工作流理解更深了。如果你刚开始我的建议是别贪多。先挑一个你最常向 agent 重复解释的场景写成一个 skill跑通用一周。有感觉了再扩展。一上来就装几十个 skill你根本不知道哪个在起作用出了问题也无从排查。最后分享一个小技巧给每个 skill 加一个最后更新日期的注释。skill 是会过期的——你的项目结构变了、工具链升级了skill 里的命令可能就失效了。有个日期你至少知道哪些该回头检查了。