agent-skills 实战：为 AI coding agent 构建可复用技能系统

1. 从装完就吃灰说起agent-skills 到底解决了什么问题我装过不少 AI coding agentClaude Code、Cursor、还有几个开源方案都折腾过。说实话前两周新鲜劲一过大部分时间它们就是个高级补全——你问一句它答一句遇到稍微复杂的任务还是得自己拆步骤、自己写提示词、自己检查输出。问题出在哪不是模型不行是这些 agent 缺少一套可复用、可组合、可版本管理的技能包。agent-skills这个项目本质上就是给 AI coding agent 装上一套标准化的技能系统。你可以把它理解成给 agent 写的插件规范 技能仓库 CLI 管理工具三件套。它要解决的核心痛点很具体每次让 agent 做同一类任务比如按团队规范生成 commit message自动补全单元测试按项目约定重构目录结构你都得重新描述一遍需求agent 每次表现还不稳定。agent-skills 把这些重复性的能力沉淀成独立的 skill 文件通过一个skillsCLI 统一安装、分发、调用。适合谁看三类人。第一类是把 Claude Code、Cursor 当主力开发工具但觉得还不够顺手的开发者第二类是团队里负责工程效率、想统一 AI 辅助编码规范的技术负责人第三类是对 agent 架构感兴趣想自己写 skill 扩展的折腾党。不管你是刚装完 Claude Code 还在研究怎么配置的新手还是已经在 Cursor 里写了几百条 rules 的老手这套东西都能让你的 agent 从能用变成好用。我实测下来最大的感受是agent-skills 把提示词工程从一次性消耗品变成了可维护的工程资产。以前你写一段复杂的 prompt 让 agent 重构代码用完就丢了现在你可以把它固化成一个 skill下次一句话调用输出质量还稳定。这个转变的价值比多装一个插件大得多。2. agent-skills 的整体设计思路拆解2.1 为什么是技能而不是提示词模板很多人第一反应是这不就是提示词模板吗我建个文件夹存一堆 prompt 不就行了区别在于三个层面。第一结构化。一个 skill 不是一段裸文本它包含元数据名称、描述、触发条件、依赖、执行逻辑步骤定义、工具调用声明、以及输出规范。这跟单纯存一段 prompt 是两码事。元数据让 agent 能知道自己在什么场景下该用哪个 skill而不是靠你每次手动指定。第二可组合。skill 之间可以互相引用。比如你有一个代码审查skill它可以调用安全检查skill 和风格检查skill最后汇总输出。这种组合能力是裸 prompt 做不到的因为你没法让一段文本去调用另一段文本。第三可版本管理。skill 是文件可以进 Git可以 review可以回滚。团队里谁改了什么 skill、为什么改都有记录。prompt 模板散落在各人手里改了什么根本不知道。提示如果你现在还在用复制粘贴 prompt的方式管理 AI 辅助流程agent-skills 的思路值得认真看一下。它解决的不是能不能用的问题是能不能规模化、可持续用的问题。2.2 skills CLI 的设计取舍skillsCLI 是这个项目的入口工具。它的设计思路很克制没有搞一堆花哨的功能核心就四件事安装、列出、更新、移除。为什么不做成图形界面因为目标用户是开发者他们本来就活在终端里。Claude Code 是终端工具Cursor 虽然有自己的界面但开发者照样开终端跑命令。CLI 的另一个好处是可脚本化——你可以在 CI 里跑skills install在项目初始化脚本里自动装好团队标准 skill 集这是 GUI 做不到的。安装机制上skills CLI 支持从远程仓库拉取 skill 包也支持本地路径安装。远程拉取用的是标准的包管理思路有 registry、有版本号、有依赖解析。本地安装则方便你在开发 skill 时快速迭代测试。这个双模式设计很实用我写自己的 skill 时就是本地装、改一次测一次稳定了再推到远程。2.3 与 Claude Code、Cursor 的集成方式agent-skills 不是要取代 Claude Code 或 Cursor它是寄生在它们之上的能力层。集成方式因工具而异。对 Claude Code 来说skill 本质上是一组约定格式的文件放在特定目录下Claude Code 启动时会扫描并加载。你在对话里提到相关任务时agent 会自动匹配并调用对应 skill。这跟 Claude Code 原生的自定义指令有点像但 agent-skills 提供了更完整的生命周期管理。对 Cursor 来说集成稍微绕一点。Cursor 有自己的 rules 系统和.cursorrules文件agent-skills 的做法是把 skill 内容转换成 Cursor 能识别的格式或者通过 MCPModel Context Protocol这类协议桥接。实测下来Cursor 用户更多是把 agent-skills 当作skill 仓库来用手动把需要的 skill 内容同步到项目配置里。注意不同版本的 Claude Code 和 Cursor 对 skill 的支持程度不一样。装之前先确认你的工具版本老版本可能不认新的 skill 格式。这个坑我踩过折腾半天发现是版本问题。3. 核心细节解析与实操要点3.1 skill 文件的目录结构与关键字段一个标准的 skill 目录长这样my-skill/ ├── skill.yaml # 元数据与触发配置 ├── prompt.md # 核心提示词内容 ├── steps/ # 分步骤执行定义可选 │ ├── 01-analyze.md │ └── 02-generate.md └── resources/ # 辅助资源模板、示例等 └── template.txtskill.yaml是最关键的。它定义了 skill 的身份name: commit-message-generator version: 1.2.0 description: 根据 git diff 生成符合团队规范的 commit message triggers: - 生成 commit - 写提交信息 - commit message dependencies: - git-context-reader output_format: text几个字段值得展开说。triggers是触发词列表agent 会根据用户输入匹配这些词来决定是否调用该 skill。这里有个经验触发词不要写太泛比如只写生成会导致误触发也不要写太窄否则用户换个说法就匹配不上。我一般会写 3-5 个不同表述的触发词覆盖常见说法。dependencies声明了这个 skill 依赖的其他 skill。安装时会自动解析并拉取依赖类似 npm 的依赖管理。这个机制让 skill 可以复用不用每个都从头写。output_format告诉 agent 期望的输出类型常见的有text、markdown、json、code。设对了能让 agent 的输出更符合预期设错了可能导致解析失败。3.2 触发机制agent 怎么知道该用哪个 skill这是很多人困惑的点。agent-skills 的触发不是简单的关键词匹配而是语义匹配 显式调用双通道。语义匹配是 agent 根据 skill 的description和triggers字段结合当前对话上下文判断是否相关。比如你说帮我把这些改动提交一下agent 看到有commit-message-generator这个 skill描述是根据 git diff 生成 commit message就会自动调用。显式调用则是你直接说用 commit-message-generator 这个 skill。当你发现自动匹配不准时显式调用是兜底方案。实测下来语义匹配的准确率跟 skill 的description写得好不好直接相关。描述要写做什么而不是是什么。写commit message 生成器不如写根据 git diff 内容生成符合 Conventional Commits 规范的提交信息。后者包含了场景、输入、输出规范agent 匹配起来准得多。3.3 参数传递与上下文注入skill 执行时需要拿到上下文比如当前项目的 git diff、文件内容、目录结构。agent-skills 通过上下文注入机制解决这个问题。在skill.yaml里可以声明需要哪些上下文context: - type: git_diff required: true - type: file_tree required: false depth: 2agent 在执行 skill 前会先收集这些上下文注入到 prompt 里。这样 skill 的 prompt 就不用写请先读取 git diff这种话了直接假设上下文已经就绪。这个设计的好处是skill 的 prompt 可以写得很干净只关注核心逻辑。坏处是如果上下文收集失败比如不在 git 仓库里skill 会直接报错。所以写 skill 时要想好required设 true 还是 false非必需的上下文设 false 能让 skill 在更多场景下可用。3.4 版本管理与依赖解析skill 的版本管理用的是语义化版本SemVer。1.2.0表示主版本 1、次版本 2、补丁版本 0。当 skill A 依赖 skill B 时可以指定版本范围dependencies: - name: git-context-reader version: 1.0.0 2.0.0安装时 skills CLI 会解析依赖树找到满足所有约束的版本组合。如果出现冲突A 要 B1.xC 要 B2.xCLI 会报错让你手动解决。这个机制跟 npm、pip 是一样的思路用过包管理的人应该很熟悉。实操心得写团队内部 skill 时依赖尽量用宽松的版本范围比如^1.0.0避免因为某个底层 skill 小版本更新导致一堆上层 skill 装不上。但如果是生产环境关键 skill锁死版本1.2.3更稳妥。4. 完整实操流程从零装好一套 skill 并跑通4.1 环境准备与 skills CLI 安装先确认基础环境。Claude Code 或 Cursor 至少装好一个Node.js 18 是 skills CLI 的运行依赖。# 检查 Node 版本 node -v # 应该输出 v18.x.x 或更高 # 全局安装 skills CLI npm install -g agent-skills/cli # 验证安装 skills --version如果 npm 全局安装遇到权限问题Linux/macOS 常见有两个方案一是用nvm管理 Node 环境避免权限问题二是改 npm 全局目录到用户目录下。Windows 用户如果用 PowerShell 遇到执行策略限制需要先Set-ExecutionPolicy RemoteSigned。安装完成后skills命令就可用了。第一次运行可能会提示你配置 registry 地址默认用官方源即可。如果你在公司内网可能需要配置私有 registry这个在~/.skillsrc里改。4.2 安装第一个 skill 并验证拿最常用的代码审查skill 练手# 搜索可用 skill skills search code-review # 安装 skills install code-review # 查看已安装列表 skills list安装完成后skill 文件会落在~/.agent-skills/目录下具体路径因系统而异skills list会显示。这时候打开 Claude Code在项目里说一句帮我审查一下这段代码如果 skill 装对了agent 会调用 code-review skill 而不是用默认方式回答。怎么判断 skill 真的生效了看 agent 的输出结构。用了 skill 的输出通常更结构化有明确的检查项、分级的问题列表、修复建议。没用 skill 的输出比较随意。我一般会故意写一段有明显问题的代码测试看 agent 能不能按 skill 定义的流程逐项检查。4.3 写一个自己的 skill以生成单元测试为例光用别人的 skill 不够真正有价值的是写自己团队的 skill。完整流程如下。第一步创建目录结构mkdir -p my-skills/unit-test-generator/steps cd my-skills/unit-test-generator第二步写skill.yamlname: unit-test-generator version: 1.0.0 description: 根据选中的函数或类生成单元测试遵循项目现有测试风格 triggers: - 生成单元测试 - 写测试 - 补测试用例 context: - type: selected_code required: true - type: test_framework required: false output_format: code第三步写prompt.md你是一个测试工程师。根据以下代码生成单元测试。 要求 1. 先分析代码的分支和边界条件 2. 覆盖正常路径、边界值、异常输入三类场景 3. 测试命名遵循 should_预期结果_when_条件 格式 4. 使用项目已有的测试框架和断言风格 5. 如果代码依赖外部服务使用 mock 代码 {{selected_code}} 测试框架{{test_framework}}第四步本地安装测试skills install ./my-skills/unit-test-generator --local第五步在 Claude Code 里选中一段代码说生成单元测试看输出是否符合预期。不符合就改prompt.md重新skills install --local覆盖安装再测。这个迭代循环很快我一般改三五轮就能稳定。4.4 团队分发与 CI 集成skill 写好了怎么让团队都用上两种方式。轻量方式把 skill 目录推到团队 Git 仓库在项目 README 里写一句运行skills install repo-url安装团队 skill 集。新人入职照着做就行。重度方式在 CI 里集成。比如在项目初始化脚本里加skills install team-standard-skills^2.0.0这样每次新环境搭建都会自动装好标准 skill。更进一步可以在 CI 的 lint 阶段检查 skill 版本是否符合要求避免有人用了过时的 skill 导致输出不一致。注意团队分发 skill 时一定要在 skill 里写清楚这个 skill 假设项目用了什么技术栈、什么规范。我见过有人把 React 项目的 skill 装到 Vue 项目里agent 生成了一堆 React 代码哭笑不得。5. 常见问题与排查技巧实录5.1 skill 装了但 agent 不调用这是最高频的问题。排查顺序如下排查项检查方法常见原因skill 是否真的装上了skills list看列表安装路径不对或权限问题触发词是否匹配换几种说法试试触发词写太窄description 是否清晰读一遍 skill.yaml描述太模糊agent 匹配不上agent 版本是否支持查工具文档老版本不认新 skill 格式是否被其他 skill 抢占看 agent 实际调了哪个多个 skill 触发词重叠我遇到最多的是触发词问题。有次写了个 skill 触发词只写了重构结果用户说优化一下这段代码就匹配不上。后来加了优化改进整理几个词命中率立马上来了。5.2 skill 输出质量不稳定同一个 skill有时候输出很好有时候一塌糊涂。原因通常有三个。一是上下文注入不完整。比如 skill 需要 git diff 但当前不在 git 仓库里agent 拿不到上下文就瞎编。解决办法是把非必需上下文设required: false并在 prompt 里写如果上下文缺失先询问用户。二是prompt 里的指令有歧义。比如写生成简洁的代码简洁是主观的agent 每次理解不一样。改成生成不超过 20 行的代码每个函数只做一件事就稳定多了。三是模型本身的随机性。这个没法完全消除但可以通过在 prompt 里加严格按照以下步骤执行、给出具体示例来降低波动。实测加了示例后输出一致性提升明显。5.3 依赖冲突怎么解skill A 要utils1.xskill B 要utils2.x装不上。解决方案按优先级排看能不能升级 A 或 B 到兼容utils2.x的版本如果 A 是内部 skill改它的依赖声明测试兼容性实在不行把utils的两个版本都装上用命名空间隔离skills CLI 支持这个但配置麻烦最后手段fork 一个utils改个名让 A 和 B 各用各的实操心得依赖冲突预防大于解决。写 skill 时依赖尽量少能用原生能力就别引第三方 skill。我见过一个 skill 依赖了七八个底层 skill结果每次底层更新它都要跟着改维护成本极高。5.4 性能问题skill 太多导致 agent 变慢装了几十个 skill 后agent 每次对话都要扫描所有 skill 做匹配响应明显变慢。解决办法按项目类型分组不同项目只装相关 skill。比如前端项目不装后端相关的 skill定期清理不用的 skillskills list看哪些很久没触发过把低频 skill 设为手动触发不参与自动匹配我自己的习惯是全局只装 5-8 个通用 skill项目级的 skill 放在项目目录下按需加载。这样既不影响匹配速度又能保证项目特定需求被覆盖。5.5 跨工具兼容性坑同一个 skill 在 Claude Code 里跑得好换到 Cursor 就出问题。主要原因是两个工具对 skill 格式的支持有差异。Claude Code 对 skill 的原生支持更完整Cursor 需要通过转换层。我的做法是skill 的核心逻辑prompt.md写成工具无关的把工具特定的配置触发方式、上下文注入格式放在单独的适配文件里。这样换工具时只改适配层核心逻辑不用动。虽然多写一个文件但长期看省事得多。6. 我踩过的坑和几条实在建议写 skill 这件事看起来简单真上手坑不少。分享几条我实际踩过的。第一条别一上来就写复杂 skill。我最初想写一个全自动重构skill结果 prompt 写了三百行agent 执行时各种跑偏。后来拆成分析代码结构生成重构方案执行重构三个独立 skill每个都简单清晰组合起来效果反而好。skill 的设计哲学应该是小而专不是大而全。第二条skill 的 prompt 要像写给新人的操作手册。你想象一个刚入职的工程师他技术没问题但不了解你的项目规范。你的 prompt 要写到他能照着做的程度。模糊的指令比如按最佳实践写等于没写具体的指令比如函数不超过 30 行参数不超过 4 个错误处理用 Result 类型才有用。第三条给 skill 写测试。对skill 也需要测试。我建了一个test-cases/目录每个 skill 配几个输入输出样例。改完 skill 后跑一遍看输出是否还符合预期。这个习惯帮我避免了好几次改一个 skill 把另一个功能搞坏的事故。第四条关注 skill 的失败模式。每个 skill 都有它搞不定的情况。比如代码审查 skill 遇到超长文件可能截断测试生成 skill 遇到复杂依赖可能生成跑不通的测试。提前想好这些情况怎么处理——是报错、是降级、还是提示用户手动介入——比事后救火强。第五条skill 的文档和 skill 本身一样重要。一个 skill 如果没有清晰的 README 说明它做什么、怎么用、有什么限制别人根本不敢用。我现在的习惯是每个 skill 必须配 README包含使用示例和已知限制。写文档花的时间会在别人包括三个月后的自己使用时加倍省回来。最后说个观察agent-skills 这类工具的价值会随着你积累的 skill 数量增长而指数级上升。刚开始只有两三个 skill 时感觉跟手动写 prompt 差别不大当你有二十个覆盖日常开发各环节的 skill 时整个 AI 辅助编码的体验就完全不一样了——agent 真的变成了一个了解你项目、了解你习惯的团队成员而不是一个每次都要重新调教的工具。这个从量变到质变的过程值得花时间投入。