1. 从agent-skills说起为什么这个项目值得你花时间第一次看到agent-skills这个标题我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套插件化的能力说明书让 Claude Code、Cursor、Windsurf 这类 AI 编程代理在特定任务上表现得更像一个有经验的工程师而不是一个只会补全代码的自动机。我接触 AI coding agent 的时间不算短从最早拿 Claude Code 当高级 grep 用到后来把它接进 CI 流程里跑测试、改 bug、写迁移脚本中间踩过的坑足够写一本小册子。agent-skills这类项目的核心价值说白了就一句话把怎么让 agent 干好一件事从散落在各处的 prompt 里抽出来变成可复用、可版本管理、可组合的技能单元。它解决的是每次都要重新教 agent 做事这个重复劳动问题适合所有已经在用或准备用 AI coding agent 的开发者尤其是那些想让 agent 参与真实工程流程、而不是只当玩具的人。这篇文章我会从设计思路、核心机制、实操落地、问题排查四个层面把agent-skills拆开讲透。不管你是刚装好 Claude Code 的新手还是已经在用 skills CLI 管理一堆技能的老手都能从里面找到能直接抄作业的东西。我尽量不写那种官方文档翻译式的废话多讲我在实际项目里验证过的做法和踩过的坑。2. agent-skills 的整体设计与思路拆解2.1 为什么需要技能这一层抽象在没有 skills 概念之前大家是怎么让 AI coding agent 干活的无非几种方式在对话里临时写一段 prompt、在项目根目录放一个CLAUDE.md或.cursorrules、或者干脆把指令塞进代码注释里。这些方式在单次任务里够用但一旦任务变复杂、团队变多人、项目变多仓库问题就全冒出来了。我举个真实场景。我们团队之前有个需求每次改数据库 schema都要同步更新 migration 文件、更新 ORM 模型、更新 API 文档、跑一遍集成测试。最开始我把这套流程写成一段长 prompt 存在笔记里每次复制粘贴。后来发现三个问题第一prompt 越写越长agent 开始选择性失忆后面的指令经常被忽略第二不同人复制的时候会漏掉几步第三prompt 和代码不在一个仓库里改代码的人不知道 prompt 也该改。agent-skills这类项目的设计思路本质上是把一段长 prompt拆成多个职责单一的小技能每个技能有自己的触发条件、输入输出约定和执行步骤。这跟软件工程里函数拆分是一个道理——一个函数只做一件事组合起来完成复杂流程。技能拆开之后agent 每次只需要加载当前任务相关的那几个技能上下文压力小执行准确率自然就上去了。提示技能拆分的粒度很关键。拆得太粗等于没拆拆得太细agent 光加载技能就耗掉大量上下文。我的经验是一个技能对应一个可独立验证的产出比如生成一个 migration 文件是一个技能跑通集成测试是另一个技能。2.2 技能包的核心组成要素一个设计良好的 skill通常包含这么几个部分我按重要性排序触发描述description告诉 agent 什么情况下该用这个技能。这段文字的质量直接决定技能会不会被正确调用。写得太泛agent 到处乱用写得太窄该用的时候想不起来。执行指令instructions具体怎么做分步骤写清楚。这里要避免正确的废话比如写出高质量的代码这种指令等于没写要写成函数不超过 50 行每个公开方法必须有 docstring这种可验证的约束。输入输出约定技能需要什么参数、产出什么结果。这一步很多人会忽略但它是技能能组合的前提。示例examples给一两个正例最好再给一个反例。agent 对示例的敏感度远高于抽象描述。依赖声明这个技能依赖哪些工具、哪些其他技能、哪些环境变量。我见过太多人写 skill 只写执行指令这一块结果 agent 要么不触发要么触发了但产出不符合预期。触发描述和示例这两块才是决定技能好不好用的关键值得多花时间打磨。2.3 与 test-driven-development 的天然契合热词里出现了test-driven-development这不是巧合。agent-skills和 TDD 的结合点非常自然TDD 的核心是先写测试再写实现测试通过才算完成而 AI coding agent 最擅长的恰恰是根据明确的验收标准反复迭代。我现在的做法是凡是让 agent 参与的开发任务都尽量走 TDD 流程。具体来说先让 agent 根据需求写测试用例这一步人必须 review因为 agent 写的测试经常漏边界测试跑失败然后让 agent 写实现直到测试通过。这个流程里写测试和写实现就是两个独立的 skill中间用测试结果作为输入输出约定连接起来。这样做的好处是agent 有了明确的完成信号——测试全绿。没有 TDD 的时候agent 经常写完代码就说完成了但你一跑发现一堆问题。有了测试作为验收标准agent 会自己迭代到通过为止人只需要在最后 review 一次。2.4 方案选型为什么是 CLI 而不是插件skills CLI这个热词说明这类项目普遍选择命令行作为主要交互方式。我一开始也疑惑为什么不做成 IDE 插件图形界面不是更友好吗用了一段时间之后我理解了CLI 的天然优势是可组合和可脚本化。技能管理这件事本质上和包管理很像——安装、卸载、更新、列出、搜索。这些操作用 CLI 做可以轻松接进 CI、接进 git hook、接进其他脚本。而 IDE 插件受限于宿主环境跨编辑器复用困难。更重要的是CLI 让技能包可以像 npm 包一样被版本管理agent-skills的更新可以走标准的依赖升级流程而不是手动去插件市场点更新。当然 CLI 也有代价就是学习曲线。但考虑到目标用户本来就是开发者这个代价可以接受。我的建议是如果你刚开始用先把 CLI 的基本命令摸熟别急着上图形界面。3. 核心细节解析与实操要点3.1 技能目录结构与文件组织一个规范的 skills 仓库目录结构通常长这样agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── db-migration/ │ │ ├── SKILL.md │ │ └── templates/ │ └── api-doc-sync/ │ └── SKILL.md ├── skills.json └── README.md每个技能一个目录目录名就是技能标识符用 kebab-case 命名。核心文件是SKILL.md里面用 frontmatter 写元数据正文写指令。examples/放示例scripts/放技能执行时可能调用的辅助脚本templates/放模板文件。skills.json是清单文件记录所有技能的元信息方便 CLI 快速索引而不用遍历所有目录。这个设计跟package.json是一个思路。注意技能目录名一旦确定就不要随便改因为其他技能可能通过名字引用它。改名等于破坏性变更要走版本升级流程。3.2 SKILL.md 的写法从能跑到好用SKILL.md是整个技能的核心我把它拆成 frontmatter 和正文两部分讲。frontmatter 部分至少要包含这几个字段--- name: tdd-workflow description: 当需要按测试驱动开发流程实现新功能时使用。先写失败测试再写实现迭代到测试通过。 version: 1.2.0 tags: [testing, workflow, tdd] dependencies: [test-runner] ---description这一行是重中之重。我踩过的坑是早期把 description 写成用于 TDD 开发结果 agent 在写文档、改配置的时候也偶尔触发它。后来改成当需要按测试驱动开发流程实现新功能时使用触发准确率明显提升。description 要写清楚什么时候用而不是这是什么。正文部分我一般按这个结构写前置检查执行前需要确认什么比如确认测试框架已配置。执行步骤分步骤每步一个明确动作。验收标准怎么算完成比如所有测试通过且覆盖率不低于 80%。失败处理测试不通过时怎么办比如分析失败原因修改实现重新运行最多迭代 5 次。示例一个完整的正例。这里有个经验步骤要写成动词开头的祈使句比如运行npm test而不是测试应该被运行。agent 对祈使句的执行意愿明显更高。3.3 触发机制agent 怎么知道该用哪个技能这是很多人困惑的地方。agent 不是人它不会记住所有技能然后按需调用。实际机制通常是把所有技能的 description 拼成一段索引放在 agent 的上下文里agent 根据当前任务判断该加载哪个技能的完整内容。这就解释了为什么 description 的质量如此关键。它相当于技能的广告词要在几十个技能里脱颖而出让 agent 在正确的时机想起它。我总结了几条写 description 的实操技巧用当……时使用的句式明确触发场景。包含具体的动作词比如生成校验重构迁移。避免和其他技能的 description 高度重叠否则 agent 会犹豫。长度控制在 50 到 100 字太短信息不够太长挤占上下文。实测下来description 写得好技能触发准确率能从六七成提到九成以上。这个投入产出比非常高。3.4 技能组合让多个技能串成工作流单个技能能做的事有限真正的威力在于组合。agent-skills支持技能之间互相引用形成一个有向图。比如实现新功能这个高层技能可以依次调用写测试写实现跑测试更新文档四个子技能。组合的时候要注意几点避免循环依赖A 调用 BB 又调用 Aagent 会陷入死循环。设计时画一下依赖图。明确数据传递上一个技能的产出怎么传给下一个。通常通过文件或者约定的变量名。失败要能中断子技能失败时父技能应该停止而不是继续往下走。我一般会把常用的组合固化成工作流技能比如feature-development就是一个组合技能内部编排了 TDD 全流程。这样日常使用只需要触发一个技能不用手动串。4. 实操过程与核心环节实现4.1 环境准备从零搭起 skills 工作区假设你现在什么都没装我带你走一遍完整流程。这里以 Claude Code 作为 agent 宿主举例其他 agent 的接入方式类似。第一步确认 Node.js 环境。skills CLI 通常基于 Node 生态node -v # 建议 18.x 或以上 npm -v第二步安装 skills CLI。具体包名以项目文档为准一般形式是npm install -g your-scope/skills-cli skills --version第三步初始化工作区。在你的项目根目录执行skills init这会生成skills/目录和skills.json清单文件。如果你已经有现成的技能仓库用skills link把它链接进来。第四步验证 agent 能读到技能。在 Claude Code 里输入一句列出当前可用的技能如果配置正确agent 会返回技能列表。如果返回空检查skills.json的路径配置和 agent 的技能索引配置。提示不同 agent 读取技能索引的方式不一样。Claude Code 通常通过项目根目录的配置文件指定技能目录具体字段名以官方文档为准。配置错了不会报错只是技能静默不生效这点很坑一定要主动验证。4.2 写第一个技能以生成数据库迁移为例我拿一个真实需求来演示每次改 schema自动生成 migration 文件。这个技能我用了大半年很稳。先建目录mkdir -p skills/db-migration/templates然后写SKILL.md--- name: db-migration description: 当需要根据 schema 变更生成数据库迁移文件时使用。读取当前模型定义对比目标 schema生成可回滚的 migration。 version: 1.0.0 tags: [database, migration] dependencies: [] --- ## 前置检查 1. 确认项目使用支持 migration 的 ORM如 Prisma、TypeORM、Alembic。 2. 确认当前工作区没有未提交的 migration 文件。 ## 执行步骤 1. 读取 schema/ 目录下的当前 schema 定义。 2. 对比目标 schema列出所有差异新增表、删除表、字段变更、索引变更。 3. 为每个差异生成对应的 up 和 down 操作。 4. 将 migration 写入 migrations/ 目录文件名格式为 YYYYMMDDHHMMSS_description.sql。 5. 运行 migration 的 dry-run 校验语法。 ## 验收标准 - migration 文件能通过 dry-run。 - 每个 up 操作都有对应的 down 操作。 - 不包含任何数据删除操作除非显式要求。 ## 失败处理 - dry-run 失败读取错误信息修正语法重新生成。 - 存在无法自动处理的差异停止并输出差异清单请求人工介入。写完这个文件用skills validate db-migration校验格式。然后在一个真实 schema 变更上测试观察 agent 是否按步骤执行。我实测下来这个技能把原来每次 15 分钟的迁移编写压缩到 2 分钟 review。关键是 down 操作也自动生成了回滚的时候不用临时补。4.3 接入 TDD 工作流完整跑一遍现在把 TDD 技能和迁移技能组合起来演示一个完整的功能开发流程。场景给用户表加一个last_login_at字段并写一个记录登录时间的接口。第一步触发tdd-workflow技能让 agent 先写测试请用 tdd-workflow 技能为记录用户登录时间功能编写测试。agent 会生成测试文件包含登录成功后last_login_at被更新、登录失败时不更新、时间格式正确等用例。这一步人必须 review我见过 agent 写的测试只覆盖 happy path边界全漏。第二步跑测试确认全部失败因为实现还没写。这是 TDD 的红灯阶段。第三步触发实现技能让 agent 写代码直到测试通过请实现上述测试对应的功能迭代到所有测试通过。agent 会进入写代码—跑测试—看失败—改代码的循环。这里有个经验给 agent 设置最大迭代次数比如 5 次。超过就停下来让人介入否则它可能在一个死胡同里反复撞墙浪费 token。第四步测试全绿后触发db-migration技能生成字段变更的迁移文件。第五步人工 review 所有产出测试、实现、迁移。确认无误后提交。整个流程走下来一个中等复杂度的功能大概 20 到 30 分钟其中人的介入主要是两次 review。相比纯手写效率提升明显而且测试覆盖率有保障。4.4 参数与配置几个容易配错的点实操中有几个配置项特别容易出问题我列一下配置项常见错误正确做法技能目录路径用相对路径agent 工作目录变了就找不到用绝对路径或基于项目根的路径最大迭代次数不设置agent 无限循环设 3 到 5 次超限中断上下文预算一次加载所有技能挤爆上下文只加载当前任务相关技能超时时间用默认值长任务被误杀按任务类型分别设置日志级别开 debug日志淹没关键信息生产用 info排查时临时开 debug上下文预算这一项我要多说一句。agent 的上下文窗口是有限的技能加载、代码读取、对话历史都在抢这个空间。我见过有人装了 50 个技能结果 agent 每次响应都变慢、变笨就是因为索引占用了太多上下文。技能不是越多越好常用的十几个就够了其余按需临时加载。5. 常见问题与排查技巧实录5.1 技能不触发从三个方向排查技能不触发是最常见的问题我按排查顺序列一下。第一检查 description 是否清晰。把 description 单独拿出来读问自己这句话能让我在正确的场景想起这个技能吗。如果答案模糊重写。第二检查技能是否被正确索引。运行skills list看技能在不在列表里。不在的话检查skills.json和目录结构。第三检查触发场景是否真的匹配。有时候是任务描述太模糊agent 无法判断。试着在任务里明确提到技能名比如用 db-migration 技能生成迁移。我整理了一个速查表现象可能原因解决技能完全不出现未索引检查 skills.json 和目录技能偶尔触发description 模糊重写 description加触发场景触发但执行错指令不具体把步骤改成祈使句加验收标准多个技能抢触发description 重叠差异化描述明确各自边界触发后卡住依赖缺失检查 dependencies 声明5.2 执行结果不稳定如何提高可复现性同一个技能今天跑得好明天跑得差这是 AI agent 的固有特性。但可以通过一些手段提高稳定性。固定输入。技能执行依赖的文件、环境变量、工具版本尽量固定。比如测试框架版本变了agent 生成的测试可能就不兼容。降低温度参数。如果 agent 支持调 temperature技能执行时调低输出更确定。加自检步骤。在技能末尾加一步检查产出是否符合验收标准让 agent 自己发现问题。记录执行日志。每次执行把输入输出存下来出问题时能对比。我一般会在技能里加一步把本次执行的关键信息写入.skills-log/目录。5.3 踩过的坑几个血泪教训坑一技能里写了破坏性操作。早期我写过一个清理临时文件的技能指令是删除所有未跟踪的文件。结果 agent 在一个没配好 gitignore 的项目里执行删掉了一堆本该保留的文件。教训是破坏性操作必须加确认步骤或者限制作用范围。坑二技能依赖外部服务但没处理失败。有个技能要调外部 API我没写失败处理结果 API 挂了之后 agent 一直重试把配额耗光了。现在所有外部依赖都加超时和重试上限。坑三技能之间循环引用。A 技能说参考 B 技能的做法B 技能说参考 A 技能的做法agent 直接懵了。设计依赖图的时候一定要检查有没有环。坑四description 用了太多同义词。我写过一个技能 description 里同时出现重构优化改进结果 agent 在三种场景都触发它但实际它只适合重构。一个技能只描述一种场景。5.4 性能优化让技能跑得更快更省技能执行慢、耗 token 多是规模化使用后的主要痛点。我总结了几条优化经验。精简技能内容。把不常用的分支拆出去主技能只保留核心路径。我有个技能从 800 行精简到 300 行执行时间降了一半。缓存中间结果。技能执行中如果某一步结果可复用存到缓存目录下次直接读。并行化独立步骤。如果技能里有多个互不依赖的步骤让 agent 并行执行。不过要注意不是所有 agent 都支持并行得看具体实现。按需加载。别把所有技能都塞进上下文用索引加按需加载的方式。这个前面提过是省 token 的大头。6. 技能包的版本管理与团队协作6.1 版本管理像管代码一样管技能技能是代码就该用代码的方式管理。我的做法是技能仓库独立成一个 git 仓库走标准的 PR 流程。每次修改技能都要说明改了什么、为什么改、怎么验证的。版本号用语义化版本。改 description 或加示例算 patch加步骤或改验收标准算 minor改输入输出约定或删步骤算 major。major 变更要通知所有使用方。skills.json里记录每个技能的版本CLI 可以据此检查更新。我一般会定期跑skills outdated看有没有新版本但不会自动升级因为技能变更可能影响现有工作流得先测试。6.2 团队协作让技能成为团队资产一个人用技能和团队用技能复杂度完全不一样。团队用的时候要考虑几个问题。统一技能源。别每个人维护自己的技能副本用一个共享仓库大家 link 过去。这样改一处所有人受益。明确 owner。每个技能指定一个负责人负责 review 变更、处理问题。没有 owner 的技能会慢慢腐烂。写使用文档。技能本身是给 agent 看的但团队需要一份给人看的文档说明有哪些技能、各自干什么、怎么组合。这份文档我一般放在仓库 README 里。定期清理。过时的技能及时删别留着占索引。我每季度清理一次删掉三个月没人用的技能。6.3 安全与合规技能里的红线技能会执行真实操作安全不能马虎。几条红线我列一下。不写破坏性操作或者必须加二次确认。不硬编码密钥用环境变量。不访问未授权的资源技能里涉及的外部调用要明确声明。不生成可能有害的内容比如批量删除、绕过校验的代码。技能变更要 review尤其是涉及文件系统、网络、数据库操作的。我见过有人写了个技能自动提交代码到主分支结果 agent 误触发把半成品推上去了。涉及 git 操作的技能一定要限制在 feature 分支。7. 从 agent-skills 延伸出去的几个方向7.1 技能市场与共享生态agent-skills这类项目发展到一定阶段自然会走向技能共享。现在已经能看到一些技能市场的雏形大家可以发布、搜索、安装别人写的技能。这对新手特别友好不用从零写先拿现成的用。但共享也带来质量参差的问题。我的建议是用别人的技能前先读一遍SKILL.md确认它做的事符合你的预期尤其是涉及文件操作的。别看到名字就装。7.2 技能与 CI/CD 的集成技能不只能在本地用还能接进 CI。比如在 PR 流程里加一步用 code-review 技能自动审查变更或者在发布流程里加用 changelog 技能生成发布说明。我现在的做法是把几个稳定的技能接进 CI作为自动化检查的一部分。注意 CI 环境里 agent 的权限要收紧别给它写仓库的权限。7.3 技能的可观测性技能跑多了之后你会想知道哪些技能用得最多、哪些经常失败、平均执行多久。这些数据能指导优化。我一般会在技能执行时打点记录技能名、耗时、结果状态汇总到一个看板里。有了数据之后优化就有方向了。比如发现某个技能失败率特别高就去查原因发现某个技能没人用就考虑删掉。8. 我个人的一些实操体会用agent-skills这套东西大半年最大的体会是技能的质量不取决于你写了多少而取决于你删了多少。一开始我恨不得把每个操作都写成技能结果索引臃肿、触发混乱。后来砍到十几个核心技能反而好用多了。另一个体会是技能要跟着项目演进。项目初期和成熟期需要的技能完全不一样。初期可能需要大量脚手架类技能成熟期更需要重构、审查、文档类技能。定期回顾技能库该加的加该删的删。最后分享一个小技巧给每个技能加一个最后验证时间字段记录上次实际跑通是什么时候。超过一个月没验证的技能用之前先跑一遍别直接信。技能依赖的外部环境会变昨天能跑的今天不一定能跑。这套东西还在快速演进今天的最佳实践明天可能就过时了。保持关注但别追新追到忘了目的——目的是让 agent 帮你把活干好不是收集技能。