1. 从 agent-skills 说起为什么它值得每个 AI 编码玩家认真研究第一次看到agent-skills这个项目名的时候我下意识以为又是一个把提示词打包成 JSON 的小工具。真正把仓库拉下来跑了一遍之后才发现它想解决的问题比提示词管理要底层得多——它试图给 AI coding agents 建立一套可复用、可组合、可测试的技能体系让 Claude Code 这类工具从每次都要重新交代一遍规矩变成加载技能包就能干活。说白了agent-skills是一套围绕skills CLI构建的技能管理方案。它把让 AI 写代码这件事拆成一个个独立的技能单元每个技能有自己的触发条件、执行流程、验证标准然后通过命令行工具统一安装、切换、组合。配合Claude Code使用的时候你能明显感觉到 agent 的行为变得更稳定——不是那种这次回答得不错下次就飘了的随机感而是有一套明确的规则在约束它。这个项目适合谁三类人最该看一是已经在用 Claude Code 但总觉得输出质量忽高忽低的开发者二是想把 AI 编码能力接入团队工作流、需要标准化流程的技术负责人三是对test-driven-development和 AI 结合感兴趣、想看看让 agent 自己写测试再写实现到底靠不靠谱的工程师。哪怕你只是刚装完 Claude Code 的新手理解这套技能体系也能帮你少走很多弯路。我下面会从设计思路、核心机制、实操流程、踩坑记录四个维度把agent-skills拆开讲。所有涉及具体配置和命令的地方我都会给出可直接复制的方案同时说明每一步为什么这么做。文中提到的 Claude Code 安装、VS Code 配置、第三方模型接入等内容都是围绕 agent-skills 的实际使用场景展开的不是泛泛而谈的教程。2. agent-skills 的整体设计与思路拆解2.1 为什么需要技能这层抽象大部分人用 Claude Code 的方式是这样的打开终端输入一段需求描述等它生成代码不满意就补充说明来回几轮。这种方式在单次任务里没问题但一旦任务变复杂、或者你需要反复做同类事情问题就暴露了——每次都要重新描述上下文每次都要重新纠正 agent 的坏习惯效率极低。agent-skills的核心洞察是AI 编码 agent 的能力不应该靠每次对话临时塑造而应该靠预定义的技能模块来驱动。一个技能就是一个自包含的指令包里面写清楚了什么时候触发这个技能执行时遵循什么步骤产出物要满足什么标准。Agent 加载技能之后行为就有了锚点。这个思路其实借鉴了软件工程里的关注点分离原则。你把怎么写测试怎么做代码审查怎么处理数据库迁移这些关注点分别封装成技能agent 在执行任务时按需加载而不是把所有规则一股脑塞进系统提示词里。好处很明显技能可以独立迭代可以组合使用可以在不同项目之间复用。2.2 skills CLI 的设计取舍agent-skills提供的skills CLI是整个方案的操作入口。我研究了一下它的命令设计发现几个有意思的取舍。第一它没有做成配置文件驱动的模式而是坚持命令行交互。这意味着你可以在终端里快速切换技能不需要手动编辑 YAML 或 JSON。对于已经习惯在终端里工作的开发者来说这个选择降低了心智负担。第二技能的组织方式是扁平化的目录结构每个技能一个文件夹里面包含技能定义文件和可选的辅助资源。这种设计的好处是透明——你随时可以打开某个技能看看它到底写了什么不需要解析复杂的继承关系。第三它没有内置技能市场或远程仓库的概念技能来源完全由你自己控制。这个取舍在安全性和灵活性之间偏向了前者。考虑到 AI 编码 agent 会直接操作你的代码库技能内容如果来自不可信来源风险是实打实的。提示如果你打算在团队里推广 agent-skills建议把技能目录纳入版本控制让每次技能变更都有记录可追溯。这一点比技能本身写得多漂亮更重要。2.3 与 Claude Code 的协作模式agent-skills和Claude Code的关系可以理解为技能库和执行引擎的关系。Claude Code 负责理解你的自然语言指令、调用工具、生成代码agent-skills 负责告诉 Claude Code在这个场景下应该遵循什么流程。具体协作方式是这样的你在项目根目录下配置好技能目录Claude Code 启动时会读取这些技能定义。当你发出一个任务指令时agent 会根据技能里定义的触发条件判断该加载哪些技能。比如你说帮我给这个函数补测试如果存在一个叫tdd-workflow的技能它的触发条件里包含测试test等关键词agent 就会自动加载这个技能然后按照技能里定义的步骤执行——先分析函数签名再生成测试用例再运行测试验证最后根据失败结果调整。这种模式比在系统提示词里写一大段规则要灵活得多。系统提示词是全局的、静态的而技能是按需加载的、可组合的。你可以同时加载测试驱动开发和代码风格检查两个技能agent 会在生成测试时同时考虑两个技能的约束。2.4 技能的生命周期管理一个技能从创建到废弃大致经历这几个阶段定义、测试、使用、迭代、归档。agent-skills在定义和测试这两个环节提供了比较明确的支撑。定义阶段你需要写清楚技能的元信息名称、描述、触发条件和执行指令步骤、约束、输出格式。测试阶段你可以用一些典型任务来验证技能是否按预期工作。我自己的做法是给每个技能准备三到五个测试用例覆盖正常场景和边界场景每次修改技能后跑一遍。使用阶段就是日常开发中让 agent 加载技能干活。迭代阶段是根据实际使用反馈调整技能内容——这一步最容易被忽略但恰恰是技能体系能否持续产生价值的关键。归档阶段是把不再适用的技能移出活跃目录避免 agent 加载到过时规则。3. 核心细节解析与实操要点3.1 技能定义文件的结构一个典型的技能定义文件包含几个部分元信息区、触发条件区、执行指令区、验证标准区。我用一个实际例子来说明。假设你要创建一个Python 函数测试生成技能元信息区写技能名称和一句话描述触发条件区写什么情况下加载这个技能比如用户提到测试pytest单元测试等关键词或者当前操作的文件是.py结尾且包含函数定义执行指令区写具体步骤比如先读取目标函数分析参数和返回值再生成对应的 pytest 测试用例覆盖正常输入、边界输入、异常输入三类场景验证标准区写生成的测试必须能直接运行且至少覆盖函数的所有分支。这种结构的价值在于它把模糊的期望变成了明确的检查项。Agent 执行完之后你可以对照验证标准判断它是否真的完成了任务而不是凭感觉说好像还行。3.2 触发条件的写法与常见误区触发条件是技能设计里最容易出问题的地方。写得太宽泛技能会在不该加载的时候加载干扰 agent 的正常判断写得太窄技能又经常该加载时不加载形同虚设。我踩过的坑是这样的一开始我把某个技能的触发条件写成用户提到代码相关的内容结果几乎每次对话都会加载这个技能agent 变得非常啰嗦什么简单问题都要走一遍完整流程。后来我把触发条件收窄到用户明确要求生成测试或当前文件包含未测试的函数情况就好多了。一个实用的经验是触发条件里尽量包含具体的动作词和对象词。测试是动作词函数是对象词两者组合起来就能比较准确地定位场景。避免使用代码开发编程这类过于宽泛的词。另外触发条件支持组合逻辑。你可以写当用户提到测试 AND 当前文件是 Python 文件才加载这样精度更高。但也不要组合太多条件否则技能会变得很难触发。3.3 执行指令的粒度控制执行指令写多细是个需要权衡的问题。写得太粗agent 自由发挥的空间太大输出不稳定写得太细又变成了硬编码流程失去了 AI 的灵活性。我的建议是关键决策点写细执行细节写粗。比如先分析函数签名再生成测试这个顺序要写清楚因为顺序错了结果就错了但用什么方式分析函数签名可以留给 agent 自己决定它可能用 AST 解析也可能直接读代码只要结果对就行。还有一个技巧是使用检查点机制。在技能里定义几个关键检查点agent 每完成一个阶段就自我检查一次。比如生成测试用例后检查是否覆盖了所有参数运行测试后检查是否有失败用例。这种机制能显著降低 agent 跑偏的概率。3.4 技能组合时的冲突处理当你同时加载多个技能时可能会遇到指令冲突。比如技能 A 说生成代码后立即运行测试技能 B 说生成代码后先做代码审查再运行测试。这时候 agent 该听谁的agent-skills的处理方式是给技能设置优先级。优先级高的技能指令会覆盖优先级低的。但我的经验是与其依赖优先级机制不如在设计技能时就避免冲突。具体做法是让每个技能只负责一个明确的关注点不要在一个技能里塞太多职责。测试技能就只管测试代码审查技能就只管审查两者通过执行顺序来协调而不是通过指令覆盖来协调。你可以在技能定义里声明依赖关系比如代码审查技能应该在测试技能之前执行这样 agent 就知道先做什么后做什么。3.5 验证标准的可操作性验证标准如果写得太模糊比如代码质量要好那等于没写。好的验证标准应该是可操作、可检查的。我通常从三个维度来写验证标准功能性是否完成了预期功能、完整性是否覆盖了所有要求、一致性是否符合项目既有规范。每个维度下写具体的检查项。以测试生成技能为例功能性检查项是测试能运行且通过完整性检查项是每个函数至少有一个测试用例一致性检查项是测试文件命名和目录结构符合项目惯例。这样 agent 执行完之后你可以逐项核对而不是笼统地说感觉不太行。4. 实操过程与核心环节实现4.1 环境准备从零开始搭建假设你现在什么都没装我带你走一遍完整流程。这套流程在 macOS 和 Ubuntu 上都验证过Windows 用户建议用 WSL。第一步是安装 Claude Code。官方提供了多种安装方式我推荐用 npm 全局安装因为后续升级方便。命令是npm install -g anthropic-ai/claude-code。装完之后运行claude --version确认版本。如果你在 Ubuntu 上遇到权限问题在命令前加sudo或者配置 npm 的全局目录到用户空间。第二步是配置 Claude Code。首次运行claude会引导你完成初始化包括选择模型、配置 API 密钥等。如果你用的是第三方 API 接入方案比如通过 cc switch 接入 DeepSeek、Qwen、GLM 等模型需要在配置里指定对应的 base URL 和模型名称。这一步的具体配置取决于你用的服务商核心是确保 Claude Code 能正常发起请求并收到响应。第三步是安装 agent-skills。把仓库克隆到本地然后按照 README 里的说明运行安装脚本。安装脚本会把 skills CLI 注册到你的 PATH 里之后你就可以在任何目录下使用skills命令了。第四步是初始化技能目录。在你的项目根目录下运行skills init它会创建一个.agent-skills目录里面包含示例技能和配置文件。你可以直接使用示例技能也可以自己写新的。4.2 编写第一个技能从需求到落地我们来写一个实际有用的技能提交前检查。这个技能的作用是当你准备提交代码时agent 自动帮你做一轮检查包括代码风格、测试覆盖、提交信息规范。首先创建技能目录skills create pre-commit-check。然后在生成的技能定义文件里填写内容。元信息部分名称写提交前检查描述写在代码提交前执行自动化检查确保代码质量和提交规范。触发条件部分写当用户提到提交、commit、push 等关键词或者用户明确要求执行提交前检查时加载。执行指令部分分四步写。第一步运行项目的代码风格检查工具根据项目配置可能是 ESLint、Pylint、gofmt 等。第二步运行测试套件确认所有测试通过。第三步检查提交信息是否符合规范比如是否包含类型前缀、是否超过长度限制。第四步汇总检查结果如果有问题就列出具体问题和修复建议。验证标准部分写所有检查项都有明确的通过或失败结论失败项附带可操作的修复建议。写完之后用skills validate pre-commit-check验证技能定义文件格式是否正确。然后就可以在 Claude Code 里测试了。4.3 技能加载与执行的现场记录我在一个 Python 项目里实测了这个技能。项目结构是标准的 src 布局测试用 pytest代码风格用 ruff 检查。我在 Claude Code 里输入帮我检查一下当前改动准备提交。Agent 识别到提交这个关键词自动加载了 pre-commit-check 技能。然后它依次执行了以下操作先运行ruff check .发现两个未使用的导入和一个行长度超限。Agent 把这些问题列出来并给出了修复建议——删除未使用的导入把超长行拆分成多行。然后运行pytest所有测试通过。Agent 报告测试套件全部通过共 47 个测试用例。接着检查 git 提交信息。因为我还没写提交信息agent 提示我提供并给出了符合规范的示例格式。最后汇总两个代码风格问题需要修复测试通过提交信息待填写。整个流程大概花了十几秒比我手动逐个运行检查工具快得多而且不会漏项。4.4 参数计算与选择过程在配置技能的时候有几个参数需要你根据项目情况做选择。我拿测试覆盖率阈值来举例说明计算过程。假设你的项目有 200 个函数当前测试覆盖了 150 个覆盖率是 75%。如果你把技能的覆盖率检查阈值设为 80%那每次提交都会失败因为当前达不到。这时候你有两个选择要么先把覆盖率提上去再启用检查要么把阈值设为 75% 并逐步提高。我的做法是设置一个渐进式阈值当前覆盖率是 75%那阈值就设为 75%但技能里加一条规则——每次提交覆盖率不得低于上次提交。这样覆盖率只能升不能降慢慢就提上去了。这个规则用脚本实现很简单把上次的覆盖率记录在一个文件里每次检查时对比即可。类似地代码风格检查的严格程度、测试运行超时时间、提交信息长度限制这些参数都需要根据项目实际情况来定。没有万能值关键是让检查规则既能发现问题又不会频繁误报导致大家想绕过它。4.5 与 VS Code 的集成配置虽然 Claude Code 主要在终端里使用但和 VS Code 集成之后体验会更好。配置方式是在 VS Code 里安装 Claude Code 插件然后在设置里指定 Claude Code 的可执行文件路径。集成之后的好处是你可以在 VS Code 的终端面板里直接使用 Claude Code同时享受编辑器的文件浏览和 diff 查看功能。当 agent 修改了多个文件时你可以在 VS Code 里逐个查看变更决定接受还是拒绝。如果你用的是远程开发模式比如通过 SSH 连接到 Ubuntu 服务器需要在远程环境里也安装 Claude Code 和 agent-skills。配置方式和本地一样只是路径要对应远程环境。注意VS Code 插件和终端版本的 Claude Code 共享同一套配置。如果你在终端里改了模型配置插件里也会生效。反过来也一样。所以改配置的时候要意识到影响范围。5. 常见问题与排查技巧实录5.1 技能不生效的排查思路技能不生效是最常见的问题。表现是你明明写了技能agent 执行任务时却完全没按技能里的流程走。排查顺序是这样的。第一确认技能目录位置正确。skillsCLI 默认在当前目录和父目录里查找.agent-skills目录如果你的技能放在别的地方需要在配置里指定路径。第二确认技能定义文件格式正确。运行skills validate检查它会告诉你具体哪里有问题。第三确认触发条件能匹配上。你可以用skills test-trigger命令模拟一个输入看看哪些技能会被触发。第四确认技能没有被禁用。skills list会显示所有技能及其状态。我遇到过一次技能不生效的情况排查了半天发现是技能定义文件里的缩进用了 Tab 而不是空格导致解析失败。这种问题很隐蔽因为文件看起来是正常的。所以写完技能后一定要跑一遍 validate。5.2 技能冲突导致行为异常当你加载了多个技能agent 的行为变得奇怪时很可能是技能冲突了。表现包括agent 反复执行同一个步骤、忽略某些指令、输出格式混乱。解决方法是逐个禁用技能定位冲突源。skills disable 技能名可以临时禁用一个技能。找到冲突的两个技能后要么调整它们的优先级要么修改指令消除冲突。我个人的经验是技能数量控制在五个以内比较稳妥。超过五个之后冲突概率显著上升而且 agent 的响应速度也会变慢因为它要处理更多的指令。如果你确实需要很多技能考虑把它们分组按任务类型加载不同的技能组。5.3 第三方模型接入后的兼容性问题用 cc switch 接入 DeepSeek、Qwen、GLM 等第三方模型之后可能会遇到技能不按预期执行的问题。原因通常是不同模型对指令的遵循程度不一样。有些模型对结构化指令的解析能力较弱你写的技能步骤它可能理解偏了。应对方法是把技能指令写得更直白、更结构化。避免使用复杂的嵌套条件尽量用第一步做 A第二步做 B这种线性描述。如果某个模型实在不兼容可以在技能里针对不同模型写不同的指令分支但这会增加维护成本。另外要注意第三方模型的上下文窗口大小可能和官方模型不同。如果你的技能定义文件很长加上项目代码可能超出窗口限制。这时候需要精简技能内容或者把技能拆成更小的单元。5.4 常见问题速查表问题现象可能原因排查方法解决方案技能完全不生效目录位置错误或文件格式错误运行skills validate修正路径或格式技能偶尔生效触发条件太窄用skills test-trigger测试放宽触发条件Agent 行为混乱技能冲突逐个禁用技能定位调整优先级或修改指令响应速度变慢加载技能过多查看skills list精简技能数量第三方模型不遵循技能模型指令遵循能力弱换官方模型对比测试简化技能指令结构技能修改后不生效缓存未刷新重启 Claude Code清除缓存或重启5.5 几个容易被忽略的实操心得第一个心得技能定义文件也要做版本控制。我见过有人把技能放在本地不提交结果换台机器就没了。技能是项目资产的一部分应该和代码一起管理。第二个心得定期清理不再使用的技能。技能目录膨胀之后agent 加载和判断的开销都会增加。每个季度过一遍技能列表把过时的归档或删除。第三个心得给技能写变更日志。每次修改技能后在文件头部记一笔什么时候改了什么、为什么改。过几个月回头看你会感谢自己做了这件事。第四个心得不要试图用技能解决所有问题。有些问题适合用技能比如流程标准化有些问题不适合比如需要大量创造性判断的任务。技能的本质是约束约束太多反而会限制 agent 的能力发挥。6. 技能体系的扩展与长期维护6.1 从个人使用到团队协作一个人用 agent-skills 和团队用复杂度完全不是一个量级。个人使用时技能怎么写、怎么改都是你说了算。团队使用时你需要考虑技能的分发、版本对齐、权限控制。我的建议是建立一个技能仓库所有技能集中管理团队成员通过 git 拉取更新。技能仓库可以有多个分支稳定分支放经过验证的技能开发分支放试验性技能。团队成员默认使用稳定分支需要尝鲜时切换到开发分支。权限控制方面至少要区分能写技能和能用技能两种角色。不是每个人都适合写技能写技能需要对 agent 的行为模式有深入理解。但每个人都应该能用技能这是提升团队整体效率的关键。6.2 技能效果的量化评估怎么判断一个技能到底有没有用不能只凭感觉。我通常从三个指标来评估任务完成时间、返工率、输出一致性。任务完成时间是指从发出指令到得到满意结果的时间。如果一个技能让这个时间缩短了说明它有价值。返工率是指 agent 输出需要人工修改的比例。返工率下降说明技能提升了输出质量。输出一致性是指同类任务多次执行的结果差异程度。一致性高说明技能有效约束了 agent 的行为。这三个指标不需要很精确粗略对比就行。比如启用技能前后各做十次同类任务记录一下时间和返工次数就能看出效果。6.3 技能体系的演进方向从agent-skills目前的设计来看它还有不少可以演进的空间。比如技能之间的依赖关系管理可以更智能现在需要手动声明未来可能通过分析技能内容自动推断。再比如技能的测试框架可以更完善现在主要靠手动测试未来可能有自动化的技能测试工具。但这些都是工具层面的演进。更重要的演进发生在使用者的认知层面——当你真正理解了技能是约束 agent 行为的规则这个本质之后你会发现很多以前觉得棘手的问题都有了新的解法。比如代码审查以前是靠人盯现在可以写一个审查技能让 agent 先过一遍人只需要看 agent 标记出来的可疑点。6.4 我个人的使用体会用了几个月 agent-skills 之后最大的感受是它改变了我对 AI 编码工具的期待。以前我期待的是AI 能帮我写代码现在期待的是AI 能按照我定义的流程稳定地写代码。前者是能力问题后者是工程问题。能力问题靠模型进步解决工程问题靠技能体系解决。另一个体会是写技能的过程本身就是对工作流程的梳理。当你试图把怎么做代码审查写成一步步的指令时你会发现自己以前很多操作是凭直觉的没有明确的章法。写技能强迫你把这些直觉显性化这本身就是一种提升。最后分享一个小技巧如果你不确定某个技能该怎么写先手动做一遍任务把每一步操作和判断都记下来然后把这些记录整理成技能指令。这样写出来的技能最贴近实际工作流程也最容易验证效果。