1. 从“agent-skills”说起为什么它值得单独拿出来聊第一次看到agent-skills这个词是在翻 Claude Code 相关仓库的时候。当时我的第一反应是这不就是把“提示词”换个说法吗但真正把仓库拉下来、跑通 skills CLI、又拿它改造了两个内部项目之后我改变了看法——它解决的是 AI coding agents 落地时最要命的一个问题能力怎么被复用、被约束、被测试。简单说agent-skills是一套给 AI 编码代理AI coding agents用的“技能包”组织方式。你可以把它理解成给 Claude Code 这类工具准备的插件目录每个 skill 是一个独立文件夹里面有说明文档、有可执行脚本、有触发条件代理在合适的场景下自动加载并调用。它要解决的核心痛点很具体——过去我们让 AI 写代码全靠一段又长又乱的系统提示词改一处崩三处团队里每个人还各写各的。agent-skills把这种“一锅炖”拆成了模块化的技能单元配合 skills CLI 做安装、校验、分发再叠加 test-driven-development 的思路让 AI 代理的行为变得可验证。这套东西适合谁三类人最该看一是已经在用 Claude Code、但提示词越写越乱的个人开发者二是想把 AI 编码能力沉淀成团队资产的技术负责人三是做 AI 工具链、需要给代理扩展自定义能力的工程师。哪怕你现在只是刚装好 Claude Code、还在摸索阶段理解 skills 的组织逻辑也能让你少走很多弯路。下面我按自己实际踩过的路径把设计思路、核心细节、实操过程和排查经验完整拆一遍。2. 整体设计思路为什么是“技能”而不是“提示词”2.1 从单体提示词到模块化技能的演进逻辑早期用 Claude Code 的人大概都有这个体验为了让代理遵守项目规范你在CLAUDE.md或者系统提示里塞进一大堆规则——命名规范、目录结构、测试要求、提交格式全堆在一起。刚开始还行规则一多就出问题。代理会“选择性失忆”前面强调的约束到后面就忘了你想改一条规则得在几百行文本里翻半天更麻烦的是这些规则没法单独测试你根本不知道是哪条在起作用、哪条在捣乱。agent-skills的设计思路本质上是软件工程里“关注点分离”那一套。每个 skill 只负责一件事比如“生成符合团队规范的 commit message”是一个 skill“跑测试并修复失败用例”是另一个 skill。每个 skill 自带触发描述代理根据当前任务判断该加载哪个。这样做的好处很直接规则之间不再互相干扰单个 skill 可以独立迭代团队还能把 skill 当代码一样做版本管理。我自己的体会是这种拆分带来的最大收益不是“更整洁”而是可调试。以前代理行为不对你只能猜是哪句话没说清楚现在你可以定位到具体某个 skill单独改、单独测问题范围一下子缩小了。2.2 skills CLI 在整个工具链里的位置skills CLI 是这套体系的操作入口。它干的事情不复杂但每一件都卡在关键位置安装 skill从本地目录或仓库拉取、列出已安装的 skill、校验 skill 的结构是否合法、以及在需要时把 skill 同步到代理能读取的位置。为什么需要一个专门的 CLI而不是手动复制文件夹因为 skill 有固定的目录约定和元数据格式手动搞很容易漏字段、放错位置。CLI 相当于一个“守门人”在安装阶段就把格式问题挡掉。我在团队里推这套东西时最看重的就是这一点——新人不需要理解全部规范跑一条命令就能把 skill 装对。从工具链角度看skills CLI 处在“技能作者”和“代理运行时”之间。作者写 skillCLI 负责分发和校验代理负责加载和执行。三者职责清晰任何一环出问题都能快速定位。2.3 与 test-driven-development 的结合点在哪把 test-driven-developmentTDD和 agent-skills 放一起很多人第一反应是“这俩有什么关系”。关系其实很紧密TDD 的核心是“先写测试再写实现”而 skill 的核心是“先定义代理该做什么、怎么算做对了再让它执行”。一个设计良好的 skill里面应该包含明确的验收标准。比如一个“修复 lint 错误”的 skill它不只是告诉代理“去修 lint”而是定义了修完之后必须满足的条件——lint 命令退出码为 0、没有新增警告、改动范围不超过某个目录。这些条件就是 skill 层面的“测试”。代理执行完你可以用脚本自动验证不通过就重试或报错。我在实际项目里把这两者结合的方式是每个 skill 目录下放一个verify脚本代理执行完主逻辑后自动跑这个脚本。这相当于给 AI 的行为加了一道自动化关卡比单纯靠人眼 review 靠谱得多。后面实操部分我会给出具体的脚本写法。3. 核心细节解析skill 的目录结构与关键字段3.1 一个标准 skill 目录长什么样skill 的目录结构是整套体系的地基搞错一个字段可能整个 skill 都加载不了。基于我实际用过的几个版本一个标准 skill 大致长这样my-skill/ ├── SKILL.md # 技能说明与触发描述 ├── skill.json # 元数据名称、版本、依赖 ├── scripts/ │ ├── run.sh # 主执行脚本 │ └── verify.sh # 验证脚本 └── resources/ └── template.txt # 可选模板、配置等资源SKILL.md是给人看也给代理看的核心文件里面要写清楚这个 skill 解决什么问题、什么时候触发、执行步骤是什么。skill.json是机器读的元数据字段必须准确。scripts目录放可执行逻辑resources放静态资源。这里有个容易踩的坑SKILL.md里的触发描述不能写得太宽泛。我一开始写了个“处理代码相关任务”的 skill结果代理几乎每个任务都想加载它反而干扰了正常判断。后来改成“当用户要求生成符合 Conventional Commits 规范的提交信息时触发”命中率立刻正常了。触发描述要具体到场景这是经验之谈。3.2 SKILL.md 的写法与触发条件设计SKILL.md的写法直接决定 skill 好不好用。我的建议是固定成三段式适用场景、执行步骤、验收标准。适用场景部分用一两句话描述什么时候该用这个 skill。这里的关键词要贴近用户实际会说的话。比如用户会说“帮我提交一下代码”而不是“执行版本控制提交操作”所以触发描述里应该包含“提交代码”“commit”这类自然表达。执行步骤部分把代理要做的事情拆成有序列表。每一步都要足够具体避免“优化代码”这种模糊指令。比如“运行npm run lint收集所有 error 级别的输出”就比“检查代码质量”可操作得多。验收标准部分明确写出什么情况下算完成。这一块和 TDD 的思路直接呼应。我通常会把验收标准写成可执行的检查项比如“npm run lint退出码为 0”“git status显示工作区干净”。提示SKILL.md里的步骤不要写得太长。超过 10 步的 skill 建议拆成两个否则代理执行到后面容易丢失上下文。3.3 skill.json 元数据字段的取舍skill.json里字段不多但每个都有讲究。常见的字段包括name、version、description、triggers、dependencies。name用短横线命名和目录名保持一致避免大小写混用带来的路径问题。version建议遵循语义化版本因为团队协作时你需要知道谁装的是哪个版本。description一句话说清楚会显示在 skills CLI 的列表里。triggers是触发关键词数组和SKILL.md里的场景描述配合使用。dependencies声明这个 skill 依赖的其他 skill 或外部命令CLI 在安装时会检查。我踩过的一个坑是dependencies写得太随意。有次一个 skill 依赖jq命令但我没在元数据里声明换到另一台机器上直接报错。后来养成习惯凡是 skill 脚本里用到的外部命令全部在dependencies里列出来CLI 安装时能提前提示缺失。3.4 脚本层的执行与验证分离脚本层我强烈建议把“执行”和“验证”分成两个文件。run.sh负责干活verify.sh负责检查干得对不对。这样拆分的好处是验证逻辑可以独立复用——同一个 verify 脚本既能被代理自动调用也能被 CI 流水线调用。run.sh里要注意的是错误处理。代理调用脚本时如果脚本静默失败代理会以为任务完成了。所以脚本开头建议加set -euo pipefail任何一步出错都立即退出并返回非零码代理收到非零码就知道需要处理异常。verify.sh的写法要尽量“只读”不要在里面做修改操作。它的职责是判断不是修复。判断结果通过退出码表达0 表示通过非 0 表示失败。这样代理和 CI 都能用统一的方式解读结果。4. 实操过程从零搭一个可用的 skill4.1 环境准备与 skills CLI 安装动手之前先把环境理清楚。我用的是 Ubuntu 环境macOS 上的步骤基本一致。前置条件就两个Node.js 环境建议 18 以上和 git。skills CLI 的安装方式通常是全局安装装完之后用skills --version验证。如果提示命令找不到八成是全局 bin 目录没进 PATH检查一下 npm 的全局路径配置就行。装好 CLI 之后建议先跑一次skills list看看当前有哪些已安装的 skill。刚装完一般是空的这正常。接下来就可以创建自己的第一个 skill 了。注意不同版本的 CLI 命令名可能有细微差异比如有的版本用skills有的用agent-skills。装完先看--help输出以实际提示为准别硬套教程。4.2 创建第一个 skill以“规范提交信息”为例我拿“生成符合规范的提交信息”这个场景做例子因为它足够简单又能体现完整流程。第一步建目录。在 skills 的工作目录下创建commit-message/然后按前面说的结构建好子目录和文件。第二步写SKILL.md。适用场景写“当用户要求提交代码或生成 commit message 时触发”。执行步骤写先运行git diff --cached查看暂存区改动再根据改动内容生成符合 Conventional Commits 规范的信息最后执行提交。验收标准写提交信息格式匹配type(scope): description且git log -1能查到新提交。第三步写skill.json。name填commit-messageversion填1.0.0triggers填[commit, 提交, commit message]。第四步写脚本。run.sh里调用 git 命令获取 diff把 diff 传给代理生成信息。verify.sh里用正则检查最近一条提交信息的格式。第五步用 CLI 安装并测试。跑skills install ./commit-message然后在 Claude Code 里触发一次提交操作看代理是否正确加载了这个 skill。整个过程走下来大概二十分钟但第一次做建议留足时间因为格式细节容易出错。4.3 用 verify 脚本给代理行为加一道关卡verify 脚本是这套体系里我最看重的部分。它把“AI 说自己做完了”变成“有客观证据证明做完了”。以提交信息 skill 为例verify.sh可以这样写#!/usr/bin/env bash set -euo pipefail # 取最近一条提交信息 msg$(git log -1 --pretty%B) # 检查是否符合 Conventional Commits 格式 if echo $msg | grep -qE ^(feat|fix|docs|style|refactor|test|chore)(\(.\))?: .; then echo verify passed exit 0 else echo verify failed: commit message format invalid exit 1 fi这个脚本的逻辑很直白拿到最近一条提交信息用正则匹配规范格式匹配就返回 0不匹配返回 1。代理执行完提交后跑这个脚本失败就知道要重新生成。实测下来加了 verify 之后代理“糊弄”的情况明显减少。以前它偶尔会生成一个格式不对但看起来像那么回事的提交信息现在直接被脚本拦下来。4.4 把 skill 接入 Claude Code 的完整流程skill 写好了怎么让 Claude Code 用上核心是让代理能读到 skill 目录。不同版本的接入方式略有不同但思路一致把 skill 放到代理约定的扫描路径下或者在配置里显式声明 skill 目录。我的做法是在项目根目录建一个.agent-skills/目录把所有 skill 放进去然后在 Claude Code 的项目配置里指向这个目录。这样 skill 跟着项目走团队成员拉下代码就自带技能包不需要各自安装。接入之后要验证两件事一是代理能不能发现 skill触发相关任务时看它是否加载二是 skill 执行结果是否符合预期verify 脚本是否通过。两件都过了才算真正接入成功。提示skill 目录建议纳入版本控制但脚本里的敏感信息比如 token不要硬编码用环境变量传入。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发怎么排查skill 不触发是最常见的问题。排查顺序我总结成三步先看触发描述再看元数据最后看加载路径。触发描述太窄会导致不触发太宽会导致误触发。判断标准是拿几个真实用户会说的话去比对看能不能命中。如果用户说“帮我提交一下”而你的触发词只有“commit”那就漏了。反过来如果触发词是“代码”那几乎所有任务都会命中这就是误触发。元数据问题通常是triggers字段拼写错误或格式不对。CLI 一般有校验命令跑一下能发现大部分问题。加载路径问题最隐蔽。skill 文件都在但代理就是读不到多半是路径配置和代理实际扫描的目录不一致。这时候去看代理的日志通常能看到它在哪些目录找过 skill。5.2 脚本执行失败的典型原因脚本失败的原因五花八门但高频的就那么几个。我整理成一张表方便对照排查现象可能原因排查方法脚本无输出直接退出缺少set -e导致静默失败手动执行脚本看退出码提示命令找不到依赖未声明或未安装检查dependencies字段权限拒绝脚本没有执行权限chmod x加上执行位路径错误用了相对路径但工作目录不对脚本内统一用绝对路径或先 cd编码问题文件含特殊字符检查文件编码为 UTF-8这张表是我踩坑踩出来的尤其是“静默失败”那条。代理调用脚本时如果脚本没加set -e中间某步失败了它还会继续往下走最后返回 0代理以为成功了。这种问题最难查因为表面看一切正常。5.3 多 skill 共存时的冲突处理项目一大skill 就多冲突几乎不可避免。最常见的冲突是触发条件重叠——两个 skill 都觉得自己该处理当前任务。处理思路有两个方向。一是收紧触发条件让每个 skill 的适用场景尽量不重叠。二是设置优先级在元数据里声明优先级字段冲突时高优先级的胜出。我个人的偏好是第一种因为优先级机制虽然能解决问题但会让行为变得不直观——你很难预测代理最终选了哪个 skill。收紧触发条件虽然麻烦一点但行为可预测调试也容易。还有一种冲突是资源冲突比如两个 skill 都要改同一个文件。这种情况建议在 skill 设计阶段就划分清楚职责边界一个 skill 只碰一类文件。5.4 版本升级后 skill 失效的应对工具链升级导致 skill 失效这个坑我踩过不止一次。表现是升级 CLI 或代理之后原本正常的 skill 突然不触发了或者脚本报错。应对方法分两步。短期是先回滚到上一个可用版本保证工作不中断。长期是建立 skill 的兼容性测试——每次升级前跑一遍所有 skill 的 verify 脚本看有没有失败。这其实就是把 TDD 的思路用在了工具链维护上。我现在维护的 skill 仓库里有一个test-all.sh遍历所有 skill 目录跑 verify。升级前跑一遍心里有底。这个习惯帮我省了很多返工时间。6. 我个人的几条实操心得关于 skill 的粒度我的经验是“宁小勿大”。一个 skill 只做一件事做透。我见过有人把整个代码审查流程塞进一个 skill结果代理执行到一半就乱了。拆成“检查命名规范”“检查测试覆盖”“检查依赖安全”三个 skill 之后每个都能稳定跑通。关于 verify 脚本别嫌麻烦每个 skill 都配上。它看起来是额外工作量但省下的是反复人工检查的时间。尤其是团队协作场景verify 脚本相当于一个不会累的审查员。关于触发描述多拿真实对话去测。我习惯在写完 skill 后找几个同事用他们平时的说话方式描述任务看 skill 能不能命中。这个土办法比任何理论都管用。最后分享一个小技巧给 skill 目录加一个README.md记录每个 skill 的用途和最近改动。skill 多了之后光看目录名很容易忘有个总览文档能省不少翻找时间。这个习惯是我从维护代码库迁移过来的用在 skill 管理上同样好使。