1. 从“agent-skills”说起为什么我们需要给AI编码代理装上技能包第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给AI编码代理AI coding agents定义、管理和分发“技能”的机制。你可以把它理解成给一个刚入职的聪明实习生发一本《岗位操作手册》手册里写清楚什么场景该做什么、按什么步骤做、做完怎么验证。没有这本手册实习生也能干活但干出来的活质量忽高忽低换个项目就得重新教一遍。agent-skills要解决的核心问题就是这个。它不是一个模型也不是一个IDE插件而是一套围绕skills CLI构建的技能描述、加载与执行体系。你写一个技能文件声明这个技能叫什么、什么时候触发、需要哪些工具、执行哪些步骤、如何验证结果然后通过命令行工具把它注册到你的AI编码代理里。之后你在Claude Code这类代理环境中工作时代理就能按需调用这些技能而不是每次都靠你临时写一大段提示词。我为什么对这个方向特别上心因为过去大半年我一直在用各种AI编码代理做实际项目踩过的坑非常集中同一个任务今天让它做和明天让它做结果可能完全不同。你以为是模型不稳定其实很多时候是“上下文里缺少稳定的操作约定”。agent-skills这类项目试图把“操作约定”从你的脑子里、从聊天记录里抽出来变成可版本管理、可复用、可测试的资产。这跟test-driven-development的思路是一脉相承的——先把验收标准写下来再让执行者去满足它。这篇文章适合谁看如果你已经在用 Claude Code、Cursor、Windsurf 或者其他AI编码代理并且开始觉得“每次都要重新解释一遍很烦”那这篇就是写给你的。如果你还没入门但听说过claude code安装、vscode配置claude code这些词想搞清楚这套东西到底怎么落地也可以跟着看我会把基础概念和实操步骤都铺开讲。全文围绕agent-skills这个核心把技能体系的设计思路、CLI 的用法、与 Claude Code 的配合、以及我实际踩过的坑一次讲透。2. 技能体系整体设计为什么是“技能”而不是“提示词”2.1 提示词的天花板在哪里刚开始用AI编码代理的时候几乎所有人都是从写提示词开始的。你打开对话框敲一段话“帮我在这个项目里加一个用户登录接口用现有的数据库连接写单元测试跑通再提交。”代理吭哧吭哧干完你看一眼还行。第二天你换个项目又敲一遍类似的话但这次它把测试文件放错目录了或者用了另一个ORM的写法。问题出在哪儿提示词是一次性的、上下文绑定的、不可测试的。它活在聊天记录里项目一换、会话一断就归零了。你可能会说那我把它存成一个模板不就行了存成模板确实进了一步但模板还是“一段文本”它没有结构没有触发条件没有工具依赖声明也没有验证步骤。代理拿到模板仍然需要自己“理解”该干什么。agent-skills的思路是把这个过程结构化。一个技能不是一段话而是一个有明确边界的执行单元。它至少包含几个要素技能名称与描述、触发条件、所需工具或权限、执行步骤、验证方式、以及可选的示例。这跟传统软件工程里的“函数”或“模块”很像——有输入、有输出、有契约。2.2 技能与提示词、工作流、插件的区别这里容易混淆我用自己的理解拆一下概念本质复用性可测试性典型载体提示词一次性自然语言指令低无聊天框提示词模板带变量的文本片段中弱文本文件工作流多步骤编排中高中YAML/脚本插件扩展代理能力高强代码包技能带触发与验证的能力单元高强技能文件CLI技能介于工作流和插件之间。它比工作流更“自包含”比插件更“轻”。你不需要写一个完整的插件包只需要按约定写一个技能描述文件然后用skills CLI注册。代理在运行时根据当前任务匹配技能匹配上了就按技能里写的步骤执行。2.3 为什么选择 CLI 作为入口agent-skills选择skills CLI作为主要交互方式这个决策我认为非常务实。原因有三点。第一CLI 天然适合自动化和版本管理。技能文件放在仓库里用 git 管理CI 里可以跑校验团队成员拉下来就能用。第二CLI 不绑定具体编辑器。你可以在 VS Code 里用也可以在终端里用甚至可以在 CI 流水线里用。第三CLI 的“显式调用”特性让调试变得简单——你可以单独跑一个技能看它输出什么而不是在一大段代理对话里猜。提示如果你之前只用过图形界面的AI编码工具建议先花半小时熟悉一下终端里的基本操作。技能体系的大量操作都在命令行里完成图形界面只是辅助。2.4 与 test-driven-development 的深层关联热词里出现了test-driven-development这不是偶然。技能体系要真正可靠必须解决“怎么知道技能执行对了”这个问题。TDD 的思路在这里非常适用先写验证再写执行。一个设计良好的技能应该把验证步骤作为技能定义的一部分。比如“添加API接口”这个技能验证步骤可能是“运行单元测试且全部通过”“用 curl 请求接口返回200”“检查数据库表结构符合预期”。代理执行完技能后自动跑这些验证不通过就重试或报告。这样你就不需要每次人工检查技能本身具备了“自我验收”的能力。我在实际项目里把技能和 TDD 结合之后最明显的感受是代理的“返工率”下降了。以前它经常交出一个看起来对、跑起来错的东西现在因为技能里写死了验证步骤它在提交前会自己先跑一遍很多低级错误在到达我之前就被拦住了。3. 核心细节解析一个技能文件到底长什么样3.1 技能的基本结构由于agent-skills的具体文件格式可能随版本变化这里我基于常见实践和同类工具的设计给出一个典型的技能结构。你可以把它当作参考模板实际使用时以项目文档为准。一个技能通常包含以下字段name技能的唯一标识用短横线连接比如add-rest-endpoint。description一句话说明这个技能做什么代理用它来判断是否匹配当前任务。triggers触发条件可以是关键词、文件类型、或者自然语言描述的场景。tools这个技能需要使用的工具或权限比如文件读写、终端执行、网络请求。steps执行步骤按顺序列出每一步说明做什么、用什么工具、预期结果是什么。verification验证步骤执行完怎么确认成功。examples可选给出输入输出示例帮助代理理解。这个结构的好处是人机都能读。人看一遍就知道这个技能靠不靠谱代理读一遍就知道该怎么执行。3.2 触发条件的设计技巧触发条件是技能体系里最容易被忽视、但影响最大的部分。写得太宽技能会被频繁误触发写得太窄该用的时候用不上。我的经验是触发条件要描述“场景”而不是“关键词”。比如不要写“当用户提到登录时触发”而是写“当任务涉及为现有项目添加用户认证接口且项目已有数据库连接层时触发”。前者太泛后者有明确的上下文约束。另外触发条件里可以引用项目特征。比如“当项目根目录存在package.json且依赖中包含express时”。这样技能就与具体技术栈绑定了不会在 Python 项目里误触发一个 Node.js 技能。3.3 步骤拆分的粒度控制步骤拆得太粗代理自由发挥的空间太大结果不可控拆得太细技能变得冗长维护成本高。我一般遵循“一个步骤一个可验证的动作”原则。举个例子“添加接口”这个技能我会拆成读取现有路由文件确认注册方式。在路由文件中添加新路由引用控制器。创建控制器文件实现处理逻辑。创建或更新数据访问层方法。添加单元测试。运行测试并确认通过。每一步都有明确的输入和输出代理执行时不容易跑偏。如果某一步失败也能快速定位是哪一环出了问题。3.4 工具声明与权限边界agent-skills里技能需要声明它用到的工具这个设计非常重要相当于权限最小化原则。一个只读技能不应该有写文件的权限一个只改前端的技能不应该能执行数据库迁移。在实际配置时我建议把工具声明写得尽量精确。比如需要执行终端命令时不要笼统地写“terminal”而是写清楚需要执行哪些命令比如“npm test”“npm run lint”。这样即使技能被误触发造成的破坏也有限。注意技能的工具权限一旦放开代理就可能在你不注意的时候执行危险操作。生产环境相关的技能务必加上人工确认环节不要让代理全自动执行。3.5 验证步骤的写法验证步骤要具体、可执行、有明确的通过标准。我见过一些技能写“确认代码正确”这等于没写。正确的写法是运行npm test退出码为0。运行curl -X POST localhost:3000/api/login返回状态码200且响应体包含token字段。检查src/routes/目录下新增了对应的路由文件。每一条都能被自动执行和判断这样技能才具备“自验收”能力。4. 实操过程从零搭建一个技能并接入 Claude Code4.1 环境准备与 Claude Code 安装在动手写技能之前得先把运行环境搭好。如果你还没装Claude Code这里简单说一下常见路径。官方提供了多种安装方式macOS 和 Ubuntu 下都可以通过包管理器或官方脚本安装。安装完成后在终端里运行claude命令如果能进入交互界面说明基础环境没问题。VS Code 用户可以在扩展市场里搜索 Claude Code 相关插件安装后在设置里配置好路径和认证信息。如果你用的是第三方模型接入方案比如通过cc switch这类工具切换 DeepSeek、Qwen、GLM 等模型需要额外配置 API 端点和密钥。这部分配置因工具而异核心是让 Claude Code 能正常发起请求并收到响应。提示安装过程中如果遇到网络或认证问题优先检查官方文档里的环境要求。不同操作系统下的依赖略有差异Ubuntu 下可能需要额外安装一些基础库。4.2 初始化技能目录环境就绪后在你的项目根目录下创建一个技能目录。常见做法是放在.agent-skills/或者skills/下。我习惯用.agent-skills/因为点开头的目录在编辑器里默认折叠不会干扰日常浏览。mkdir -p .agent-skills然后在这个目录里创建你的第一个技能文件。文件名建议与技能名一致比如add-rest-endpoint.md或add-rest-endpoint.yaml。具体格式看agent-skills的文档要求这里我用 Markdown 加 frontmatter 的形式举例因为这种格式人读起来最舒服。4.3 编写第一个技能添加 REST 接口下面是我实际在用的一个技能文件简化版。你可以直接抄过去改。--- name: add-rest-endpoint description: 为现有 Express 项目添加一个 REST 接口包含路由、控制器、数据访问和测试 triggers: - 当任务要求添加新的 API 接口 - 当项目根目录存在 package.json 且依赖包含 express tools: - read_file - write_file - run_command: npm test - run_command: npm run lint steps: - 读取 src/routes/index.js确认路由注册方式 - 在路由文件中添加新路由指向新控制器 - 创建 src/controllers/name.controller.js实现处理逻辑 - 在 src/services/ 下添加或更新数据访问方法 - 在 tests/ 下添加对应的单元测试文件 - 运行 npm test确认全部通过 - 运行 npm run lint确认无错误 verification: - npm test 退出码为 0 - npm run lint 退出码为 0 - 新路由文件存在于 src/routes/ 目录 - 新控制器文件存在于 src/controllers/ 目录 examples: - input: 添加一个 GET /api/users/:id 接口 output: 生成路由、控制器、服务方法和测试测试通过 ---这个文件写完之后用skills CLI注册它。具体命令看工具文档通常是skills add .agent-skills/add-rest-endpoint.md或者类似形式。注册成功后代理在遇到匹配任务时就会自动加载这个技能。4.4 用 skills CLI 管理技能生命周期技能不是写完就完了还需要管理。skills CLI一般提供这些操作skills list列出当前已注册的技能。skills add file注册一个新技能。skills remove name移除技能。skills validate file校验技能文件格式是否正确。skills test name单独运行某个技能的验证步骤。我强烈建议在 CI 里加上skills validate每次提交技能文件时自动校验格式。这样能避免因为格式错误导致技能加载失败而你在实际使用时才发现。4.5 在 Claude Code 中调用技能技能注册好之后在 Claude Code 里怎么用有两种方式。一种是自动匹配。你正常描述任务代理根据触发条件自动匹配技能。比如你说“帮我加一个查询订单的接口”代理检测到项目是 Express 且任务匹配add-rest-endpoint就会加载这个技能并按步骤执行。另一种是显式调用。你直接说“用 add-rest-endpoint 技能来做这件事”代理就会强制加载指定技能。调试阶段我建议用显式调用这样你能清楚看到技能是否按预期执行。4.6 参数计算与选择过程技能里有些步骤可能涉及参数选择比如分页大小、超时时间、重试次数。这些参数不应该硬编码在技能里而应该作为技能输入。我的做法是在技能定义里加一个parameters段声明这个技能接受哪些参数、默认值是什么、取值范围是什么。代理在调用技能时根据任务上下文填充这些参数。比如分页接口默认每页20条最大100条这些都可以在技能里声明。这样技能就具备了可配置性同一个技能能适应不同项目的需求而不需要为每个项目复制一份。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最常见的问题。你写了一个技能但代理就是不用。排查思路如下第一检查触发条件是否太窄。把触发条件里的关键词放宽一点或者增加几个同义场景描述。第二检查技能是否真的注册成功了。运行skills list确认。第三检查项目特征是否匹配。如果技能要求package.json存在而你的项目用的是pyproject.toml那自然不会触发。我遇到过一次技能写得好好的就是不触发。后来发现是技能文件里的 frontmatter 格式有误YAML 解析失败了但 CLI 没有报错。从那以后我每次写完都跑一遍skills validate。5.2 技能执行到一半失败技能执行失败的原因很多常见的有工具权限不足、文件路径不对、依赖命令不存在、验证步骤太严格。我的排查顺序是先看失败在哪一步然后单独手动执行那一步的命令确认环境没问题。如果是权限问题检查技能的工具声明。如果是路径问题检查技能里写的路径是相对路径还是绝对路径建议统一用相对于项目根目录的路径。注意技能执行失败后代理可能会重试。如果重试多次仍然失败检查是不是技能本身有逻辑错误而不是环境问题。有时候技能步骤里写的命令在当前项目里根本不适用。5.3 技能之间冲突当你注册了多个技能可能会出现两个技能都匹配同一个任务的情况。这时候代理选哪个取决于匹配算法的优先级。为了避免冲突我的做法是给技能加priority字段数值高的优先。同时触发条件尽量互斥。比如一个技能处理“添加接口”另一个处理“修改接口”触发条件里明确区分“添加”和“修改”。5.4 验证步骤误报验证步骤太严格会导致误报。比如你写“测试覆盖率必须达到90%”但项目当前覆盖率只有70%那技能永远无法通过验证。我的建议是验证步骤只检查本次变更直接相关的内容。比如新增接口的测试必须通过但不要求整个项目覆盖率达标。这样验证既有意义又不会因为历史遗留问题卡住。5.5 常见问题速查表问题现象可能原因排查方法解决方式技能不触发触发条件太窄/格式错误运行 skills validate放宽条件/修正格式执行中途失败权限不足/路径错误手动执行失败步骤调整工具声明/路径多技能冲突触发条件重叠查看 skills list加 priority/区分条件验证误报验证范围过大检查验证步骤缩小到本次变更技能加载慢技能文件过大查看文件大小拆分技能/精简步骤5.6 独家避坑技巧说几个文档里不会写、但我踩过坑之后总结出来的经验。技巧一技能文件不要写太长。一个技能超过200行代理加载和执行都会变慢而且维护起来痛苦。如果一个技能步骤超过10步考虑拆成两个技能用工作流串起来。技巧二给技能加版本号。技能会迭代加个version字段方便回滚。当新版本技能出问题时能快速切回旧版本。技巧三技能里的命令用绝对路径或明确的环境变量。代理执行时的环境可能和你的终端环境不同相对路径容易出错。用$PROJECT_ROOT这类变量或者在技能里声明工作目录。技巧四定期清理不再使用的技能。技能多了之后匹配效率会下降。每个季度 review 一次把过时的技能归档。技巧五把技能纳入代码评审。技能文件也是代码应该走 PR 流程。团队成员一起看能发现触发条件写得太宽、验证步骤不完整等问题。6. 技能体系的扩展玩法与个人体会6.1 把技能和 CI 流水线结合技能不只在本地用还可以接入 CI。比如在 PR 流水线里自动运行技能验证步骤确保代理提交的代码符合技能定义的标准。这样技能就从“代理的辅助工具”升级成了“团队的自动化质量门禁”。我试过在一个中型项目里这么做所有新增接口都必须通过add-rest-endpoint技能的验证步骤否则 PR 不允许合并。效果很明显接口的规范性大幅提升因为代理知道有验证卡着写的时候就会更注意。6.2 技能的市场化与共享agent-skills这类项目如果发展得好很可能会形成一个技能共享生态。你可以把自己写的技能发布出去也可以拉别人的技能来用。这有点像 npm 包或者 VS Code 插件但粒度更细更贴近具体任务。我在团队内部已经这么做了把常用技能放在一个共享仓库里新项目直接拉取。新人入职时不需要看长篇文档直接看技能文件就知道项目里各种任务该怎么执行。6.3 技能与模型切换的配合热词里提到了用cc switch接入 DeepSeek、Qwen、GLM 等模型。技能体系在这里的价值更加明显技能是模型无关的。你写好的技能换一个模型照样能用。因为技能描述的是“做什么”和“怎么验证”而不是“用哪个模型做”。这意味着你可以在不同模型之间切换比较哪个模型执行同一个技能效果更好而技能本身不需要改。这对于控制成本和探索模型能力边界非常有用。6.4 我个人的使用体会用了几个月技能体系之后我最大的感受是它把AI编码从“聊天”变成了“工程”。以前用AI写代码像是在跟一个记性不太好的同事口头交代任务现在更像是在维护一套标准操作流程代理只是执行者。当然技能体系不是银弹。它需要你花时间设计和维护技能前期投入不小。但如果你的项目周期超过一个月或者团队超过两个人这个投入是值得的。因为技能一旦稳定下来它带来的一致性和可复用性会远远超过你写提示词的时间成本。最后分享一个小技巧刚开始不要追求写大而全的技能。从一个最小的、你每天都在重复的任务开始写一个技能用一周然后根据实际使用情况迭代。技能体系是长出来的不是设计出来的。