1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把散落在各个仓库里的提示词、脚本、工作流模板统一收拢成一套可复用的技能包吗后来实际用下来发现它的野心比我想的要大——它想解决的是AI coding agents 在真实工程场景里会写代码但不会干活这个核心痛点。你如果最近半年在折腾 Claude Code、Cursor、或者各种基于大模型的编码代理应该会有同感模型本身能力已经很强了能读懂代码、能改 bug、能写测试但一旦让它去执行一个完整的工程任务比如给这个模块补一套测试并跑通 CI它就开始犯迷糊——要么忘了先看项目结构要么改完代码不跑测试要么跑测试失败了不知道怎么回滚。这不是模型笨而是缺少一套结构化的、可被代理理解和执行的技能定义。agent-skills要干的事情就是把这些工程套路抽象成一个个独立的 skill每个 skill 有明确的触发条件、执行步骤、验证标准。代理在执行任务时不再是凭感觉瞎猜而是像查手册一样按需加载对应的技能。这个思路其实和人类工程师的成长路径一模一样——新手靠记忆和试错老手靠沉淀下来的 checklist 和肌肉记忆。这篇文章我会从项目整体设计、核心机制、实操落地、常见坑四个维度把agent-skills这套东西拆开讲透。不管你是刚接触 Claude Code 的新手还是已经在用 skills CLI 搭工作流的老玩家应该都能从里面捞到点能直接抄作业的东西。2. 项目整体设计与思路拆解2.1 核心问题代理为什么不听话在聊设计之前得先把问题定义清楚。我观察下来AI coding agents 在实际使用中翻车基本逃不出这三类上下文缺失代理不知道项目的约定比如测试框架用的是 vitest 还是 jestlint 规则是 eslint 还是 biome结果生成一堆风格不一致的代码。流程跳跃让它改个函数它直接改完就交差不跑测试、不检查类型、不更新文档。人类工程师不会这么干但代理默认就是这么干。验证缺位改完代码声称已完成但实际上根本没验证。你问它跑没跑测试它说应该没问题。这三个问题的根源是一样的代理缺少一个显式的、可执行的工作协议。传统做法是把这些约定塞进 system prompt 或者项目根目录的CLAUDE.md但问题是 prompt 越写越长模型注意力被稀释关键规则反而被忽略。agent-skills的解法很直接把工作协议拆成独立的 skill 文件每个文件只讲一件事代理按需加载。这就像你不会把整本《代码大全》塞进脑子而是遇到具体问题时翻对应章节。2.2 设计哲学技能即契约我读完项目结构和几个示例 skill 之后最大的感受是每个 skill 本质上是一份契约。它规定了三件事什么时候用触发条件比如当用户要求新增功能时、当测试失败时。怎么做执行步骤具体的操作序列包括要跑哪些命令、要检查哪些文件。做完的标准验证条件怎么算完成比如所有测试通过、类型检查无错误。这个三段式结构看起来简单但威力在于它把模糊的帮我改个功能变成了可执行的流水线。代理不再需要猜测你的意图而是按照 skill 定义的路径走。我拿 test-driven-development 这个 skill 举例。它的触发条件是实现新功能或修复 bug执行步骤是先写失败测试 → 运行确认失败 → 写最小实现 → 运行确认通过 → 重构验证条件是测试从红变绿且覆盖率不下降。你看这就是一个标准的 TDD 循环但被显式地写成了代理能执行的协议。2.3 为什么不用一个大 prompt 搞定有人可能会问为什么不直接把这些规则写进一个超长的 system prompt我实测下来原因有三个注意力稀释prompt 超过一定长度后模型对中间部分的规则遵循度明显下降。这是 transformer 架构的固有问题不是模型不够聪明。加载成本不是每个任务都需要所有 skill。改个 typo 不需要加载 TDD 流程跑个 lint 不需要加载部署 skill。按需加载能省 token 也能提准确率。可维护性一个 skill 一个文件改起来清晰。塞在一个大 prompt 里改一处可能影响其他规则。提示如果你现在还在用超长CLAUDE.md管理代理行为建议先挑出最常翻车的 2-3 个场景把它们抽成独立 skill 试试。改完你会明显感觉到代理听话了很多。2.4 与 Claude Code 的关系agent-skills和 Claude Code 的关系我理解是技能库和执行器的关系。Claude Code 提供了代理运行的基础设施——文件读写、终端命令执行、代码搜索这些底层能力。agent-skills则是在这之上定义了一层工程规范告诉代理在什么场景下该调用哪些能力、按什么顺序调用。这也是为什么 skills CLI 这个工具很重要。它负责把 skill 文件安装到 Claude Code 能识别的位置通常是项目根目录的.claude/skills/或者用户级的配置目录。安装完之后Claude Code 在启动时会自动扫描这些 skill根据当前任务动态加载。3. 核心细节解析与实操要点3.1 skill 文件的结构长什么样一个标准的 skill 文件我拆开看大概是这几个部分--- name: test-driven-development description: 当需要实现新功能或修复 bug 时使用确保代码有测试覆盖 trigger: 用户要求新增功能、修复 bug、或重构代码 --- ## 执行步骤 1. 阅读相关代码理解现有测试结构 2. 编写一个会失败的测试用例 3. 运行测试确认它确实失败 4. 编写最小实现让测试通过 5. 运行完整测试套件确认无回归 6. 重构代码保持测试绿色 ## 验证条件 - 新测试从失败变为通过 - 完整测试套件全部通过 - 没有跳过或注释掉的测试frontmatter 里的name、description、trigger是给代理做匹配用的。代理拿到任务后会先看哪些 skill 的 trigger 匹配当前场景然后加载对应的执行步骤。这个匹配过程可以是关键词匹配也可以是语义匹配取决于具体实现。我个人的经验是description写得越具体匹配越准。别写用于开发要写当需要实现新功能或修复 bug 时使用。前者太泛代理可能在不该加载的时候加载。3.2 skills CLI 的安装与使用skills CLI 是管理这些 skill 的命令行工具。安装方式我试过两种都挺顺# 方式一通过 npm 全局安装 npm install -g agent-skills/cli # 方式二通过 npx 直接运行不污染全局环境 npx agent-skills/cli init安装完之后常用命令大概这几个# 初始化项目创建 .claude/skills 目录 skills init # 从远程仓库安装一个 skill skills install test-driven-development # 列出当前项目已安装的 skill skills list # 更新所有 skill 到最新版本 skills update # 移除某个 skill skills remove test-driven-development我实测下来skills init会在项目根目录创建.claude/skills/文件夹并在里面放一个README.md说明文件。之后skills install下载的 skill 都会放在这个目录下。注意如果你用的是 Claude Code 的桌面版或者 VS Code 插件skill 目录的位置可能略有不同。VS Code 插件默认读的是工作区根目录下的.claude/skills/而桌面版可能会读用户级配置目录。装完 skill 后如果代理没反应先检查目录位置对不对。3.3 触发机制代理怎么知道该用哪个 skill这是整个系统里最容易被忽略但最关键的部分。代理不是把所有 skill 都加载进上下文而是根据当前任务动态选择。选择逻辑我观察下来大概是这样的任务解析代理先理解用户请求提取关键动作比如新增、修复、重构、部署。skill 匹配拿这些动作去匹配各个 skill 的 trigger 字段。优先级排序如果有多个 skill 匹配按优先级或依赖关系排序。比如 TDD skill 可能优先于 code-review skill。动态加载把匹配到的 skill 内容注入当前上下文然后开始执行。这个机制的好处是上下文始终干净。你让代理改个 typo它不会加载 TDD 流程你让它写测试它才会加载。我试过在一个项目里装了十几个 skill日常使用中代理每次只加载 1-2 个token 消耗很可控。3.4 自定义 skill 的编写要点官方提供的 skill 只是起点真正有价值的是你自己项目沉淀下来的 skill。我写自定义 skill 的时候总结了几个要点一个 skill 只干一件事别把写测试和部署塞进一个 skill。粒度越细复用性越高。步骤要可执行别写确保代码质量这种废话要写运行npm run lint并修复所有 error。验证条件要客观别写代码看起来没问题要写npm test退出码为 0。trigger 要具体用具体的动作词别用开发、优化这种模糊词。我拿一个实际例子说明。我们项目里有个 skill 叫api-endpoint-creation专门处理新增 API 接口的场景。它的步骤是这样的## 执行步骤 1. 在 src/routes/ 下创建路由文件命名遵循 kebab-case 2. 在 src/controllers/ 下创建控制器导出标准 CRUD 方法 3. 在 src/schemas/ 下用 zod 定义请求和响应 schema 4. 在 tests/routes/ 下创建集成测试覆盖成功和失败路径 5. 运行 npm run test:routes 确认通过 6. 更新 docs/api.md 添加接口文档 ## 验证条件 - 路由文件、控制器、schema 文件都已创建 - 集成测试覆盖至少 3 个场景成功、参数错误、权限不足 - npm run test:routes 全部通过 - API 文档已更新这个 skill 装上去之后代理新增接口的规范度明显提升。以前它经常忘了写 schema 或者忘了更新文档现在基本不会漏。4. 实操过程与核心环节实现4.1 环境准备从零搭一个可用的 skill 环境我拿一个真实项目走一遍完整流程。假设你有一个 Node.js 项目想接入agent-skills来规范代理行为。第一步确认 Claude Code 已经装好并能正常使用。如果你还没装Ubuntu 或者 Mac 上的安装方式大概是# Mac 上通过 Homebrew 安装 brew install --cask claude-code # Ubuntu 上通过官方脚本安装 curl -fsSL https://claude.ai/install.sh | sh装完之后跑claude --version确认版本。我建议用最新版本因为 skill 相关的功能在持续迭代老版本可能不支持。第二步在项目根目录初始化 skillscd your-project npx agent-skills/cli init这一步会创建.claude/skills/目录。你可以看一下目录结构your-project/ ├── .claude/ │ └── skills/ │ └── README.md ├── src/ ├── tests/ └── package.json第三步安装几个基础 skill。我建议新手先装这三个skills install test-driven-development skills install code-review skills install commit-convention这三个覆盖了日常开发最高频的场景写代码、审代码、提交代码。4.2 配置 Claude Code 识别 skillskill 装好了但 Claude Code 不一定知道去哪读。我踩过的坑是装完 skill 后代理完全没反应后来发现是配置文件没写对。Claude Code 的配置文件通常在项目根目录的.claude/settings.json或者用户级的~/.claude/settings.json。你需要确保里面配置了 skill 目录{ skills: { directory: .claude/skills, autoLoad: true } }autoLoad设为 true 之后Claude Code 启动时会自动扫描 skill 目录。如果你不想自动加载可以设为 false然后手动指定要加载的 skill。提示如果你用的是 VS Code 插件版的 Claude Code配置文件的路径可能是.vscode/claude-code.json。不同版本路径不太一样建议先看官方文档确认。装完 skill 后如果代理没反应八成是路径问题。4.3 跑通第一个 TDD 流程配置好之后我们来跑一个完整的 TDD 流程验证 skill 是否生效。假设我们要给一个工具函数库新增一个formatCurrency函数。在 Claude Code 里输入帮我新增一个 formatCurrency 函数接收数字和货币代码返回格式化后的字符串如果 TDD skill 生效了代理的执行顺序应该是这样的先读现有代码结构看测试框架和代码风格在测试文件里写一个会失败的测试运行测试确认失败写最小实现运行测试确认通过重构我实测下来装了 TDD skill 之后代理确实会先写测试。没装之前它直接写实现测试要么不写要么最后补。这个差别在长期项目里影响很大——先写测试的代码边界条件覆盖明显更全。代理执行过程中你可以在终端看到它跑的命令。比如它会跑npm test -- --grep formatCurrency看到测试从红变绿就说明 TDD 流程走通了。4.4 自定义一个项目专属 skill官方 skill 是通用的但每个项目都有自己的约定。我拿一个实际场景演示怎么自定义。假设你们项目规定所有数据库查询必须走 repository 层不能在 controller 里直接调 ORM。这个约定如果不写成 skill代理经常违反。创建.claude/skills/db-access-convention.md--- name: db-access-convention description: 当需要访问数据库时使用确保查询走 repository 层 trigger: 用户要求查询、新增、更新、删除数据库记录 --- ## 执行步骤 1. 检查 src/repositories/ 下是否已有对应的 repository 2. 如果没有创建新的 repository 文件继承 BaseRepository 3. 在 repository 里实现查询方法方法名用动词开头 4. 在 controller 里调用 repository 方法不直接引入 ORM 5. 运行 npm run test:repositories 确认通过 ## 验证条件 - controller 文件里没有直接 import ORM 库 - 所有数据库操作都通过 repository 方法 - repository 测试全部通过装上去之后代理再写数据库相关代码就会自动走 repository 层。我试过故意让它直接在 controller 里查一下用户表它会先创建 repository 方法再调用而不是直接写 SQL。4.5 多 skill 协同一个完整功能的开发流程真实开发中一个功能往往需要多个 skill 协同。我拿新增用户注册接口举例完整的 skill 调用链大概是阶段触发的 skill作用需求理解无代理解析任务写测试test-driven-development先写失败测试写实现api-endpoint-creation按规范创建路由、控制器、schema数据库操作db-access-convention走 repository 层代码审查code-review自查代码质量提交commit-convention按规范写 commit message这个链条跑下来代理产出的代码规范度接近一个熟悉项目的老手。我对比过装 skill 前后同一个任务的产出装之前的代码需要我改 5-6 处装之后基本改 1-2 处就能合并。5. 常见问题与排查技巧实录5.1 skill 不生效的排查思路这是最高频的问题。我整理了一个排查清单按顺序检查检查项怎么查常见原因skill 目录位置ls .claude/skills/目录不存在或位置不对配置文件看 settings.json 的 skills 字段没配 directory 或 autoLoadskill 格式检查 frontmatter 是否完整缺 name 或 trigger代理版本claude --version版本太老不支持 skill触发词看任务描述是否匹配 triggertrigger 写得太窄我遇到最多的是配置文件问题。装完 skill 后代理没反应九成是settings.json里没配 skill 目录。其次是 skill 格式问题frontmatter 少个字段就可能导致整个 skill 被忽略。5.2 skill 冲突怎么办装了多个 skill 之后可能出现冲突。比如两个 skill 都匹配当前任务代理不知道该听谁的。我的处理原则是明确优先级在 skill 的 frontmatter 里加priority字段数字越小优先级越高。拆分触发条件让每个 skill 的 trigger 尽量不重叠。比如 TDD skill 管写代码code-review skill 管审代码别让它们都匹配改代码。合并相关 skill如果两个 skill 经常一起触发考虑合并成一个。我试过一个极端情况装了 5 个 skill结果代理每次执行任务都加载全部上下文被塞满反而变笨了。后来把 trigger 改具体每次只加载 1-2 个效果立刻好转。5.3 代理跳过验证步骤这是 TDD skill 使用中最常见的问题。代理写完实现声称测试通过但实际上根本没跑测试。排查方法看终端输出。如果代理没跑npm test就宣布完成说明验证条件没被强制执行。解决思路有两个在 skill 里明确写命令别写运行测试要写运行npm test并确认退出码为 0。加一个 verification skill专门负责在任务完成后跑验证命令不通过就报错。我现在的做法是在每个 skill 的验证条件里都写具体的命令和预期输出。代理看到退出码为 0这种客观标准比看到测试通过这种模糊描述执行率高很多。5.4 自定义 skill 的常见坑写自定义 skill 的时候我踩过这几个坑步骤太抽象写优化代码结构代理不知道具体做什么。要写把超过 50 行的函数拆分成多个小函数。验证条件不可执行写代码质量良好没法验证。要写npm run lint无 error。trigger 太宽泛写当需要开发时几乎匹配所有任务。要写当需要新增 API 接口时。一个 skill 塞太多把整个开发流程塞进一个 skill代理执行时容易漏步骤。拆成多个小 skill每个只干一件事。提示写完自定义 skill 后先拿一个简单任务测试。如果代理执行步骤和预期不符先检查 skill 的步骤描述是否足够具体。我一般会改 2-3 轮才能让 skill 稳定工作。5.5 性能与 token 消耗装了 skill 之后token 消耗会增加因为 skill 内容要注入上下文。我实测下来一个中等长度的 skill 大概占 500-1000 token。如果一次加载 3 个 skill就是 1500-3000 token 的额外开销。控制方法按需加载确保 autoLoad 逻辑是动态的不是全量加载。精简 skill 内容步骤描述够用就行别写成长篇大论。定期清理项目里不用的 skill 及时移除别让它们占着位置。我现在的项目里常驻 5 个 skill日常任务平均加载 1.5 个token 开销在可接受范围内。相比代理翻车后我手动修代码的时间成本这点 token 消耗完全值得。6. 我个人的使用体会与扩展思路用agent-skills这套东西大概两个月最大的感受是它把调教代理从玄学变成了工程。以前我靠反复改 prompt 来让代理听话效果不稳定换个任务就失效。现在我把工程约定写成 skill代理的行为变得可预测、可复现。我现在的做法是每遇到一次代理翻车就问自己这个错误能不能通过一个 skill 来避免如果能就写一个。两个月下来项目里沉淀了 8 个自定义 skill代理的翻车率明显下降。后续我打算扩展的方向有两个一是把 skill 和 CI 打通让代理在提交前自动跑一遍所有相关 skill 的验证条件二是把 skill 做成团队共享的让每个成员的项目都能复用同一套工程约定。这两个方向如果跑通代理的产出质量应该能再上一个台阶。如果你刚开始接触这套东西我的建议是别一上来就写一堆 skill。先装官方的 2-3 个基础 skill 用一周感受一下代理行为的变化然后再针对自己项目最常翻车的场景写第一个自定义 skill。循序渐进比一次性搭个大框架要靠谱得多。