1. 从“装了一堆技能却用不起来”说起如果你最近在折腾 AI coding agents大概率会遇到一个很尴尬的局面模型本身能力不差但一到具体项目里就开始“犯迷糊”——不知道你的代码规范、不熟悉你的目录结构、写测试的方式跟你团队完全对不上。你反复在对话里贴规范、贴示例下一次开新会话又得重来一遍。这种重复劳动本质上不是模型的问题而是技能没有沉淀成可复用的资产。agent-skills这个项目要解决的就是这件事。它把“怎么让 AI coding agent 按你的方式干活”这件事从一次性对话提示变成了一套可安装、可版本管理、可组合的技能包体系。配套的skills CLI让你像装 npm 包一样把技能装进 Claude Code 这类 agent 环境里按需启用。再叠加test-driven-development这类具体技能agent 就能在写代码前先写测试、跑测试、再改实现形成闭环。这篇内容适合三类人看一是刚接触 Claude Code、还在纠结安装和配置的入门用户二是已经在用 agent 写代码、但被“每次都要重新交代背景”折磨的开发者三是想把团队规范固化进 agent 工作流的 Tech Lead。我会从设计思路讲到实操落地把技能包的目录结构、CLI 的安装逻辑、TDD 技能的具体运作方式以及我踩过的坑全部摊开讲清楚。读完你至少能做到自己写一个技能包装进 agent并让它稳定生效。2. agent-skills 到底在解决什么问题2.1 传统提示词工程的三个死穴先说清楚痛点不然很难理解这套东西的价值。我们平时用 AI coding agent最常见的做法是在对话里写一段“你是一个资深工程师请遵循以下规范……”。这种做法有三个绕不过去的死穴。第一个是不可复用。你在这个项目里写的规范换个项目就得重写。哪怕两个项目用的是同一套技术栈你也得复制粘贴一遍而且很容易漏掉几条。第二个是不可版本管理。规范写在对话里改了什么、什么时候改的、为什么改全都没有记录。团队里三个人用三套说法agent 的输出自然飘忽不定。第三个是不可组合。你既想让 agent 遵守代码规范又想让它用 TDD 流程还想让它按你的 commit message 格式提交这些需求堆在一段提示里模型很容易顾此失彼。agent-skills的思路是把这些规范拆成独立的“技能单元”每个技能只负责一件事通过 CLI 安装到 agent 的技能目录里。agent 在运行时按需加载互不干扰。这跟微服务拆分的逻辑是一样的单一职责、独立部署、按需组合。2.2 技能包与普通提示词的本质区别很多人第一反应是“这不就是把提示词存成文件吗”。表面看是这样但本质区别在于加载时机和触发机制。普通提示词是你手动贴进去的agent 被动接收。而技能包通常带有元数据比如技能名称、描述、适用场景、触发条件。agent 在接到任务时会先判断“这个任务需不需要调用某个技能”需要才加载对应的技能内容。这就避免了把所有规范一股脑塞进上下文导致的 token 浪费和注意力稀释。举个具体例子。你装了一个test-driven-development技能它的描述里写着“当用户要求实现新功能或修复 bug 时使用”。那么当你让 agent 写一个新函数时它会自动加载这个技能按照“先写失败测试、再写实现、再重构”的流程走。而当你只是让它解释一段代码时这个技能不会被加载上下文保持干净。这种按需加载是技能包相比裸提示词最大的工程优势。2.3 为什么是 Claude Code 这类 agent 先受益技能包这套机制对 agent 环境的成熟度有要求。它需要 agent 支持读取本地技能目录、解析技能元数据、在运行时动态加载。Claude Code 这类工具恰好提供了这种扩展能力所以agent-skills和skills CLI优先适配了它。这里要提醒一句不同 agent 对技能目录的约定不一样。有的放在项目根目录的隐藏文件夹里有的放在用户主目录的全局配置里。安装前一定要确认你的 agent 版本支持哪种路径否则技能装了也不生效。这个坑我在后面会详细讲。3. 技能包的目录结构与核心机制3.1 一个技能包的最小构成要理解agent-skills得先看懂一个技能包长什么样。基于常见实践一个最小可用的技能包通常包含这几个部分技能主文件一般是 Markdown 格式写清楚这个技能要 agent 做什么、遵循什么流程、有哪些约束。元数据文件描述技能的名称、版本、适用场景、触发关键词。有些实现会把它写在主文件的头部用类似 frontmatter 的格式。辅助资源比如代码模板、示例文件、检查清单。这些不是必须的但能让技能更“厚实”。我建议新手从单文件技能开始把元数据写在文件头部先跑通流程再考虑拆分成多文件结构。一上来就搞复杂目录很容易在路径引用上翻车。3.2 技能是如何被 agent 发现和加载的这里讲一下底层逻辑理解了它你就能自己排查“技能为什么不生效”。agent 启动时会扫描约定的技能目录。扫描到每个技能后读取元数据建立一个“技能索引”。这个索引里通常只有名称和描述不包含技能正文。当你的请求进来agent 拿请求内容跟索引里的描述做匹配判断哪些技能相关。匹配上的技能才会把正文加载进上下文。所以有两个关键点描述写得准不准决定了技能能不能被正确触发正文写得精不精决定了触发后 agent 干得好不好。很多人技能不生效问题就出在描述太模糊比如只写“代码相关”agent 根本判断不出什么时候该用。3.3 技能之间的组合与优先级实际项目里你往往需要多个技能同时生效。比如写一个新功能既要 TDD 技能管流程又要代码规范技能管风格还要 commit 技能管提交格式。这时候就涉及组合和优先级。常见做法是给技能设置优先级或者依赖关系。流程类技能如 TDD优先级高因为它决定了大方向风格类技能优先级低作为补充约束。如果两个技能冲突比如一个说“函数不超过 20 行”另一个说“禁止拆分函数”那 agent 就会犯难。所以写技能时要避免跟其他技能产生硬冲突把约束写成“建议”而非“强制”给 agent 留出判断空间。提示技能不是越多越好。装太多技能会让 agent 的匹配负担变重反而降低准确率。我的经验是单个项目常驻技能控制在 5 个以内其余按需临时启用。4. skills CLI 安装与 Claude Code 环境配置实操4.1 安装前的环境确认清单在动手之前先把环境确认清楚能省掉后面一大堆报错。你需要确认这几件事检查项确认内容常见问题Agent 版本是否支持技能目录扩展老版本可能不识别技能路径运行环境Node.js 或对应运行时是否就绪CLI 通常依赖 Node 环境目录权限技能目录是否可写全局目录常因权限写入失败网络环境能否正常拉取技能包依赖源不通会导致安装中断我见过最多的情况是目录权限问题。全局技能目录在类 Unix 系统下往往需要提权才能写入但很多人直接用普通权限跑安装命令结果技能文件写了一半就失败agent 扫描到残缺文件直接报错。建议先手动确认目录可写再执行安装。4.2 skills CLI 的安装与初始化skills CLI是管理技能包的命令行工具核心命令就那么几个安装、列出、启用、禁用、卸载。安装方式通常是通过包管理器全局安装然后在项目里初始化。# 全局安装 skills CLI以 Node 生态为例 npm install -g skills-cli # 在项目目录初始化技能配置 skills init # 查看当前已安装的技能 skills list # 安装一个技能包 skills install test-driven-development # 启用某个技能 skills enable test-driven-development初始化的作用是生成技能目录和配置文件。这一步做完你的项目里会多出一个技能存放目录agent 启动时就会去扫描它。如果你用的是全局技能初始化时可以选择写到用户主目录这样所有项目都能共享。4.3 Claude Code 侧的配置要点技能装好了还得让 Claude Code 知道去哪找。这一步是新手最容易卡住的地方。配置的核心是告诉 agent 技能目录的路径。在 Claude Code 的配置文件里通常需要指定技能目录的位置。如果你用的是项目级技能路径指向项目内的技能文件夹如果是全局技能指向用户主目录下的配置目录。配置改完记得重启 agent否则不会重新扫描。{ skills: { directory: ./.agent-skills, autoLoad: true } }autoLoad这个开关很关键。打开后 agent 会自动扫描并匹配技能关掉的话就得手动指定加载哪个技能。日常开发建议打开调试技能时再关掉避免干扰。4.4 验证技能是否真正生效装完别急着用先验证。最简单的办法是给 agent 一个明确会触发技能的任务观察它的行为是否符合技能定义。比如装了 TDD 技能后让它写一个简单函数看它是不是先写测试。如果行为不对按这个顺序排查技能目录路径对不对、元数据描述是否匹配任务、技能是否处于启用状态、agent 是否重启过。这四步能解决九成的“技能不生效”问题。注意有些 agent 会缓存技能索引改了技能内容后不重启不生效。调试阶段养成“改完就重启”的习惯能少走很多弯路。5. 以 test-driven-development 技能为例的完整落地5.1 TDD 技能的核心流程设计test-driven-development是agent-skills里最值得先装的技能之一因为它把一套成熟工程实践固化成了 agent 的默认行为。它的核心流程就是经典的红-绿-重构三步红先写一个会失败的测试明确要实现的预期行为。绿写最少的实现代码让测试通过不追求优雅。重构在测试保护下优化代码结构保持测试全绿。技能文件里会把这套流程写成明确的指令并附上约束比如“禁止在测试通过前写实现代码”“每次只处理一个测试用例”。这些约束是 TDD 能真正跑起来的关键因为模型天然倾向于一次性把实现和测试都写完那就失去 TDD 的意义了。5.2 技能文件里应该写什么基于常见实践一个 TDD 技能文件大致包含这几块内容触发条件明确什么时候用这个技能比如“实现新功能、修复 bug、重构现有代码”。执行步骤把红绿重构拆成 agent 可执行的动作序列。约束与禁忌列出不允许的行为比如跳过测试、一次写多个测试。输出格式规定 agent 每步要汇报什么方便你跟踪进度。写技能文件有个诀窍用命令式短句别用描述性长句。模型对“先写测试”这种指令的执行度远高于“建议采用测试先行的方式”。指令越直接行为越稳定。5.3 一次完整的 TDD 实操记录我拿一个真实场景走一遍。需求是写一个函数判断字符串是不是回文。第一步agent 加载 TDD 技能后先输出测试代码def test_is_palindrome(): assert is_palindrome(racecar) is True assert is_palindrome(hello) is False assert is_palindrome() is True此时is_palindrome还不存在测试必然失败这就是“红”。第二步agent 写最简实现def is_palindrome(s): return s s[::-1]跑测试全绿。注意它没有加任何额外功能没有处理大小写、没有去空格因为测试没要求。这就是“绿”阶段该有的克制。第三步如果后续需求增加比如要忽略大小写那就先加一个失败测试再改实现。整个循环由测试驱动而不是由 agent 的“我觉得应该这样”驱动。5.4 让 TDD 技能稳定生效的三个技巧第一个技巧是把测试命令写进技能。agent 写完测试后需要自己跑如果它不知道用什么命令跑测试流程就断了。在技能里明确写“使用 pytest 运行测试”或“使用 npm test”能大幅提升稳定性。第二个技巧是限制单次任务粒度。TDD 最怕 agent 一口气写十个测试再写一堆实现。在技能里加一条“每次只处理一个测试用例通过后再进行下一个”能强制它慢下来。第三个技巧是要求 agent 汇报测试结果。让它每跑一次测试就贴出输出你能实时看到红绿状态也方便在它“假装测试通过”时及时纠正。模型偶尔会跳过实际执行直接说通过这个约束能有效遏制。6. 常见问题与排查技巧实录6.1 技能装了但 agent 完全没反应这是最高频的问题。排查顺序我整理成了一张表现象可能原因解决方式技能列表里看不到安装路径不对确认安装目录与配置一致列表能看到但不触发描述不匹配任务优化技能描述关键词触发了一次后续不触发索引缓存未刷新重启 agent部分技能生效部分不生效技能间冲突检查约束是否矛盾我遇到过一次特别隐蔽的情况技能目录路径里带了空格配置解析时被截断导致 agent 扫描了一个不存在的目录。这种问题看日志才能发现所以养成看 agent 启动日志的习惯很重要。6.2 技能之间互相打架怎么办多个技能同时生效时冲突几乎不可避免。比如代码规范技能要求“函数必须写类型注解”而某个快速原型技能说“优先保证速度可省略注解”。agent 夹在中间就会摇摆。解决办法是分层。把技能分成流程层和风格层流程层优先级高风格层作为默认建议。在风格层技能里加一句“当与其他技能冲突时以流程层技能为准”给 agent 一个明确的裁决规则。另外能合并的技能尽量合并减少冲突面。6.3 技能更新后行为变了技能是活的你会不断迭代它。但更新后 agent 行为突变往往是因为改动影响了触发匹配或流程约束。我的做法是给技能加版本号每次改动记录变更点。出问题时能快速回滚到上一个稳定版本。还有个小坑如果你用的是全局技能更新后所有项目都会受影响。所以重大改动前先在单个项目里用项目级技能验证确认没问题再推到全局。6.4 关于模型接入的一些现实问题很多人关心能不能用第三方模型跑这套技能体系。从机制上讲技能包本质是文本资源和加载逻辑跟底层模型是解耦的。只要 agent 环境支持技能目录扫描换模型不影响技能生效。但要注意不同模型对指令的遵循度差异很大。同一份 TDD 技能在遵循度高的模型上能严格走红绿重构在遵循度低的模型上可能直接跳过测试。所以换模型后建议重新验证核心技能的行为别默认它还能按老样子工作。技能写得越明确、约束越硬跨模型的稳定性就越好。7. 自己动手写一个技能包的完整方法7.1 从重复劳动里找技能选题写技能包的第一步不是写代码是找选题。方法很简单回顾你最近一周跟 agent 的对话哪些话你重复说了三遍以上那些就是最该固化成技能的内容。常见的选题方向有代码风格规范、提交信息格式、测试流程、文档模板、review 检查清单、特定框架的用法约定。选题的原则是高频且明确。如果一个需求你自己都说不清楚那写成技能也是模糊的agent 执行起来照样飘。7.2 技能文件的写作模板我总结了一个通用模板你可以直接套--- name: 技能名称 description: 一句话说明什么时候用这个技能 version: 1.0.0 --- ## 目标 这个技能要达成什么。 ## 执行步骤 1. 第一步做什么 2. 第二步做什么 ## 约束 - 不允许做什么 - 必须做什么 ## 输出要求 每步要汇报什么内容。description是最关键的一行它决定触发匹配。写法是“当……时使用”把触发场景写具体。比如“当需要为新功能编写测试时使用”比“测试相关”强太多。7.3 技能调试与迭代的实操心得技能写完不是终点是起点。第一版几乎不可能完美得靠实际使用来打磨。我的迭代节奏是先用一周记录每次 agent 行为不符合预期的地方周末集中改一版。调试时有个技巧把技能里的约束一条条单独测试。比如你写了“禁止跳过测试”那就故意给一个容易让 agent 偷懒的任务看它会不会违反。逐条验证比整体感觉靠谱得多。另外技能描述里的关键词要跟你的实际用词对齐。你平时说“写单测”技能描述里就别只写“单元测试”把常见说法都覆盖进去匹配率会明显提升。8. 技能体系的扩展与团队协作8.1 把团队规范沉淀成共享技能个人用技能包已经能省不少事团队用价值更大。做法是把团队共识的规范写成技能放进共享仓库成员通过 CLI 安装。这样新人入职第一天agent 就已经懂团队规矩了不用口口相传。团队技能要特别注意共识性。别把某个人的个人偏好写成团队技能否则会引起抵触。建议先在小范围试用收集反馈稳定后再推广。技能仓库也要有 review 机制改动走 PR保证质量。8.2 技能版本管理与分发技能多了以后版本管理就成了刚需。建议给技能仓库打 tagCLI 安装时支持指定版本。这样某个技能更新出问题时团队可以锁定旧版本不影响日常开发。分发方式上小团队直接共享仓库地址就行规模大了可以考虑私有 registry但别过度工程化。我见过团队为了技能分发搞了一套复杂系统结果维护成本比技能本身还高得不偿失。8.3 技能体系的边界与注意事项最后说几个边界问题。技能包不是万能的它擅长固化明确的、可重复的工作流但不擅长处理需要大量上下文判断的模糊任务。别指望一个技能解决所有问题。还有技能内容里不要放敏感信息比如内部密钥、私有地址。技能文件会被加载进上下文等于把这些信息暴露给了模型。团队技能尤其要注意这点提交前过一遍敏感信息检查。我个人在实际操作中的体会是技能体系最大的价值不在于让 agent 变聪明而在于让它的行为可预期、可复现。当 agent 的输出稳定了你才敢把它真正接进生产流程。从装第一个 TDD 技能开始慢慢积累属于你自己的技能库这件事的复利效应会超出你的预期。