1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个词是在翻 Claude Code 相关生态的时候。当时我的第一反应是这不就是把“提示词模板”换了个马甲吗但真正动手把它的结构拆开、跑通几个技能之后我意识到这个判断太草率了。agent-skills本质上是一套面向 AI coding agents 的能力封装规范它把“让 AI 干某件具体的事”这件事从散落在对话里的提示词变成了可版本管理、可复用、可组合的独立单元。说得再直白一点以前你用 Claude Code 写代码每次都要在对话里反复交代“帮我按 TDD 的方式写测试再写实现”“提交前跑一遍 lint”“生成 commit message 要符合规范”。这些交代本质上就是你的“技能”但它们只存在于你的记忆和聊天记录里。agent-skills要做的事情就是把这些技能抽出来做成一个个独立的文件夹里面放一份说明文档可能再配点脚本然后通过一个 skills CLI 把它们挂载到 agent 上。下次你只要说“用 TDD 技能处理这个需求”agent 就知道该按什么流程走。这套东西解决的核心痛点有三个。第一是一致性团队里每个人对“什么叫规范地写一个功能”理解不一样技能把流程固化下来输出就稳定了。第二是可维护性流程变了改技能文件就行不用去翻几十条历史对话。第三是可组合性一个技能可以调用另一个技能比如“代码审查”技能内部可以引用“安全检查”技能形成能力树。适合谁来参考这篇内容如果你已经在用 Claude Code、Cursor、Windsurf 这类 AI coding agent并且开始觉得“每次都要重复交代同一套流程很烦”那你就是目标读者。如果你还没入门只是想搞清楚 agent-skills 到底是个什么东西、值不值得投入时间这篇也会给你一个足够清晰的判断依据。下面我会从设计思路、核心结构、实操落地、踩坑排查几个层面把我在实际项目里跑通这套东西的经验完整摊开。2. agent-skills 的整体设计与思路拆解2.1 为什么不是“写更长的提示词”而是做技能封装很多人第一反应是我把要求写详细一点不就行了我一开始也这么干过。在 Claude Code 里写了一段将近两千字的“开发规范”每次开新会话就粘贴进去。前几次还行到第五次的时候问题就来了这段提示词开始和项目里的实际情况脱节我改了 lint 规则但忘了同步提示词结果 agent 按旧规则生成代码CI 直接挂掉。技能封装解决的正是这个“提示词漂移”问题。它的思路和软件工程里的“配置即代码”是一脉相承的把流程性的东西从对话上下文里抽离出来变成文件系统里的实体。这样做有几个直接好处。文件可以被 git 管理改动有 diff、有历史、可回滚。文件可以被 review团队里谁改了技能流程其他人能在 PR 里看到。文件可以被测试你可以写一个用例验证“调用这个技能后 agent 是否真的按预期产出了测试文件”。从 agent 的角度看技能本质上是一种按需加载的上下文。agent 平时不需要把所有技能都塞进上下文窗口那样既浪费 token 又容易干扰判断。只有当任务匹配到某个技能的触发条件时才把这份技能的说明加载进来。这个机制和 Claude Code 的 skills 设计是吻合的技能以文件夹形式存在每个文件夹里有一份SKILL.md作为入口说明agent 根据任务描述决定要不要读取。2.2 技能、工具、子代理三者到底怎么分工刚接触这套体系的人最容易混淆的就是技能skill、工具tool、子代理subagent这三个概念。我在项目里踩过这个坑一开始把什么都往技能里塞结果技能文件越写越臃肿agent 反而不知道该用哪个。我的理解是这样的。工具是原子能力比如读文件、写文件、执行终端命令、搜索代码库这些是 agent 的“手脚”你一般不需要自己造平台已经提供了。子代理是一个独立的执行单元有自己的上下文窗口和职责边界适合处理那种“需要大量探索、但结论很简短”的任务比如“在代码库里找出所有调用某个废弃 API 的地方”。技能则是介于两者之间的东西它是一套流程知识告诉 agent“面对这类任务应该按什么步骤、用什么工具、产出什么格式的结果”。举个具体例子。你要实现“给现有函数补单元测试”这件事。工具层面agent 需要读文件、写文件、跑测试命令。子代理层面你可以派一个子代理去分析这个函数的依赖和边界条件。技能层面你定义的是流程先读函数签名和实现识别分支和边界按 TDD 的红绿重构节奏先写失败测试再补实现最后跑覆盖率。这三者配合起来才是一个完整的“补测试”能力。提示不要试图用一个技能解决所有问题。技能粒度太粗agent 匹配时容易误触发粒度太细又会变成一堆碎片维护成本反而上升。我的经验是一个技能对应一类“有明确输入输出和固定流程”的任务比如“生成 commit message”“按 TDD 实现功能”“做代码审查”。2.3 目录结构设计一份技能长什么样技能在文件系统里的组织方式直接决定了它好不好维护。我试过几种结构最后稳定下来的方案是这样的skills/ tdd-workflow/ SKILL.md templates/ test-template.ts scripts/ check-coverage.sh commit-message/ SKILL.md code-review/ SKILL.md checklists/ security.md performance.md核心是每个技能一个独立文件夹文件夹名就是技能标识。SKILL.md是必须的入口文件里面写清楚这个技能是干什么的、什么时候触发、执行步骤是什么、产出什么。templates放模板文件scripts放辅助脚本checklists放检查清单。这种结构的优势在于技能是自包含的复制一个文件夹就能把技能迁移到另一个项目不依赖外部路径。SKILL.md的写法有讲究。我见过有人把它写成一篇散文agent 读起来抓不住重点。我的做法是用固定的几个段落一段简短的用途说明一段触发条件一段编号的执行步骤一段产出格式说明。触发条件尤其重要它决定了 agent 什么时候会想起这个技能。写得太宽泛比如“当需要写代码时”会导致技能被滥用写得太窄又可能永远不被触发。2.4 和 Claude Code 生态的衔接逻辑agent-skills这套东西之所以最近热度上来和 Claude Code 的普及有直接关系。Claude Code 本身提供了 skills 机制允许你把技能放在特定目录下agent 在需要时会自动读取。这就意味着你写的技能不是某个私有框架的方言而是能直接跑在主流 agent 上的通用资产。这里有个关键点值得说清楚技能的可移植性。因为技能本质上是 Markdown 加脚本它不绑定具体的模型。你今天用 Claude Code 跑明天换成别的支持类似机制的 agent技能文件大概率还能用。这种“资产不锁死”的特性是我愿意在技能上投入时间的重要原因。相比之下如果你把流程写死在某个平台的专有配置里迁移成本会高得多。从 skills CLI 的角度看它的作用主要是安装、列出、更新技能。你可以把它理解成技能包的管理器。团队协作时把技能仓库 clone 下来跑一条 CLI 命令把技能挂载到 agent 的技能目录所有人就共享同一套流程了。这个环节后面实操部分会详细展开。3. 核心细节解析与实操要点3.1 SKILL.md 的写法让 agent 一眼看懂SKILL.md是整个技能的灵魂写得好不好直接决定技能能不能被正确触发和执行。我前后改过十几版总结出一个比较稳的模板结构。开头用一句话说清楚这个技能做什么不要绕弯子。比如“按测试驱动开发流程实现一个新功能或修复一个 bug”。这句话会作为 agent 判断是否加载这个技能的重要依据所以要包含关键动作词。接着是触发条件段落。这里要写清楚“什么情况下用这个技能”。我的写法是列几个典型场景比如“用户要求新增功能且希望有测试覆盖”“用户要求修复 bug 并补充回归测试”。这样 agent 在解析任务时能更容易匹配上。然后是执行步骤用有序列表每一步都要具体到可操作。比如 TDD 技能的第一步是“阅读目标函数或模块的现有实现识别输入、输出和边界条件”而不是笼统的“理解需求”。步骤里要明确提到会用哪些工具比如“使用读文件工具查看现有测试文件的结构”。最后是产出说明写清楚执行完这个技能后应该得到什么。比如“一个失败的测试文件、一个通过测试的实现、一份覆盖率报告”。产出说明能帮助 agent 自我校验如果产出不符合预期它会倾向于重试或报错而不是糊弄过去。注意SKILL.md里不要写和具体项目强绑定的路径或变量。技能应该是可复用的项目相关的配置放到单独的配置文件里通过脚本读取。我见过有人把绝对路径写进技能结果换台机器就废了。3.2 触发条件的边界避免技能被误用和漏用触发条件是技能设计里最微妙的部分。写得太松agent 会在不相关的任务上也加载这个技能浪费上下文还干扰判断。写得太紧技能就成了摆设永远不被触发。我的经验是触发条件要同时包含“动作”和“对象”两个维度。只写动作比如“写测试”太宽泛只写对象比如“用户模块”又太具体。合起来写“当用户要求为现有函数补充单元测试时”就清晰多了。还有一个技巧是用“反例”来收窄边界。在触发条件里明确写“不适用于以下情况”比如“不适用于从零搭建测试框架”“不适用于端到端测试”。这样 agent 在边缘情况下会更有判断依据。我实测下来加了反例之后技能误触发的概率明显下降。另外多个技能之间的触发条件要避免重叠。如果你有两个技能都声称“处理代码审查”agent 就会犯难。解决办法是给技能分层比如一个叫“快速审查”负责风格和明显问题一个叫“深度审查”负责安全和性能触发条件里写清楚各自的适用场景。3.3 脚本与模板的配合把重复劳动交给机器技能里最容易被忽视、但价值最高的部分是配套的脚本和模板。纯文字说明只能告诉 agent“怎么做”脚本和模板能直接帮它“做掉一部分”。以 TDD 技能为例我在scripts里放了一个check-coverage.sh作用是跑完测试后检查覆盖率是否达标。技能的执行步骤里会写“运行 check-coverage.sh如果覆盖率低于阈值则补充测试”。这样 agent 不需要自己去解析覆盖率报告脚本直接给出结论效率和准确性都更高。模板文件的作用类似。templates/test-template.ts里放一个符合项目规范的测试骨架agent 生成测试时可以参考这个骨架产出的代码风格更统一。我对比过用模板和不用模板的产出用了模板之后测试文件的命名、describe 结构、断言风格都稳定多了review 成本明显降低。提示脚本要写得健壮考虑失败情况。比如覆盖率脚本在测试命令本身失败时应该输出明确的错误信息而不是静默返回。agent 拿到清晰的错误信息才能做出正确的下一步决策。3.4 版本管理与团队协作的衔接技能一旦进入团队协作场景版本管理就成了刚需。我的做法是把技能仓库单独建一个 git 仓库或者放在主仓库的一个独立目录下用 CODEOWNERS 指定负责人。每次改技能走正常的 PR 流程。PR 描述里要写清楚改了什么、为什么改、影响哪些技能。因为技能改动会直接影响 agent 的行为所以 review 的时候要特别关注触发条件和执行步骤的变化这些是最容易引入回归的地方。还有一个实践是给技能打标签。比如stable、beta、deprecated。团队里有人想试用新技能可以先用 beta 标签的稳定后再提升为 stable。deprecated 的技能保留一段时间给使用者迁移的缓冲期。这套机制听起来有点重但在多人协作的项目里它能避免“某人改了技能导致所有人 agent 行为突变”这种事故。4. 实操过程与核心环节实现4.1 环境准备把 skills CLI 跑起来动手之前先把环境理清楚。我是在 Ubuntu 上做的macOS 流程基本一致。前提是你已经装好了 Claude Code并且能正常在终端里调用它。如果你还没装官方文档里有安装指引这里不展开。skills CLI 的安装方式我采用的是从源码构建。先把技能仓库 clone 下来然后按仓库里的说明跑构建命令。构建完成后CLI 会提供一个可执行文件把它加到 PATH 里或者用绝对路径调用。git clone skills-repo-url cd skills-repo # 按仓库说明执行构建通常是 npm install npm run build export PATH$PWD/bin:$PATH skills --version跑通skills --version能看到版本号说明 CLI 可用了。这一步看起来简单但我第一次做的时候卡了半小时原因是 Node 版本不对。仓库要求 Node 18 以上我机器上是 16构建报了一堆看不懂的错。所以动手前先确认 Node 版本能省不少事。4.2 创建第一个技能从 commit-message 开始新手不要一上来就搞复杂的 TDD 技能容易受挫。我建议从commit-message这种小技能入手流程短、反馈快能帮你快速理解技能的工作机制。在技能目录下新建文件夹commit-message里面创建SKILL.md。内容大致如下# Commit Message 生成技能 ## 用途 根据当前 git 暂存区的改动生成符合 Conventional Commits 规范的提交信息。 ## 触发条件 - 用户要求生成 commit message - 用户要求提交代码但未提供提交信息 - 不适用于需要拆分多个提交的复杂改动 ## 执行步骤 1. 运行 git diff --staged 查看暂存区改动 2. 分析改动的类型feat、fix、refactor、docs、test、chore 3. 识别改动影响的范围scope 4. 用一句话概括改动内容不超过 72 字符 5. 如有必要在正文补充改动原因和影响 ## 产出格式 type(scope): subject body可选写完保存然后用 CLI 把这个技能挂载到 agent 的技能目录。挂载命令的具体形式取决于 CLI 的设计一般是skills link skill-name或skills install path。挂载完成后在 Claude Code 里说“帮我生成 commit message”观察 agent 是否读取了这个技能并按步骤执行。我第一次跑的时候agent 确实读了技能但生成的 message 格式不对把 scope 写成了文件路径。排查后发现是步骤 3 写得太模糊“识别改动影响的范围”没有给出判断依据。改成“根据改动涉及的主要模块或功能识别 scope优先使用项目已有的模块命名”之后产出就正常了。这个调试过程很典型技能不是一次写对的要根据实际产出反复打磨。4.3 TDD 技能的完整落地从红到绿到重构commit-message跑通之后可以挑战 TDD 技能了。这个技能的价值最高但实现也最复杂。我把它拆成三个阶段每个阶段在SKILL.md里都有明确的步骤和产出要求。红阶段agent 先读目标函数的现有实现识别输入、输出、边界条件和异常路径。然后写一个测试文件测试必须覆盖正常路径和至少两个边界情况。写完测试后运行确认测试失败。这一步的关键是“确认失败”很多 agent 会跳过这步直接写实现导致测试和实现一起写失去了 TDD 的意义。我在技能里明确写了“运行测试并确认失败如果测试通过则说明测试没有覆盖新功能需要重写测试”。绿阶段agent 写最少的实现代码让测试通过。这里要强调“最少”避免过度设计。技能里写“只实现让当前测试通过所需的代码不要提前实现未被测试覆盖的功能”。重构阶段测试通过后agent 检查实现代码是否有重复、命名是否清晰、结构是否合理在保持测试通过的前提下重构。重构完再跑一次测试确认。配套的check-coverage.sh脚本在绿阶段结束后运行检查覆盖率。脚本内容大致是跑测试命令解析覆盖率输出和阈值比较。阈值我设的是 80%低于这个值 agent 需要补充测试。#!/bin/bash # check-coverage.sh THRESHOLD80 # 运行测试并生成覆盖率报告具体命令依项目而定 npm test -- --coverage coverage-output.txt 21 COVERAGE$(grep -oP All files\s\|\s\K[0-9.] coverage-output.txt) if [ -z $COVERAGE ]; then echo ERROR: 无法解析覆盖率请检查测试命令 exit 1 fi if (( $(echo $COVERAGE $THRESHOLD | bc -l) )); then echo FAIL: 覆盖率 $COVERAGE% 低于阈值 $THRESHOLD% exit 1 fi echo PASS: 覆盖率 $COVERAGE%这个脚本我改过好几版。第一版没有处理解析失败的情况结果测试命令报错时脚本静默返回agent 以为覆盖率达标了。加上错误处理之后问题就暴露出来了。4.4 技能组合让 code-review 调用安全检查单个技能跑顺之后可以试试技能组合。我的code-review技能里执行步骤的第三步是“调用 security-check 技能检查潜在安全问题”。这样 agent 在执行代码审查时会自动加载安全检查技能形成能力嵌套。组合的关键是技能之间的接口要清晰。code-review需要告诉security-check检查哪些文件、关注哪些方面security-check需要返回结构化的结果比如“文件路径 行号 问题描述 严重级别”。我在两个技能的SKILL.md里都写清楚了输入输出格式实测下来组合执行很顺畅。注意技能嵌套不要太深。我试过三层嵌套agent 的上下文里塞了太多技能说明反而影响了主任务的执行质量。两层基本够用超过三层就要考虑是不是该把某些技能合并了。5. 常见问题与排查技巧实录5.1 技能不触发从触发条件开始查技能不触发是最常见的问题。agent 该用技能的时候没用你只能手动提醒。排查思路是从触发条件往回查。先看触发条件的措辞是否和你的实际指令匹配。如果你说“帮我写个测试”而技能触发条件写的是“用户要求补充单元测试”语义上接近但不完全一致agent 可能就匹配不上。解决办法是在触发条件里多列几种常见表述覆盖不同的说法。再看技能是否被正确挂载。用 CLI 的 list 命令查看已挂载的技能列表确认目标技能在里面。有时候挂载路径写错了技能文件在但 agent 看不到。还有一个隐蔽的原因是技能之间的触发条件冲突。两个技能都声称处理某类任务agent 可能选了另一个。这时候要检查所有技能的触发条件消除重叠。5.2 技能执行到一半卡住上下文和工具权限排查技能触发了但执行到某一步就停住或者反复绕圈。这种情况我遇到过几次原因主要有两类。一类是上下文超限。技能说明太长加上任务本身的上下文超出了 agent 的窗口限制。解决办法是精简SKILL.md把非必要的解释性内容删掉只保留可操作的步骤。模板和清单可以拆到单独文件按需读取。另一类是工具权限问题。技能步骤里要求执行某个终端命令但 agent 没有权限就会卡住。检查 agent 的工具配置确认它有权执行技能里用到的所有工具。我在项目里给 agent 配置了受限的终端权限结果 TDD 技能跑到跑测试那步就停了排查半天才发现是权限没开。5.3 产出不符合预期用产出说明做校验agent 执行完技能但产出格式不对、内容不全。这时候先看SKILL.md里的产出说明是否足够具体。如果只写“生成测试文件”agent 可能生成一个空壳写“生成包含正常路径和至少两个边界情况测试的测试文件使用项目现有的测试框架和断言风格”产出就具体多了。另一个技巧是在技能里加自检步骤。比如 TDD 技能的最后一步写“对照产出说明逐项检查确认测试文件、实现代码、覆盖率报告都已生成且符合要求”。agent 有了明确的检查清单自我校验的能力会强很多。5.4 常见问题速查表问题现象可能原因排查动作解决方向技能不触发触发条件措辞不匹配对比用户指令和触发条件补充常见表述扩大匹配面技能不触发技能未正确挂载用 CLI list 查看技能列表重新挂载检查路径技能不触发多技能触发条件冲突检查所有技能触发条件消除重叠明确分工执行卡住上下文超限估算技能说明加任务的 token 量精简技能拆分文件执行卡住工具权限不足检查 agent 工具配置按需开放权限产出不符预期产出说明太模糊检查 SKILL.md 产出段落写具体格式和内容要求产出不符预期缺少自检步骤检查技能末尾加对照产出说明的自检技能组合失败接口格式不清晰检查技能间输入输出定义明确结构化格式5.5 我踩过的几个坑第一个坑是技能写得太大而全。我一开始做了一个“全流程开发”技能从需求分析到部署全包了。结果 agent 执行时经常在中途迷失因为它要同时处理太多信息。后来拆成需求分析、TDD 实现、代码审查、部署准备四个技能每个都短小精悍执行质量明显提升。第二个坑是忽略技能的测试。技能本身也是代码资产需要测试。我现在的做法是给每个技能写几个测试用例比如“给定一个任务描述验证 agent 是否加载了正确的技能”“给定一个技能执行结果验证产出是否符合格式要求”。这些测试跑起来不复杂但能挡住大部分回归问题。第三个坑是技能文档和实际流程脱节。有次我改了项目的测试命令但忘了同步更新 TDD 技能里的脚本结果 agent 跑测试一直失败。后来我把测试命令抽到一个项目级配置文件里技能脚本从配置文件读取改一处就全生效了。6. 技能资产的长期维护与扩展思路技能跑起来之后真正的挑战是让它持续有用。我见过太多团队一开始热情很高建了一堆技能几个月后没人维护技能和实际流程越差越远最后变成摆设。我的做法是把技能维护纳入日常开发流程。每次项目流程有变化比如换了测试框架、调整了代码规范对应的技能必须同步更新这个动作写进 PR checklist 里。技能仓库的 CI 里跑技能测试测试挂了就阻止合并。这样技能不会悄悄腐烂。扩展方面我倾向于从实际痛点出发而不是为了建技能而建技能。最近加的一个技能是“依赖升级检查”因为项目里依赖升级经常出问题手动检查又费时。技能流程是读 package.json对比最新版本检查 changelog 里的破坏性变更生成升级建议。这个技能上线后依赖升级的返工率降了不少。还有一个扩展方向是技能的市场化。团队之间可以共享技能比如前端团队写的“组件测试技能”可以给后端团队参考。我们内部搞了一个技能索引按领域分类谁有好用的技能就提交上去。这个机制让技能资产流动起来避免了重复造轮子。最后分享一个我在实际使用中的体会技能的价值不在于数量而在于被真正用起来。与其建二十个没人用的技能不如把三五个高频场景的技能打磨到极致。我现在项目里稳定在用的技能就六个但每个都经过反复迭代agent 执行的成功率很高。技能这东西用起来顺手比看起来丰富重要得多。