1. 从 agent-skills 说起为什么它值得单独拿出来聊第一次看到agent-skills这个词是在翻 Claude Code 相关仓库的时候。当时我的第一反应是这不就是把一堆提示词打包成文件夹吗但真正把它拉下来跑了一遍、又自己照着结构写了几个 skill 之后我改变了看法。它解决的其实是一个很具体的问题——AI coding agent 每次开新会话都像失忆你得反复告诉它同一套规矩。而 agent-skills 就是把这套规矩沉淀成可复用、可版本管理、可被 agent 自动加载的模块。说白了agent-skills 是一套面向 AI 编程代理AI coding agents的技能组织规范。它把「怎么做事」这件事从对话里抽出来变成磁盘上的结构化文件。你写一次Claude Code 这类工具在合适的时机自动读取之后每次让它写测试、做代码审查、跑迁移脚本它都按你定好的流程走而不是每次靠你临场描述。这对天天用 Claude Code 写代码的人来说价值非常直接减少重复沟通、统一团队规范、让 agent 的行为可预测。这篇文章适合三类人看。第一类是已经在用 Claude Code、但还停留在「聊天框里贴需求」阶段的开发者你会看到怎么把零散经验变成资产第二类是想给团队统一 AI 编码规范的 tech leadagent-skills 天然适合做规范载体第三类是对 skills CLI、test-driven-development 这类关键词好奇、想搞清楚它们怎么串起来的人。我会从设计思路讲到落地实操包括目录结构、加载机制、怎么写一个能用的 skill、以及我踩过的坑。全程按我自己的实践来讲不绕弯子。需要先说明一点agent-skills 本身是一套约定和工具链不是某个闭源产品。它的核心是「文件结构 元数据 触发条件」这三件事。理解了这三件事你就能判断哪些场景值得写成 skill哪些场景写了反而添乱。下面我按这个逻辑一层层拆。2. agent-skills 的整体设计与思路拆解2.1 它到底解决什么问题从「提示词堆积」到「技能模块化」用 Claude Code 时间长了你会发现一个规律真正高效的用法不是每次写超长 prompt而是把稳定的部分固化下来。比如「写单元测试要先列边界条件、再写失败用例、再实现、最后重构」这套 test-driven-development 流程你不可能每次都在对话里重敲一遍。以前的做法是存个 snippet手动粘贴agent-skills 的做法是把它变成一个带触发条件的技能agent 在识别到「用户要求写测试」时自动加载。这个转变的意义在于关注点分离。提示词是易变的、一次性的技能是稳定的、可复用的。把两者混在一起结果是你的对话越来越长agent 的注意力被稀释行为越来越不可控。拆开之后对话只负责表达「这次要做什么」技能负责表达「这类事该怎么做」。这是 agent-skills 最核心的设计哲学也是我建议你先想清楚再动手的原因。2.2 核心概念拆解skill、metadata、trigger 三件套一个 skill 在磁盘上通常就是一个目录里面至少有一个描述文件常见是 Markdown 加 YAML frontmatter或者独立的元数据文件。这个描述文件包含三部分信息元数据metadata技能名、版本、作者、适用场景的简短描述。这部分是给人和工具看的索引。触发条件trigger什么情况下加载这个技能。可以是关键词匹配、文件类型、任务类型也可以是显式调用。技能正文body具体怎么做事的步骤、约束、示例、检查清单。我一开始只写了正文没写触发条件结果 agent 要么不加载要么乱加载。后来才明白触发条件是 skill 和普通文档的分水岭。没有触发条件它就只是一份躺在仓库里的说明有了触发条件它才是 agent 能主动调用的能力。2.3 为什么用文件而不是数据库或服务有人会问为什么不搞个中心化服务来管理这些技能我的实践结论是文件系统是最低摩擦的方案。原因有三。第一技能需要跟着代码仓库走团队 clone 下来就能用不需要额外部署。第二技能需要版本管理Git 天然适合谁改了什么、什么时候改的一目了然。第三技能需要被 agent 直接读取文件是最通用的接口Claude Code 这类工具本来就在文件系统里工作。用文件还有一个隐性好处可审查。AI 编码最让人不放心的地方就是黑盒而 skill 是纯文本你能逐行读、逐行改。团队做 code review 时skill 的改动和业务代码的改动走同一套流程这在合规和信任层面很重要。2.4 和 Claude Code 的关系为什么它在这套工具里特别顺Claude Code 的工作方式是在你的项目目录里读写文件、执行命令。agent-skills 放在项目里Claude Code 天然能访问。更关键的是Claude Code 支持在会话中读取项目内的约定文件这就让 skill 的自动加载变得自然。你不需要额外配置什么服务把 skill 目录放对位置Claude Code 在需要时就能读到。这也是为什么热词里claude code、claude code使用、claude code 入门教程和agent-skills经常一起出现。它们不是并列关系而是载体和内容的关系Claude Code 是执行载体agent-skills 是喂给它的结构化知识。理解了这层关系你就知道学 agent-skills 的前提是先能把 Claude Code 跑起来。3. 核心细节解析与实操要点3.1 目录结构怎么设计才不混乱我试过几种目录组织方式最后稳定下来的结构是这样的project-root/ .agent-skills/ skills/ test-driven-development/ SKILL.md examples/ templates/ code-review/ SKILL.md db-migration/ SKILL.md registry.yaml.agent-skills放在项目根目录和.github、.vscode一个层级语义清晰。skills下面每个子目录是一个技能目录名就是技能标识用 kebab-case。每个技能目录里SKILL.md是入口examples和templates放辅助材料。registry.yaml是可选的索引列出所有技能和它们的触发条件方便工具快速扫描也方便人一眼看全。注意目录名不要用中文或空格。agent 在解析路径时对特殊字符的处理不一定稳kebab-case 是最保险的选择。3.2 SKILL.md 的写法frontmatter 加正文SKILL.md我推荐用 YAML frontmatter 加 Markdown 正文的结构。frontmatter 放元数据和触发条件正文放具体内容。一个 test-driven-development 技能的例子--- name: test-driven-development version: 1.0.0 description: 在实现新功能或修复 bug 时按红绿重构流程编写测试 triggers: - keyword: 写测试 - keyword: TDD - task: implement-feature - task: fix-bug --- ## 流程 1. 先写一个失败的测试明确预期行为 2. 运行测试确认它失败且失败原因是预期原因 3. 写最少量的实现代码让测试通过 4. 运行全部测试确认没有破坏其他功能 5. 重构保持测试全绿 ## 约束 - 不允许先写实现再补测试 - 每个测试只验证一个行为 - 测试命名要描述行为不要描述实现frontmatter 里的triggers是关键。keyword是关键词匹配task是任务类型匹配。实际用的时候agent 会综合判断不是简单字符串包含。我建议 triggers 不要写太多三到五条足够写多了容易误触发。3.3 触发条件的设计宁窄勿宽这是我踩过最大的坑。一开始我给某个技能写了keyword: 代码结果几乎每次对话都触发agent 被无关技能干扰输出质量反而下降。后来我把触发条件收窄只保留高区分度的词和明确的任务类型效果立刻好转。判断标准很简单如果这个触发条件在你不希望加载技能时也会命中那它就太宽了。比如「测试」这个词在「帮我看看这个测试为什么失败」的场景下你其实不需要加载完整的 TDD 流程只需要排查。这时候用task: write-test比keyword: 测试精准得多。3.4 技能粒度一个技能只做一件事技能粒度是另一个容易做错的地方。我见过有人把「写测试 代码审查 提交信息规范」塞进一个技能理由是「都是开发流程」。结果这个技能又长又杂agent 加载后注意力分散每个环节都做得不深。我的经验是一个技能对应一个可独立描述的流程。TDD 是一个技能code review 是另一个commit message 规范是第三个。它们可以互相引用但不要合并。粒度细的好处是触发精准、维护简单、复用性高。坏处是技能数量会变多这时候registry.yaml的索引价值就体现出来了。3.5 版本管理技能也要 semver技能是会被修改的。今天你觉得测试要先写边界条件明天团队决定改成先写 happy path。这些改动如果不管理agent 的行为就会悄悄漂移出了问题很难追溯。所以我给每个技能都加了version字段遵循语义化版本破坏性改动升 major新增内容升 minor措辞调整升 patch。配合 Git你就能回答「上周 agent 为什么那样写测试」这类问题。这在团队协作里尤其重要因为 skill 的改动会影响所有人的 agent 行为必须可追溯。4. 实操过程与核心环节实现4.1 环境准备先把 Claude Code 跑起来agent-skills 要发挥作用前提是 Claude Code 能正常工作。这一步我不展开讲安装细节因为不同系统差异大但把关键点说清楚。在 macOS 和 Ubuntu 上Claude Code 的安装方式略有不同官方文档有对应说明。装完之后你需要确认它能正常读写项目文件、执行终端命令。VS Code 用户可以通过插件方式接入配置好之后在编辑器里直接调用。如果你在 VS Code 里配置 Claude Code注意工作区目录要指向你的项目根目录否则它读不到.agent-skills。提示Claude Code 在某些地区可能不可用官方文档里有支持地区的说明动手前先确认一下避免白折腾。关于模型接入除了默认配置也有人通过第三方 API 接入其他模型。这类配置属于工具使用范畴核心是保证 Claude Code 能正常发起请求并拿到响应。配置完成后用一个简单任务验证一下比如让它读一个文件并总结能跑通再往下走。4.2 创建第一个技能从 test-driven-development 开始我建议第一个技能就写 TDD因为它流程清晰、收益明显、容易验证。步骤如下。第一步在项目根目录建.agent-skills/skills/test-driven-development/。第二步创建SKILL.md把前面那段 frontmatter 和正文写进去。第三步在项目里随便找个函数让 Claude Code「用 TDD 方式给这个函数加一个测试」。观察它是否按红绿重构的顺序走。如果它没有按流程走先检查触发条件是否命中。你可以显式说「加载 test-driven-development 技能」看它能不能找到。能显式加载但不会自动触发说明 triggers 需要调整显式加载都失败说明路径或格式有问题。4.3 参数与配置的选择过程技能里经常需要一些可配置项比如测试框架、代码风格、目录约定。我的做法是把可变部分抽成配置放在技能目录的独立文件里而不是硬编码在 SKILL.md 正文中。比如# .agent-skills/skills/test-driven-development/config.yaml test_framework: vitest test_dir: src/__tests__ naming: behavior-based这样换项目时只改配置不动技能逻辑。SKILL.md 里用占位符引用这些配置agent 加载时会读取实际值。这个设计让技能的可移植性大幅提升同一个 TDD 技能能适配不同技术栈的项目。选择配置项的原则是只抽真正会变的。测试框架会变抽出来红绿重构的顺序不会变留在正文里。抽太多会让技能变得难懂抽太少又失去灵活性这个度需要根据你的实际项目判断。4.4 让技能被自动加载验证与调试技能写完之后最关键的验证是「自动加载」。我的调试方法是开一个全新会话不提技能名直接说一个应该触发它的任务看 agent 的行为是否符合技能定义。如果符合说明触发链路通了如果不符合逐步排查。排查顺序我总结成三步。第一确认文件路径和格式正确frontmatter 能被解析。第二确认触发条件能命中当前任务可以临时把条件放宽测试。第三确认技能正文没有语法错误导致解析失败。这三步走完绝大多数加载问题都能定位。4.5 一个完整的实操记录我拿一个真实场景走一遍。项目里有个calculateDiscount函数我想给它补测试。我在 Claude Code 里输入「给 calculateDiscount 补单元测试覆盖边界情况」。agent 识别到task: write-test加载了 TDD 技能。它先读函数实现然后列出边界条件金额为 0、金额为负、折扣率为 0、折扣率为 1、折扣率超过 1。接着它写了第一个失败测试运行确认失败。然后写实现让测试通过再写下一个。整个过程它没有一次性写完所有测试而是严格按红绿重构走。这个过程中我注意到一个细节它在写测试前会先确认测试框架这是因为它读了config.yaml里的test_framework。如果没有这个配置它会默认用项目里已有的框架或者问我。这就是配置抽离的价值——减少来回确认让 agent 自己拿到上下文。5. 常见问题与排查技巧实录5.1 技能不生效的排查清单技能不生效是最常见的问题我把排查路径整理成表按顺序查基本能定位。现象可能原因排查方法完全不加载路径错误或目录名不对确认.agent-skills/skills/层级正确显式调用失败SKILL.md 格式错误检查 frontmatter 的 YAML 语法不自动触发触发条件太窄或太宽临时放宽条件测试命中情况加载了但行为不对正文描述模糊把步骤写得更具体加约束多个技能冲突触发条件重叠收窄条件明确优先级这张表是我实际排查时总结的比漫无目的地改文件高效得多。尤其是「加载了但行为不对」这一类很多人以为是加载问题其实是正文写得太笼统agent 只能自由发挥。5.2 触发条件写太宽的后果前面提过触发条件写太宽的问题这里展开说后果。当多个技能因为宽泛的关键词同时被加载agent 的上下文里会塞进多套流程它可能把 A 技能的步骤和 B 技能的约束混在一起用输出看起来「什么都沾一点什么都不精」。更糟的是这种问题很隐蔽你很难一眼看出是技能冲突导致的。我的解决办法是给技能加优先级字段冲突时高优先级的生效。同时在 registry 层面做一次全局检查确保没有两个技能的触发条件高度重叠。这个检查我建议每次新增技能时都做一遍成本很低收益很大。5.3 技能正文写太长的陷阱另一个坑是正文写太长。我一开始恨不得把十年经验全塞进一个技能结果 agent 加载后抓不住重点执行时漏步骤。后来我给自己定了个规矩一个技能的正文控制在能一屏读完的长度超出的部分拆成子技能或者放到 examples 里按需引用。正文的结构我固定成三块流程、约束、示例。流程是必须做的步骤约束是不能做的事示例是参考。三块加起来如果超过一屏就说明这个技能该拆了。这个规矩执行下来技能的可维护性和 agent 的执行准确率都明显提升。5.4 团队协作中的技能管理团队用 agent-skills最大的挑战不是技术是规范的一致性。每个人对「好的测试」理解不同写出来的技能就不同最后 agent 的行为在团队里不统一。我的做法是设立一个技能 review 流程新增或修改技能都要走 PR至少一个人 review。review 的重点是触发条件是否精准、流程是否可执行、约束是否明确。另外技能要有 owner。每个技能目录里放一个OWNERS文件写明谁负责维护。这样出问题时知道找谁也避免技能变成没人管的孤儿文件。这套机制听起来重但实际跑起来成本不高因为技能改动频率远低于业务代码。5.5 独家避坑技巧分享几个我踩坑后总结的技巧。第一新技能先在个人分支试别直接进主分支因为技能改动会影响所有人的 agent 行为试错成本高。第二给技能写测试虽然听起来奇怪但你可以写一个脚本模拟触发条件检查 agent 是否按预期加载这在技能多的时候很有用。第三定期清理僵尸技能项目演进后有些技能不再适用留着只会干扰触发每季度过一遍。还有一个技巧关于调试当你不确定 agent 为什么没按技能走时让它「复述当前加载了哪些技能和约束」。这个方法能快速暴露加载问题比猜高效得多。我用这招定位过好几次触发条件冲突的问题。6. 技能扩展与进阶玩法6.1 组合技能让多个技能协同单个技能用熟之后可以尝试组合。比如 TDD 技能负责写测试code-review 技能负责审查两者可以在一个任务里先后触发。关键是定义好技能之间的边界和交接点。TDD 技能结束时应该产出「测试全绿的代码」code-review 技能从这里接手。交接点写清楚agent 就不会在两个技能之间迷失。组合的方式有两种。一种是隐式组合靠触发条件自然衔接另一种是显式组合在一个技能里引用另一个技能。我倾向隐式组合因为耦合度低改一个不影响另一个。显式组合适合流程强绑定的场景比如「部署前必须过安全扫描」这种硬约束。6.2 从个人技能到团队资产个人技能和团队资产的区别在于可发现性和可维护性。个人技能你自己知道在哪、怎么用团队资产需要索引、文档、owner、review 流程。当你的技能从几个变成几十个就必须做这层建设否则新人根本不知道有哪些技能可用。我的做法是维护一个registry.yaml自动生成一份技能清单文档包含每个技能的名称、描述、触发条件、owner。这份文档随代码更新新人 clone 下来就能看到团队沉淀了哪些能力。这比口头传授高效得多也是 agent-skills 作为团队资产的核心价值。6.3 技能与项目演进的同步项目会演进技能也要跟着变。我见过技能和实际代码脱节的情况技能里写的测试框架项目早就不用了agent 还按老框架写测试结果跑不起来。避免这个问题的方法是把技能纳入 CI每次构建时检查技能里引用的配置和路径是否还存在不存在就报警。这个检查脚本不难写核心是解析技能里的配置引用验证对应文件或依赖是否存在。加上这一步技能就不会悄悄腐烂。我现在的项目里技能检查和单元测试一样是构建流程的一部分。6.4 面向不同技术栈的技能适配同一个流程在不同技术栈下细节不同。TDD 在 JavaScript 项目和 Python 项目里的写法就有差异。我的处理方式是技能逻辑和技术细节分离SKILL.md 写通用流程技术细节放adapters/目录按技术栈分文件。agent 加载时根据项目类型选对应 adapter。这样一套 TDD 技能能覆盖多个技术栈维护成本大幅降低。新增技术栈时只加一个 adapter 文件不动主逻辑。这个设计我在多技术栈项目里验证过效果很好推荐给有类似需求的团队。7. 我个人的一些实践体会agent-skills 这东西刚接触时容易低估它觉得不就是几个 Markdown 文件用久了又容易高估它觉得什么都能写成技能。我的体会是它的价值边界很清晰凡是「怎么做」稳定、「做什么」多变的场景都适合写成技能。反过来「做什么」本身就很复杂的任务写成技能反而添乱不如老老实实在对话里描述。还有一个体会是关于投入产出。写第一个技能时你会觉得麻烦收益不明显写到第五个、第十个复利效应就出来了。因为技能之间可以复用配置、复用结构、复用触发逻辑边际成本越来越低。所以我的建议是先写三个高频技能把 TDD、code review、commit 规范这三个跑通你会立刻感受到差别。最后说个心态问题。技能不是写完就完事的它需要持续维护。把它当成代码的一部分而不是一次性文档你才能长期受益。我现在的习惯是每次发现 agent 在某类任务上表现不好第一反应不是改 prompt而是想「是不是该加个技能或者改个技能」。这个思维转变是我用 agent-skills 最大的收获。