agent-skills 实战：为 AI coding agents 打造专属技能插件

1. 从装完就吃灰说起agent-skills 到底解决了什么问题如果你最近半年在折腾 AI coding agents大概率经历过这个循环兴冲冲装好 Claude Code 或者 Cursor敲了几个 prompt觉得也就那样然后它就安静地躺在终端里吃灰了。问题往往不在模型本身而在于你给它的技能包太薄——它不知道你的项目结构、不知道你的代码规范、不知道你团队那套祖传的提交信息格式。agent-skills这个项目本质上就是给 AI coding agents 装技能插件的一套机制和 CLI 工具。你可以把它理解成给 agent 写的岗位说明书 操作手册一个 skill 就是一份结构化的能力描述告诉 agent 在特定场景下该读哪些文件、按什么流程走、输出什么格式。它不是一个模型也不是一个 IDE而是一层夹在 agent 和你项目之间的能力中间层。我最初接触这个概念是在 Claude Code 的 skills 机制里后来发现 Cursor、以及一批基于开源模型搭建的 agent 客户端都在往这个方向靠。核心诉求很一致让 agent 从通用聊天机器人变成懂你项目的专属助手。适合谁来参考三类人一是天天用 Claude Code / Cursor 但只会基础对话的开发者二是想给团队统一 AI 编码规范的 tech lead三是想基于开源模型自建 agent 工作流的折腾党。哪怕你只是刚装完 Claude Code 的新手理解 skills 这套东西也能让你的使用效率翻好几倍。2. agent-skills 的整体设计与思路拆解2.1 为什么是技能而不是更长的 prompt很多人第一反应是我直接把要求写进 prompt 不就行了我试过一个 2000 字的系统提示词塞满项目规范结果是每次对话都要重复粘贴token 烧得飞快而且模型对超长 prompt 的注意力是衰减的——越靠后的规则越容易被忽略。skills 的思路是把这些规则外置、模块化、按需加载。一个 skill 通常是一个目录里面有一个描述文件声明这个技能叫什么、什么时候触发、需要哪些工具权限加上若干参考文档或脚本。agent 在运行时根据当前任务判断要不要加载这个技能需要时才把内容读进上下文。这样做的好处很直接省 token不相关的技能不加载上下文窗口留给真正要处理的代码。可复用写一次技能所有项目、所有会话都能用。可组合一个代码审查技能可以调用Git 规范技能形成能力链。可版本化技能文件进 Git团队共享改一次全员生效。这跟传统 prompt engineering 的区别有点像把常用函数抽成库和每次重写一遍的区别。2.2 技能触发的两种主流机制目前 agent-skills 生态里触发方式主要有两类理解这个对你设计自己的技能很关键。第一类是描述匹配触发。技能描述文件里写一段自然语言说明比如当用户要求生成数据库迁移脚本时使用本技能。agent 在收到任务后会拿任务去和所有已安装技能的描述做语义匹配命中就加载。这种方式灵活但对描述文案的质量要求高——写得太模糊会误触发写得太窄又永远不触发。第二类是显式调用触发。用户在对话里直接点名比如输入/review或者提到技能名。这种方式确定性最强适合那些我知道现在就该用它的场景。实际用下来我的经验是两者结合高频、边界清晰的技能用显式调用比如提交信息生成需要 agent 自己判断的用描述匹配比如检测到你在改 SQL 文件就自动加载数据库规范。2.3 目录结构一个 skill 长什么样虽然不同 agent 客户端的实现细节有差异但一个 skill 的骨架大同小异。下面是我自己项目里常用的一个结构你可以直接抄.agent-skills/ ├── code-review/ │ ├── SKILL.md # 技能主描述含触发条件和流程 │ ├── checklist.md # 审查清单 │ └── examples/ # 正反例 ├── commit-message/ │ ├── SKILL.md │ └── template.txt └── db-migration/ ├── SKILL.md └── rules.mdSKILL.md是核心通常包含三段元信息名称、描述、触发条件、执行流程分步骤说明 agent 该做什么、约束不能做什么、必须遵守什么。这个结构不是随便定的——元信息给匹配器用流程给模型用约束给护栏用各司其职。提示技能目录的命名尽量用英文小写加连字符避免空格和中文。很多 CLI 工具在扫描目录时对特殊字符处理不一致我踩过中文目录名导致技能加载失败的坑。3. 核心细节解析与实操要点3.1 SKILL.md 的写法把 agent 当新人带写 SKILL.md 最大的误区是把它写成需求文档。它不是给人看的是给模型看的所以要遵循模型友好的写法。我的几条实战原则第一用祈使句别用描述句。写检查所有新增函数是否有单元测试不要写本技能用于检查单元测试覆盖率。前者是命令模型执行起来更干脆。第二流程要分步骤编号。模型对有序步骤的遵循度明显高于大段散文。一个审查技能我会写成读取本次 diff 涉及的所有文件对每个文件检查命名规范见 rules.md检查是否有硬编码的密钥或路径按 checklist.md 逐项核对输出问题列表按严重程度排序第三明确输出格式。如果你希望 agent 输出 Markdown 表格就在技能里写清楚列名。我见过太多人抱怨agent 输出格式乱其实是因为技能里根本没规定格式。第四给出正反例。在examples/里放一两个好的输出和坏的输出模型模仿能力很强这比写十条规则都管用。3.2 权限与工具声明别让技能越权这是最容易被忽视、但出事最狠的地方。一个技能如果声明了文件写入权限agent 在加载它之后就真的能改你的文件。我在早期给一个自动修复 lint技能开了全盘写权限结果它顺手修复了我一个故意留着的兼容性写法差点提交上去。正确的做法是最小权限只读技能就只声明读需要写就限定目录。Claude Code 这类客户端在技能加载时会弹权限确认别嫌烦认真看它要什么权限。下面是我总结的权限对照技能类型建议权限风险点代码审查只读基本无风险提交信息生成只读 读取 git 历史无自动格式化写入限定目录误改无关文件依赖升级写入 执行命令命令注入、版本冲突数据库迁移写入 执行命令高危务必人工确认注意任何涉及执行 shell 命令的技能都要在 SKILL.md 里写死允许的命令白名单。我见过有人图省事写可以执行任何必要命令这等于把终端交给了模型。3.3 技能之间的组合与依赖单个技能能力有限真正的威力在组合。比如一个发布新版本的复合任务可以拆成changelog技能生成变更日志 →version-bump技能改版本号 →commit-message技能生成提交信息 →tag技能打标签。组合有两种实现方式。一种是技能内引用在 SKILL.md 里写完成本步骤后加载 commit-message 技能。另一种是编排层由 agent 自己根据任务规划调用哪些技能。前者可控性强后者灵活但容易乱。我的建议是关键路径用显式引用探索性任务交给 agent 自己编排。发布流程这种一步错步步错的必须写死顺序而帮我重构这个模块这种开放任务让 agent 自己决定用哪些技能反而效果更好。3.4 跨客户端兼容Claude Code、Cursor 与开源 agent热词里反复出现 Claude Code 和 Cursor说明大家最关心的就是这两个平台。它们的 skills 机制有共性也有差异。Claude Code 的 skills 更偏向文件系统 描述匹配技能放在约定目录里启动时扫描。它的优势是技能可以很复杂包含脚本和多文件劣势是配置相对重。Cursor 这边skills 的概念更多体现在 Rules 和自定义指令上配合它的 agent 模式使用。它的优势是 IDE 内集成好改完即时生效劣势是跨项目复用不如文件系统方案方便。开源模型搭的 agent比如接 DeepSeek 的那些通常需要你自己实现技能加载逻辑灵活度最高但什么都得自己写。一个实用的兼容策略是把技能内容写成纯 Markdown元信息用 YAML front matter。这样同一份技能文件稍作调整就能在多个平台用。下面是个 front matter 示例--- name: code-review description: 当用户要求审查代码或提交 PR 前使用 trigger: explicit tools: - read_file - list_dir ---4. 实操过程与核心环节实现4.1 环境准备与 skills CLI 安装假设你已经在用 Claude Code 或者 Cursor第一步是确认你的客户端版本支持 skills。Claude Code 较新的版本原生支持Cursor 需要开启 agent 模式。skills CLI 这类工具的作用是帮你管理技能安装、列出、启用、禁用、更新。典型用法是全局安装后在项目里初始化技能目录。我一般会这样做# 全局安装 skills 管理工具以 npm 生态为例 npm install -g agent-skills-cli # 在项目根目录初始化 cd your-project agent-skills init # 安装一个社区技能 agent-skills install code-review # 列出当前已安装技能 agent-skills list初始化之后项目里会多出一个技能目录。这时候别急着装一堆技能先装一两个高频的跑通了再扩。提示如果你在 Ubuntu 或者 Win11 上折腾注意路径分隔符和权限问题。Win11 下建议在 WSL 里操作避免一堆莫名其妙的路径错误。Mac 用户相对省心但要注意别把技能目录放在 iCloud 同步盘里同步冲突会让技能文件损坏。4.2 手写第一个技能提交信息生成器光装别人的技能不够真正提升效率的是写自己的。我拿提交信息生成这个最实用的场景带你走一遍完整流程。第一步建目录。在技能根目录下建commit-message/。第二步写 SKILL.md。内容大致如下--- name: commit-message description: 当用户要求生成 git 提交信息时使用 trigger: explicit tools: - read_file - run_git --- # 提交信息生成 ## 流程 1. 执行 git diff --staged 获取暂存区变更 2. 执行 git log --oneline -10 了解历史提交风格 3. 按以下格式生成提交信息 ## 格式 type(scope): subject body ## 约束 - type 只能是 feat/fix/docs/style/refactor/test/chore - subject 不超过 50 字符用中文 - 不编造 diff 里没有的变更第三步测试。暂存几个文件然后让 agent 生成提交信息。第一次大概率不完美根据输出调整 SKILL.md迭代两三轮就稳了。第四步进 Git。把整个技能目录提交到仓库团队成员拉下来就能用。这个流程走一遍你就理解了 skills 的核心工作方式。后面写再复杂的技能都是这个套路的延伸。4.3 参数与阈值的选择以代码审查技能为例代码审查技能里有一堆需要拍脑袋的参数我把我调过的几个关键值分享出来省得你从零试。diff 行数阈值。如果一次审查的 diff 超过 800 行模型容易漏看后面的内容。我的做法是在技能里写若 diff 超过 800 行先按文件分组逐个审查。这个 800 不是玄学是实测下来模型注意力还比较集中的上限你可以根据自己的模型调整。问题严重程度分级。我分三级blocker必须改比如安全漏洞、major应该改比如逻辑错误、minor可选比如命名。分级的好处是输出有优先级人看起来不累。误报容忍度。审查技能最烦的是误报。我在技能里加了一条若不确定是否为问题标注为 minor 并说明不确定原因这样既不会漏也不会把 minor 当 blocker 吓人。下面是我常用的审查清单表格直接放进checklist.md检查项级别说明硬编码密钥/路径blocker任何明文凭证未处理的异常majortry 块无 catch 或空 catch函数超过 80 行minor建议拆分魔法数字minor未提取为常量缺少单元测试major新增公共函数4.4 把技能接入日常工作流技能写好了怎么让它真正融入日常我的做法是绑定到几个固定动作上提交前显式调用 commit-message 技能。开 PR 前显式调用 code-review 技能把输出贴进 PR 描述。改数据库文件时描述匹配自动加载 db-migration 技能。每周五跑一次 changelog 技能汇总本周变更。关键是别贪多。我一开始装了十几个技能结果 agent 每次都要在匹配上花时间反而变慢。现在稳定在五六个高频技能体验最好。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法描述匹配技能从不触发描述太窄或太模糊手动测试描述与任务的语义相似度显式调用报技能不存在目录名或技能名拼写不符用 list 命令核对实际名称技能加载了但没效果SKILL.md 格式错误检查 front matter 的 YAML 缩进时灵时不灵描述与其他技能冲突精简描述避免关键词重叠我踩过最坑的一次是 YAML front matter 里用了 Tab 缩进YAML 规范不允许 Tab导致整个技能被静默跳过连报错都没有。后来养成习惯写完技能先用agent-skills validate校验一遍。5.2 技能输出不稳定同一个技能有时输出很规范有时又跑偏。原因通常是技能内容太长关键约束被淹没。解决办法是把最重要的约束放在 SKILL.md 最前面或者单独抽成一个constraints.md并在流程里显式引用。另一个原因是模型温度设置。如果你用的是可调温度的客户端审查类技能建议调低温度创意类技能可以调高。这个在技能层面控制不了得在客户端配置里改。5.3 团队协作中的技能管理多人用同一套技能最容易出的是版本漂移——有人改了技能没提交有人本地是旧版。我的做法是技能目录必须进 Git和代码同仓库。技能改动走 PR 流程至少一人 review。在 CI 里加一步agent-skills validate格式错误直接挂掉。这样能保证所有人用的技能是一致的。别小看这一步我见过因为技能版本不一致导致两个人对同一段代码的审查结论完全相反的尴尬场面。5.4 安全红线哪些技能绝对不能开自动执行最后说个严肃的。有几类技能无论多方便都不要开自动执行必须人工确认每一步任何执行数据库写操作的技能任何执行git push或打标签的技能任何安装/升级依赖的技能任何涉及生产环境配置的技能我的原则是读操作可以自动写操作必须确认。这条线守住skills 就是个提效工具守不住它就是个定时炸弹。6. 技能库的长期维护与扩展思路技能这东西写起来容易维护起来才是真功夫。我现在的做法是给每个技能标一个最后验证日期超过三个月没验证的要么更新要么删掉。因为模型在迭代客户端在迭代三个月前的技能很可能已经不适配了。扩展方向上我最近在试的是技能的分层基础层放通用规范命名、格式项目层放项目特有规则个人层放自己的偏好。三层叠加既保证团队一致又保留个人空间。这个思路还在打磨但初步跑下来比一个技能包打天下要清爽得多。另外社区技能可以装但别直接用。我一般会先读一遍 SKILL.md把里面不符合自己习惯的部分改掉再用。毕竟技能是给 agent 下命令的命令写错了agent 执行得越认真坑越大。