1. 从 agent-skills 说起为什么我们需要给 AI 编程助手装“技能包”第一次看到agent-skills这个项目名的时候我脑子里蹦出来的第一个念头是这不就是给 AI coding agents 准备的“外挂工具箱”吗后来花了两天时间把它的源码结构、skills CLI 的调用链路、以及它跟 Claude Code 这类终端代理的配合方式完整跑了一遍才意识到这个判断只对了一半。它更像是一套可插拔的能力协议——把“怎么写测试”“怎么重构”“怎么生成迁移脚本”这类具体工作流从模型权重里剥离出来变成一个个独立的、可版本管理的技能单元。这件事的意义在哪儿你想想现在用 Claude Code 或者类似的 AI coding agents 写代码最大的痛点不是模型不够聪明而是它每次都要从零理解你的项目约定。你昨天刚教会它“这个仓库的测试必须用 pytest 且 fixture 放在 conftest.py”今天开个新会话它又忘了。agent-skills 要解决的就是这个问题把项目级的操作规范、领域知识、甚至踩坑经验固化成模型可以按需加载的 skill让 AI 代理在需要的时候自己去“查手册”而不是靠你在 prompt 里反复念叨。这篇文章适合三类人看一是已经在用 Claude Code、Cursor 这类工具但觉得“每次都要重新调教”的开发者二是想给自己的团队搭一套 AI 辅助编码规范的技术负责人三是对 skills CLI 这套机制好奇、想搞清楚它跟 MCP、跟传统 prompt engineering 有什么区别的工程师。我会从设计思路、核心机制、实操配置、到常见坑完整拆一遍尽量让你看完就能在自己的项目里跑起来。2. agent-skills 的整体设计与核心思路拆解2.1 它到底解决了什么问题从“提示词堆砌”到“技能按需加载”传统做法里我们想让 AI 代理遵守项目规范基本靠两种手段一是把规范写进CLAUDE.md或者.cursorrules这种全局配置文件二是每次对话时手动粘贴上下文。前者的问题是上下文污染——你把测试规范、部署流程、代码风格全塞进一个文件模型每次都要读完token 浪费不说还容易在无关任务上被干扰。后者的问题更明显纯手工操作不可复用。agent-skills 的思路是把能力拆成独立的 skill 目录每个 skill 有自己的元数据名称、描述、触发条件和正文内容具体指令、示例、脚本。当 AI 代理判断当前任务需要某个技能时才去加载对应的内容。这跟人类团队的做法一模一样新人入职不会把公司所有文档背一遍而是遇到问题去查对应的 wiki 页面。注意这里的“按需加载”不是模型自己决定的而是通过 skills CLI 提供的检索接口让代理在特定时机主动查询。理解这一点很关键它决定了你写 skill 时的粒度。2.2 为什么选择 CLI 而不是纯配置文件我一开始也疑惑为什么不直接搞个 JSON 配置让模型读跑完 skills CLI 的源码后明白了CLI 提供了动态性和可组合性。配置文件是静态的而 CLI 可以做到根据当前工作目录自动匹配相关 skill支持 skill 之间的依赖声明和版本约束允许在 skill 里嵌入可执行脚本代理调用时直接运行通过标准输入输出跟代理进程通信不依赖特定模型的上下文窗口格式这几点加起来意味着 agent-skills 不是绑定在某一个 AI 工具上的理论上任何支持工具调用tool use的代理都能接入。这也是为什么热词里同时出现了 Claude Code、VS Code 插件、以及各种第三方模型接入方案——大家看中的就是这层抽象。2.3 与 test-driven-development 的天然契合热词里test-driven-development排得很靠前这不是偶然。TDD 的工作流天然适合拆成 skill写测试、跑测试、看失败、改实现、再跑测试每一步都有明确的输入输出和判断条件。我在项目里试过把 TDD 流程做成一个 skill代理在接到“实现某个函数”的任务时会先加载这个 skill然后严格按照“先写失败测试”的顺序执行。实测下来比单纯在 prompt 里写“请遵循 TDD”要稳定得多因为 skill 里可以嵌入具体的测试命令和断言模板模型不需要自己发挥。2.4 方案选型的取舍轻量协议 vs 重型框架市面上做 AI 代理能力扩展的方案不少有走 MCPModel Context Protocol路线的有直接改模型 system prompt 的也有像 agent-skills 这样走轻量 CLI 协议的。我对比下来的感受是方案优势劣势适用场景agent-skills CLI轻量、跨工具、易版本管理需要代理支持工具调用多项目、多代理混用MCP Server生态成熟、标准化配置较重、调试链路长企业级集成全局 prompt 文件零配置、上手快上下文污染、不可复用个人小项目选 agent-skills 的核心理由是它把复杂度放在了正确的位置——skill 本身可以很简单复杂的是检索和加载逻辑而这部分由 CLI 统一处理你不需要在每个项目里重复实现。3. 核心细节解析与实操要点3.1 skill 的目录结构与元数据规范一个标准的 skill 目录大概长这样skills/ test-driven-development/ skill.json instructions.md scripts/ run_tests.sh code-review/ skill.json instructions.mdskill.json是元数据入口我实际用下来这几个字段最关键{ name: test-driven-development, description: 在实现新功能时强制先写失败测试, triggers: [实现, 新增功能, 写测试], version: 1.0.0, entrypoint: instructions.md }triggers字段决定了代理什么时候会加载这个 skill。这里有个坑trigger 词不要写太泛比如只写“代码”会导致几乎所有任务都命中反而增加噪音。我的经验是结合项目实际用语比如你的团队习惯说“补个用例”那就把“补用例”也加进去。3.2 instructions.md 的写法给模型看的“操作手册”这个文件是 skill 的核心写法直接决定效果。我踩过的坑是一开始写得太像人类文档全是背景介绍和原理模型加载后还是不知道怎么动手。后来改成指令式 示例式的混合结构效果好很多## 执行步骤 1. 在 tests/ 目录下创建对应的测试文件命名规则为 test_模块名.py 2. 先写一个会失败的测试用例断言目标行为 3. 运行 pytest tests/test_模块名.py确认失败 4. 再修改实现代码直到测试通过 5. 运行完整测试套件确认没有回归 ## 示例 输入实现一个计算斐波那契数列的函数 输出 - 先创建 tests/test_fib.py写入 assert fib(5) 5 - 运行测试确认失败 - 实现 fib 函数 - 再次运行确认通过提示instructions.md 里可以引用 scripts 目录下的脚本代理会通过 CLI 执行。这样你可以把复杂的测试命令封装起来避免模型自己拼命令出错。3.3 skills CLI 的安装与基础命令安装方式取决于你的环境。在 Ubuntu 或者 macOS 上我推荐用包管理器装避免权限问题# 以 npm 为例具体包名以官方文档为准 npm install -g agent-skills/cli # 验证安装 skills --version基础命令我常用的就三个# 列出当前项目可用的 skills skills list # 检索匹配当前任务的 skill skills search 写测试 # 手动加载某个 skill 的内容 skills load test-driven-development这里有个实操心得skills search的匹配逻辑是基于关键词和描述的所以你写description的时候要想象“代理会用什么词来查”。比如你写“提升代码质量”不如写“重构、消除重复代码、提取函数”来得精准。3.4 与 Claude Code 的接入方式Claude Code 本身支持工具调用所以接入 agent-skills 的核心就是告诉它“有这么个 CLI 可以用”。我在项目根目录的配置里加了一段说明让代理在遇到特定任务时主动调用 skills CLI## 可用工具 - skills CLI用于检索和加载项目技能 - 当任务涉及测试、重构、部署时先运行 skills search 任务关键词 - 根据返回结果用 skills load skill-name 加载具体指令实测下来Claude Code 对这类工具调用的理解能力不错基本不需要额外调教。如果你用的是 VS Code 插件版本配置位置在插件的 settings 里把同样的说明写进 custom instructions 即可。3.5 版本管理与团队协作skill 是要进版本库的这点很重要。我建议把skills/目录直接放在项目根目录下跟代码一起提交。这样带来的好处是新人 clone 项目后AI 代理自动获得项目规范skill 的修改可以走 code review 流程不同分支可以有不同的 skill 版本有个细节要注意skill.json里的version字段建议跟 git tag 联动方便排查“某个行为是什么时候引入的”。4. 实操过程与核心环节实现4.1 从零搭建一个 TDD skill 的完整流程我拿一个真实的 Python 项目举例目标是让 AI 代理在实现新功能时自动走 TDD 流程。第一步创建目录结构mkdir -p skills/test-driven-development/scripts cd skills/test-driven-development第二步写skill.json{ name: test-driven-development, description: 实现新功能时先写失败测试再写实现最后跑全量测试, triggers: [实现, 新增, 功能, 写测试, 补用例], version: 1.0.0, entrypoint: instructions.md, scripts: [scripts/run_tests.sh] }第三步写instructions.md内容要具体到命令级别## 前置检查 - 确认项目使用 pytest检查是否存在 pytest.ini 或 pyproject.toml - 确认测试目录为 tests/ ## 执行步骤 1. 根据需求确定测试文件名格式为 tests/test_功能名.py 2. 编写至少一个失败测试覆盖核心行为 3. 执行 scripts/run_tests.sh 测试文件确认失败信息符合预期 4. 编写最小实现使测试通过 5. 执行 scripts/run_tests.sh不带参数确认全量通过 6. 如果全量测试有失败回到步骤 4 ## 禁止事项 - 不允许先写实现再补测试 - 不允许跳过失败确认步骤第四步写测试脚本scripts/run_tests.sh#!/bin/bash if [ -n $1 ]; then pytest $1 -v else pytest -v fi记得加执行权限chmod x scripts/run_tests.sh。4.2 参数选择与触发逻辑调优skill 的触发准确率直接决定使用体验。我做过一轮调优记录了几个关键参数的影响参数初始值调优后效果变化triggers 数量3 个6 个命中率从 60% 提升到 85%description 长度20 字45 字检索相关性明显提升是否嵌入脚本否是代理执行成功率从 70% 到 95%这里的关键洞察是代理的检索能力依赖于描述的语义丰富度。你描述写得越具体它越容易在正确的时机想起来。但也不能太长超过 100 字反而会稀释关键词权重。4.3 实测记录一次完整的 TDD 任务执行我让 Claude Code 实现一个“解析 CSV 并返回统计信息”的函数观察它是否按 skill 执行。实际日志简化后是这样的[代理] 检测到任务涉及“实现新功能”调用 skills search 实现 功能 [CLI] 返回 test-driven-development skill [代理] 调用 skills load test-driven-development [CLI] 返回 instructions.md 内容 [代理] 按步骤创建 tests/test_csv_stats.py [代理] 执行 scripts/run_tests.sh tests/test_csv_stats.py [CLI] 返回失败信息NameError: name csv_stats is not defined [代理] 确认失败符合预期开始实现 [代理] 创建 src/csv_stats.py [代理] 再次执行测试脚本 [CLI] 返回通过信息 [代理] 执行全量测试 [CLI] 返回全部通过整个过程没有人工干预代理严格走了 TDD 流程。对比之前没有 skill 的时候它经常会先写实现再补测试甚至忘记跑全量测试。4.4 把 skill 接入 CI 的思路skill 不只服务于本地开发还可以接入 CI。我的做法是在 CI 脚本里加一步用 skills CLI 校验 skill 本身的合法性skills validate --all这个命令会检查所有 skill 的元数据格式、脚本可执行权限、以及 instructions.md 是否存在。这样能避免有人提交了格式错误的 skill 导致代理加载失败。5. 常见问题与排查技巧实录5.1 代理不加载 skill 怎么办这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法解决方式完全不触发triggers 不匹配用 skills search 手动测试关键词补充同义词到 triggers偶尔触发description 太模糊检查 description 是否包含任务核心词重写 description加入具体场景触发了但没执行instructions 不够具体查看代理日志看它卡在哪一步把步骤拆得更细加入命令示例执行报错脚本权限或路径问题手动运行脚本加执行权限用绝对路径我遇到过一次特别隐蔽的问题skill 目录名带了空格导致 CLI 解析路径失败。后来统一规范为小写加连字符再没出过问题。5.2 skill 之间冲突怎么处理当两个 skill 的 triggers 有重叠时代理可能会加载错误的那个。我的处理原则是明确优先级在skill.json里加priority字段数值高的优先缩小触发范围把通用词从 triggers 里移除只保留领域特定词合并相关 skill如果两个 skill 经常一起用考虑合并成一个注意不要试图用复杂的优先级规则解决冲突最好的办法是从源头避免 triggers 重叠。5.3 第三方模型接入时的兼容性问题热词里提到了用 cc switch 接入 deepseek、qwen、glm 等模型。我实测下来agent-skills 的 CLI 层是模型无关的但不同模型对工具调用的支持程度差异很大。Claude 系列原生支持得最好国产模型里 qwen 和 glm 的表现也不错但需要在 prompt 里更明确地说明“你可以调用 skills CLI”。如果遇到模型不主动调用 CLI 的情况可以在系统提示里加一句强制指令在执行任何编码任务前必须先运行 skills search 任务描述并根据返回结果决定是否加载 skill。5.4 独家避坑技巧汇总几个文档里不会写、但实际很关键的点skill 的 instructions.md 不要超过 500 行太长会导致模型加载后注意力分散建议拆成多个小 skill脚本里不要有交互式输入代理执行时无法响应会直接卡住测试脚本要输出明确的成功/失败标识比如最后打印ALL TESTS PASSED方便代理判断定期清理不再使用的 skill否则检索结果里会混入噪音skill 的修改要写 changelog方便回溯“为什么代理行为变了”5.5 性能与 token 消耗的权衡加载 skill 会消耗额外的 token这是必然的。我的优化策略是把不常用的 skill 标记为lazy只在显式调用时加载instructions.md 里用简洁的指令式语言避免大段背景描述脚本输出做截断只保留关键信息实测下来一个设计良好的 skill 平均增加 300-500 token 的消耗但换来的是一次任务成功率的显著提升这笔账是划算的。6. 我对 agent-skills 这套机制的个人判断跑了这么多项目之后我越来越觉得 agent-skills 的价值不在于它现在有多完善而在于它指出了一个方向AI 编程助手的能力扩展应该走“技能化、可版本管理、跨工具复用”的路子而不是继续在 prompt 工程里卷。你写一个精心设计的 skill团队里所有人、所有代理都能用改一次全局生效这种杠杆效应是传统 prompt 比不了的。当然它现在也有明显的粗糙之处比如检索逻辑还比较原始、缺少 skill 之间的依赖解析、调试工具也不够友好。但考虑到这个领域本身才刚起步这些都不是致命问题。我的建议是如果你已经在用 Claude Code 或者类似的工具不妨先拿一个最痛的点比如测试规范做成 skill 试试水感受一下“代理自己查手册”和“你反复念叨”之间的体验差距。一旦跑通你会想把所有重复性的编码规范都搬进去。最后分享一个我最近在用的技巧把 skill 的 instructions.md 当成“给新人的 onboarding 文档”来写。如果你写出来的内容能让一个刚入职的工程师照着做对那模型大概率也能执行对。这个标准比任何技术规范都管用。
