1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识地把它理解成给 AI 智能体写提示词。这个理解不算错但太浅了。真正在项目里落地过 AI coding agents 的人会明白agent-skills本质上是一套可复用、可组合、可测试的能力封装体系——它把让 AI 干某件事从一次性的对话变成了一份可以进版本库、可以被 review、可以被回归测试的工程资产。我最初接触这个概念是在给团队搭建 Claude Code 工作流的时候。当时我们面临一个很现实的问题同一个生成单元测试的需求不同的人问出来的结果质量参差不齐有人写出来的测试覆盖了边界条件有人写出来的测试连 happy path 都跑不通。问题不在于模型能力而在于没有人把怎么问、问什么、按什么顺序问、产出怎么校验这套东西固化下来。agent-skills要解决的就是这个固化问题。它适合谁三类人最该认真看一是已经在用 Claude Code、Cursor 这类 AI coding agents 做日常开发但产出不稳定的工程师二是想把 AI 能力沉淀成团队标准流程的技术负责人三是正在做 AI 工具链集成、需要一套清晰抽象来组织 prompt 和工具调用的平台开发者。哪怕你现在只是偶尔用 AI 写写脚本理解agent-skills的组织方式也能让你的使用效率上一个台阶。这篇文章不讲空泛的AI 改变开发只讲我实际搭过、踩过、改过的那套东西agent-skills的目录怎么设计、skills CLI 怎么用、怎么和 test-driven-development 结合、Claude Code 在 VS Code 和 Ubuntu 下怎么配、第三方模型怎么接、以及那些官方文档里不会写的坑。2. agent-skills 的整体设计与思路拆解2.1 为什么需要技能这层抽象先说一个我踩过的坑。早期我们团队把所有的 prompt 都塞在一个巨大的prompts.md里几十条指令堆在一起改一条要翻半天复用全靠复制粘贴。用了两个月这个文件变成了没人敢动的祖传代码。这就是缺少抽象层的典型症状。agent-skills的核心思路是把每一个AI 能独立完成的任务单元封装成一个 skill。一个 skill 通常包含四部分触发条件什么时候用这个技能、输入约定需要哪些上下文、执行步骤具体怎么一步步做、产出校验怎么判断做对了。这四部分对应到文件结构上往往是一个目录加一个描述文件再加若干辅助脚本或模板。为什么这么设计因为 AI coding agents 的可靠性很大程度上取决于上下文的边界是否清晰。你把一个模糊的大任务丢给 agent它会在无数种可能的路径里随机游走你把任务拆成边界清晰的 skill每一步的输入输出都可控整体成功率会显著提升。这跟微服务拆分的逻辑是一样的——不是拆得越细越好而是每个单元的职责要单一、接口要明确。2.2 目录结构一个能长期维护的骨架我最终稳定下来的目录结构大致是这样agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md │ │ ├── templates/ │ │ └── scripts/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── refactor-safe/ │ ├── SKILL.md │ └── examples/ ├── shared/ │ ├── conventions.md │ └── context-rules.md └── registry.jsonSKILL.md是每个技能的核心描述文件templates放产出模板scripts放辅助脚本shared放跨技能共享的约定registry.json是技能索引。这个结构的好处是新增技能不影响已有技能共享约定集中管理索引文件让 skills CLI 能自动发现所有技能。我试过把共享约定直接写进每个 SKILL.md结果是改一次约定要改十几个文件漏改一个就出现行为不一致。抽到shared/之后维护成本直接降下来了。这个经验很朴素但真的省事。2.3 方案选型为什么不用纯 prompt 文件有人会问直接用一堆.mdprompt 文件不行吗为什么要搞这么复杂我的回答是当技能数量超过 5 个纯 prompt 文件就会失控。原因有三个。第一纯 prompt 文件没有元数据。你没法标注这个技能依赖哪些工具、适用哪些语言、需要什么前置条件。skills CLI 也就无法根据当前上下文自动推荐技能。第二纯 prompt 文件没有校验环节。AI 的产出对不对全靠人肉看。而agent-skills的 SKILL.md 里可以明确写产出必须通过npm test把校验交给机器。第三纯 prompt 文件难以版本化演进。技能是会迭代的今天有效的 prompt 明天可能因为模型更新就失效了。有结构、有测试、有版本记录的技能体系才能持续演进。3. 核心细节解析与实操要点3.1 SKILL.md 到底该写什么SKILL.md是整个体系的心脏。我见过太多人把它写成一段长长的自然语言描述结果 agent 读完之后还是不知道该干嘛。一份好的 SKILL.md应该像一份给新人的 SOP而不是一段散文。我通常按这个模板写# Skill: tdd-workflow ## 触发条件 当用户要求为新功能写测试或补充测试覆盖时启用。 ## 前置检查 - 确认项目已配置测试框架jest/pytest/go test - 确认目标文件路径存在 ## 执行步骤 1. 读取目标文件的导出接口 2. 为每个导出生成 happy path 测试 3. 补充边界条件测试空值、极值、异常输入 4. 运行测试若失败则分析原因并修正测试或报告代码问题 ## 产出校验 - 所有新增测试必须能通过 - 覆盖率提升不低于 10% ## 禁止事项 - 不得修改被测代码来让测试通过 - 不得跳过失败测试注意最后那个禁止事项。这是我从一次事故里学到的agent 为了让测试通过偷偷改了被测代码的逻辑把 bug 掩盖了。加上明确的禁止条款之后这类问题基本消失了。给 agent 划红线比给它讲道理更有效。3.2 skills CLI 的安装与基本用法skills CLI 是管理这些技能的命令行工具。安装方式取决于你的环境常见的是通过包管理器全局安装。装完之后核心命令就那么几个# 列出所有已注册技能 skills list # 查看某个技能的详情 skills show tdd-workflow # 在项目中初始化技能目录 skills init # 校验技能定义是否合法 skills validateskills validate这个命令我要重点说。它会检查 SKILL.md 的格式、引用的模板文件是否存在、脚本是否有执行权限。我建议把它加进 CI每次提交技能改动都跑一遍。技能定义出错比代码出错更隐蔽因为它不会报错只会让 agent 的行为变得诡异。3.3 与 test-driven-development 的结合点agent-skills和 test-driven-development 是天作之合原因很简单TDD 天然要求先写测试、再写实现、最后重构这个流程的每一步都可以封装成一个 skill而且每一步都有明确的校验标准。我的做法是把 TDD 拆成三个技能tdd-red写失败测试、tdd-green写最小实现让测试通过、tdd-refactor在测试保护下重构。三个技能串起来就是一个完整的 TDD 循环。为什么这么拆因为如果让 agent 一次性完成写测试写实现重构它很容易走捷径——比如写一个过于宽松的测试然后写一个刚好能过的实现最后重构时又把测试改松了。拆成三步之后每一步的产出都要经过独立校验走捷径的空间被大幅压缩。提示tdd-red技能里一定要明确要求测试必须先失败。如果测试一写出来就通过说明测试没有真正覆盖新功能必须重写。3.4 上下文管理别让 agent 被信息淹没这是最容易被忽视的一点。很多人以为给 agent 的上下文越多越好实际上恰恰相反。上下文过载会让 agent 抓不住重点产出质量反而下降。我的经验是每个 skill 只加载它真正需要的上下文。比如code-review技能只需要目标文件的 diff 和相关测试不需要整个仓库的历史。refactor-safe技能需要目标文件、它的调用方、以及现有测试但不需要无关模块的代码。实现方式上可以在 SKILL.md 里声明context_scope让 skills CLI 在调用时自动裁剪上下文。这个机制我强烈建议加上实测下来对产出质量的提升非常明显。4. 实操过程与核心环节实现4.1 环境准备Ubuntu 下的完整配置先讲 Ubuntu 环境因为这是我最常用的开发环境。整个配置过程分几步。第一步是基础运行时。Claude Code 这类工具通常依赖 Node.js 环境建议用 nvm 管理版本避免系统自带的旧版本捣乱curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v第二步是安装 Claude Code 本体。官方提供了安装脚本执行后按提示完成即可。安装完成后用claude --version确认。第三步是配置 skills CLI。如果你是从源码构建克隆仓库后执行构建命令再把产物链接到全局路径git clone skills-cli-repo cd skills-cli npm install npm run build npm link skills --version第四步是在你的项目里初始化技能目录把团队共享的技能复制进去然后跑一次skills validate确认无误。注意Ubuntu 下如果遇到权限问题不要无脑sudo。优先检查文件属主和目录权限用chown修正比用sudo更安全。4.2 VS Code 配置让 agent 融入编辑器VS Code 是大多数人的主战场配置好之后体验提升很大。核心是装 Claude Code 的 VS Code 插件然后在设置里配置好模型和 API 端点。插件装完之后需要在设置里填几个关键项模型名称、API 地址、密钥。如果你用的是第三方 API 接入 DeepSeek、Qwen、GLM 这类模型端点地址和模型名要按服务商文档填别照抄别人的配置——不同服务商的模型名大小写和路径规则经常不一样抄错了就是一堆 404。配置好之后我建议在项目根目录放一个.claude/settings.json把项目级的技能路径、上下文规则写进去。这样团队每个人拉下代码就有一致的配置不用各自折腾。VS Code 里还有一个实用技巧把常用的 skill 绑定到快捷键。比如我把tdd-red绑到CtrlAltT写测试的时候一键触发比在对话框里打字快得多。4.3 第三方模型接入cc switch 的用法很多人关心怎么用第三方模型跑 Claude Code 的工作流。这里cc switch是个常用工具它的作用是切换不同的模型后端。基本用法是配置好各个后端的参数然后用一条命令切换cc switch deepseek cc switch qwen cc switch glm每个后端的配置里要写清楚 API 地址、模型名、密钥环境变量名。我踩过的坑是不同模型对 system prompt 的遵循程度差异很大。DeepSeek 和 Qwen 对结构化指令的遵循比较好GLM 在某些长上下文场景下表现更稳。所以同一个 skill在不同模型上可能需要微调措辞。我的建议是先在一个模型上把 skill 调通再迁移到其他模型迁移时重点测触发条件和产出校验这两个环节因为这两个环节对模型能力最敏感。4.4 一个完整的 TDD 实操记录讲个真实案例。需求是给一个订单金额计算函数加满减逻辑。我先触发tdd-red让 agent 写测试。它产出了三个测试正常满减、不满足门槛、边界值刚好等于门槛。我检查后发现边界值测试写错了门槛是满 100 减 10它写成了满 100 减 10 但 100 不算。我修正了测试描述重新生成。然后触发tdd-green让 agent 写最小实现。它写了一个简单的 if 判断测试全过。最后触发tdd-refactor把硬编码的门槛和减免额抽成配置。重构后测试依然全过。整个过程大概 15 分钟比我手写快了一倍多而且测试覆盖比我平时写的更全。关键在于每一步都有校验agent 没法偷懒。4.5 参数选择上下文窗口与温度这两个参数值得单独说。上下文窗口决定了 agent 一次能看多少代码温度决定了产出的随机性。对于agent-skills场景我的经验值是上下文窗口尽量给足但通过context_scope精确控制加载内容温度调低通常在 0.2 到 0.4 之间因为技能执行需要的是稳定复现不是创意发散。有人喜欢把温度调到 0追求完全确定性。但实测下来温度 0 有时会让 agent 陷入死循环反复输出同样的错误内容。留一点随机性反而更容易跳出死胡同。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。你写好了 skillagent 却视而不见。排查顺序是这样的先看skills list里有没有这个技能。没有的话检查registry.json是否包含它以及 SKILL.md 的路径是否正确。有的话看触发条件写得够不够明确。我见过有人写当需要时启用这种模糊描述 agent 根本没法判断。触发条件必须是具体的、可匹配的场景描述。再不行就在对话里显式点名使用 tdd-workflow 技能。如果显式点名能用说明是触发条件的问题如果显式点名也不行说明技能定义本身有语法错误跑skills validate查。5.2 产出质量不稳定同一个技能有时产出很好有时一塌糊涂。原因通常有三个上下文过载、模型状态波动、技能描述有歧义。上下文过载最常见。检查一下是不是把整个仓库都塞进去了。模型状态波动没法完全避免但可以通过降低温度、增加校验环节来缓解。技能描述有歧义则需要你反复打磨措辞把尽量适当这类模糊词全部替换成具体标准。5.3 常见问题速查表问题现象可能原因排查方法解决方向技能不触发触发条件模糊显式点名测试改写触发条件产出格式错乱模板缺失检查 templates 目录补全模板文件测试被改松缺少禁止条款对比测试 diff加禁止事项上下文超限scope 未裁剪查看加载内容配置 context_scope模型返回 404端点或模型名错核对服务商文档修正配置技能校验失败格式不合法跑 validate按报错修正5.4 几个独家避坑技巧第一个技巧给每个技能写一个反例。在 SKILL.md 里加一段错误示范明确告诉 agent 什么样的产出是不合格的。这比只写正面要求有效得多因为 agent 对不要做什么的遵循往往比要做什么更到位。第二个技巧技能要小步迭代不要一次写完美。我最初的code-review技能写了 200 行结果 agent 执行时经常漏步骤。后来砍到 50 行只保留最核心的检查项执行成功率反而上去了。技能不是越长越好是越聚焦越好。第三个技巧定期清理失效技能。模型更新后有些技能可能已经不需要了或者行为变了。我每个月会跑一次全量技能测试把失效的标记出来该改的改该删的删。技能库跟代码库一样需要持续维护不然就会变成技术债。第四个技巧把技能产出纳入 code review。agent 生成的代码和测试一样要过 review。我见过有人因为是 AI 写的就放松审查结果线上出了事故。AI 是加速器不是免检章。6. 技能体系的扩展与团队协作6.1 从个人技能到团队资产一个人用agent-skills价值有限一个团队用价值才真正释放。关键在于把个人调好的技能沉淀成团队共享资产。我的做法是建一个独立的技能仓库团队每个人都可以提交新技能或改进现有技能通过 PR 流程 review。review 的重点不是代码而是技能描述的清晰度和校验环节的完备性。一个技能如果校验环节缺失就不允许合并。这样做的好处是新同事入职第一天就能用上团队积累的所有技能不用从零摸索。而且技能会随着团队实践不断进化越用越好用。6.2 技能的组合与编排单个技能解决单点问题技能组合解决复杂问题。比如新功能开发这个复杂任务可以编排成需求拆解→tdd-red→tdd-green→tdd-refactor→code-review。编排方式有两种一种是在 SKILL.md 里声明依赖让 CLI 自动串联另一种是写一个编排脚本显式控制每一步的输入输出。我倾向于后者因为可控性更强出问题好定位。编排时要注意步骤之间的数据传递。上一步的产出怎么传给下一步格式要约定清楚。我通常用 JSON 作为中间格式结构清晰解析方便。6.3 技能的效果度量技能好不好用不能凭感觉要有数据。我跟踪三个指标触发成功率技能被正确触发的比例、产出合格率产出通过校验的比例、人工修正率产出需要人工修改的比例。这三个指标我每周统计一次画成趋势图。哪个技能指标下滑了就重点排查。这套度量让我能客观判断技能体系的健康度而不是靠感觉最近 AI 变笨了这种模糊判断。7. 我个人的一些实操体会搭这套agent-skills体系前后折腾了小半年最大的体会是AI coding agents 的上限取决于你给它的结构而不是它的模型参数。同一个模型在有清晰技能体系的环境里和在裸奔的环境里产出质量差距是数量级的。另一个体会是别追求一步到位。我最初想设计一套完美的技能体系结果卡在设计阶段两周没动手。后来改成先用起来边用边改反而很快就跑通了。技能体系是长出来的不是设计出来的。最后分享一个我最近在用的做法把每次 agent 产出不理想的案例记下来分析是技能描述的问题还是模型的问题。积累一段时间后这些案例就成了改进技能的最好素材。踩过的坑都是资产。