1. 从"agent-skills"这个标题能读出什么
第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 当"新同事"来培养的技能体系。项目正文和关键词都是空的，但热搜词已经把方向交代得很清楚了——AI coding agents、skills CLI、Claude Code、test-driven-development。把这几个词串起来，它想解决的问题其实很具体：当 AI 已经能写代码、能跑终端命令之后，怎么让它稳定地按一套工程规范干活，而不是每次都要人重新交代一遍。
大多数人用 AI 编程工具的方式是"对话式"的：打开对话框，描述需求，等它吐代码，不满意就再补一句。这种方式在写一个函数、改一个 bug 时够用，但一旦进入真实项目——有目录约定、有测试要求、有提交规范、有代码风格——就会立刻暴露问题。你会发现每次新开一个会话，agent 都像失忆了一样，你得把项目背景、技术栈、命名习惯、测试命令重新讲一遍。讲得越细，token 消耗越大；讲得越粗，产出越不可控。
agent-skills这类项目的核心思路，是把这些"每次都要重复交代的东西"沉淀成可复用的技能单元。一个 skill 可以理解为一份写给 agent 看的"岗位说明书 + 操作手册"：它告诉 agent 在什么场景下该做什么、按什么顺序做、做完怎么验证。配合skills CLI这样的命令行工具，你可以把技能安装到本地、按项目启用、按需组合。这跟传统意义上"给 AI 写 prompt"最大的区别在于：prompt 是一次性的，skill 是可版本化、可分发、可测试的工程资产。
这篇文章适合三类人看。第一类是已经在用 Claude Code 或类似 AI coding agent、但总觉得"它不够听话"的开发者；第二类是想把 AI 编程引入团队、但苦于产出质量不稳定的技术负责人；第三类是对test-driven-development这类工程实践有执念、想看看能不能让 agent 也遵守的人。我会从技能体系的设计逻辑讲起，拆到 CLI 的安装与使用，再落到 TDD 场景的完整实操，最后聊几个我踩过的坑。全程按"为什么这么设计"来讲，不堆概念。
2. 为什么"技能"比"提示词"更适合 AI coding agent
2.1 提示词的三个结构性缺陷
先说清楚为什么单纯堆提示词走不远。我在实际项目里观察到的三个问题是反复出现的。
第一是上下文漂移。一个会话聊到第 20 轮，agent 对最初那条"所有函数必须写单元测试"的指令已经"淡忘"了，它开始直接给实现、跳过测试。这不是模型笨，而是长上下文里早期指令的权重天然会被稀释。你只能不断重复提醒，而每次提醒都在烧 token。
第二是无法复用。你为 A 项目精心调教的那套"先读现有代码风格、再写实现、最后补测试"的流程，换到 B 项目就得重来一遍。提示词躺在聊天记录里，既不能 git 管理，也不能团队共享，更没法做 A/B 对比看哪版效果更好。
第三是缺乏触发时机。提示词是"常驻"的，但很多规范只在特定时刻才该生效。比如"提交前必须跑 lint"这条，在 agent 写代码阶段提它没用，反而干扰；只有到准备 commit 的那一刻才该触发。纯提示词做不到这种"条件触发"，而 skill 可以。
2.2 skill 的本质：带触发条件的操作契约
一个设计良好的 skill，结构上通常包含四块：元信息（名称、描述、适用场景）、触发条件（什么时候该用这个技能）、执行步骤（具体怎么做）、验证标准（怎么算做完了）。这四块合起来，就是一份 agent 能读懂、能执行、能自检的契约。
拿test-driven-development这个技能举例。它的元信息会写明"适用于新增功能或修复 bug 时"；触发条件是"当用户要求实现一个可测试的行为时"；执行步骤是经典的 Red-Green-Refactor——先写一个会失败的测试，再写最小实现让它通过，最后重构；验证标准是"测试从红变绿，且没有为了通过而写假测试"。当 agent 识别到当前任务符合触发条件，它就会加载这套流程，而不是随手开写。
这种设计的精妙之处在于关注点分离。技能本身不关心你用什么语言、什么框架，它只规定"流程"；具体的技术细节由项目自身的配置文件（比如CLAUDE.md或类似的上下文文件）提供。这样一来，同一个 TDD 技能可以跨语言复用，你不需要为 Python 和 TypeScript 各写一份。
2.3 skills CLI 扮演的角色
skills CLI是这套体系的"包管理器"。它的存在解决了一个很现实的问题：技能从哪来、装到哪、怎么更新。
没有 CLI 的时候，你得手动把技能文件复制到 agent 能读到的目录，还得记住每个技能放哪、版本对不对。有了 CLI，流程就变成标准化的几条命令：搜索技能、安装技能、列出已装技能、更新技能。这跟npm install或pip install的思路是一致的——把"能力"当成依赖来管理。
提示：技能目录的路径约定很关键。不同 agent 读取技能的默认位置不一样，装错地方会出现"明明装了却不生效"的情况。安装后第一件事是确认 agent 实际扫描的目录，而不是想当然。
我个人的判断是，agent-skills这类项目的价值不在于它内置了多少技能，而在于它定义了一套让技能可以被工程化管理的规范。技能一旦能被版本控制、能被团队 review、能被 CI 校验，AI 编程就从"个人手感"变成了"团队能力"。
3. 把 skills CLI 跑起来：环境准备与安装细节
3.1 前置环境检查
在装任何东西之前，先确认基础环境。这套工具链通常依赖 Node.js 运行时（因为多数 AI coding agent 的 CLI 是 npm 分发的），所以第一步是确认 Node 版本。
node -v npm -vNode 建议 18 LTS 以上，低于这个版本有些依赖会装不上。如果你用的是 macOS，用nvm管理 Node 版本会比系统自带的更省心；Ubuntu 上同理，别用apt装的老版本 Node，容易和后续工具冲突。
# 用 nvm 安装并切换到 LTS nvm install --lts nvm use --lts这里有个容易被忽略的点：全局安装目录的权限。在 macOS 和 Ubuntu 上，如果 npm 的全局目录归 root 所有，npm install -g会报权限错误。正确的做法不是无脑加sudo（那会让后续所有全局包都带 root 权限，埋雷），而是把 npm 的全局前缀改到用户目录下。
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加进 PATH export PATH=~/.npm-global/bin:$PATH把这行export写进~/.bashrc或~/.zshrc，否则新开终端就失效了。
3.2 安装 skills CLI 与 agent 本体
环境就绪后，安装分两步：先装 AI coding agent 本体，再装 skills CLI。以 Claude Code 为例，它通过 npm 全局安装：
npm install -g @anthropic-ai/claude-code装完用claude --version验证。如果提示命令找不到，八成是 PATH 没配好，回头检查上一步。
skills CLI 的安装方式取决于具体实现，常见的是通过 npm 或独立的安装脚本。安装后同样用--version或--help确认可用：
skills --help--help的输出很值得细看，它会列出所有子命令。通常包括list（列出可用技能）、install（安装技能）、remove（卸载）、update（更新）。先把这个清单过一遍，比直接上手瞎试高效得多。
3.3 首次运行时的登录与模型选择
Claude Code 首次启动会引导你完成账号配置。这里有个很多人关心的问题：能不能不登录、直接用第三方模型？答案是取决于你的接入方式。官方 CLI 默认走官方账号体系，但社区里也有通过配置指向兼容接口的做法，让 CLI 调用其他模型服务。
如果你走的是第三方接口路线，核心是配置好base_url和api_key两个环境变量或配置文件项。不同模型的兼容程度不一样，有的对工具调用（tool use）支持得好，有的在长上下文里容易丢指令。我的经验是：先用官方默认配置把流程跑通，确认技能体系能正常工作，再去折腾模型替换。否则一旦出问题，你分不清是技能没生效还是模型不兼容，排查成本翻倍。
注意：切换模型后，技能的触发准确率可能会有明显波动。因为技能依赖 agent 正确理解"何时该用哪个技能"，这本质上是模型的指令遵循能力。换模型后建议重新验证一遍核心技能是否还能正常触发。
3.4 在编辑器里接入
如果你习惯在 VS Code 里工作，可以装对应的扩展，让 agent 直接在编辑器内运行。配置的关键是让扩展能找到 CLI 的可执行文件路径，以及正确的工作目录。装完后在项目根目录打开，agent 会自动读取当前项目的上下文文件。
Ubuntu 用户如果遇到扩展连不上 CLI 的情况，先确认 CLI 在终端里能独立运行，再检查扩展设置里的路径配置。很多时候问题不在扩展本身，而是终端环境和 GUI 环境下的 PATH 不一致——GUI 启动的进程读不到你在.bashrc里设的 PATH。解决办法是在扩展配置里写绝对路径。
4. 用 TDD 技能走一遍完整开发流程
4.1 为什么拿 TDD 当第一个练手技能
test-driven-development是检验技能体系是否好用的最佳试金石。原因很简单：TDD 有明确的阶段划分（红、绿、重构）和明确的验证信号（测试通过与否）。如果 agent 能严格按 TDD 流程走，说明技能体系真的在约束它的行为；如果它还是"先写实现再补测试"，那说明技能没生效或者触发条件写得太模糊。
TDD 的经典三步是：
- Red：写一个测试，描述你期望的行为，此时它必然失败（因为功能还没实现）。
- Green：写最少的代码让测试通过，不追求优雅。
- Refactor：在测试保护下重构，改善结构但不改变行为。
让 agent 遵守这个顺序，最大的价值是防止它写出"看起来对但没验证"的代码。人类开发者偷懒时也会跳过测试，agent 更是如此——它倾向于直接给你一个完整实现，因为那样"看起来更有用"。TDD 技能的作用就是强制它先停下来写测试。
4.2 触发技能并观察行为
假设我要实现一个"计算购物车总价，支持折扣码"的功能。启用 TDD 技能后，我给 agent 的指令应该尽量简洁，把细节留给技能去补：
实现一个购物车总价计算函数，支持百分比折扣码。如果技能正常工作，agent 的第一反应不是给你实现代码，而是先问清楚或直接写出一个测试文件。它可能会先确认：折扣码无效时怎么处理？折扣是否可叠加？这些边界问题正是 TDD 逼出来的——写测试的过程就是澄清需求的过程。
我实测下来，一个配置得当的 TDD 技能会让 agent 的输出顺序变成：测试文件 → 运行测试（确认失败）→ 实现代码 → 再运行测试（确认通过）→ 重构。你能在终端里看到它真的执行了测试命令，而不是嘴上说说。
4.3 验证技能是否真的在约束行为
判断技能有没有生效，有个很实用的方法：故意给一个模糊需求，看 agent 会不会主动补测试。
如果它直接甩给你一段实现，说明技能没触发。这时候要检查三件事：技能是否装在 agent 扫描的目录里、技能的触发条件描述是否和你的指令匹配、agent 的上下文里有没有冲突的指令（比如项目配置文件里写了"优先给实现"）。
另一个验证角度是看它失败时的反应。真正遵守 TDD 的 agent，在测试没通过时不会急着改测试去迁就实现，而是回头改实现。如果它开始修改测试断言让它变绿，那就是"假 TDD"，得在技能里明确禁止这种行为。
提示：在技能描述里加一句"禁止为了让测试通过而修改测试断言，除非测试本身写错了"，能显著减少 agent 走捷径的情况。
4.4 把技能和项目上下文文件配合使用
技能负责"流程"，项目上下文文件负责"事实"。两者配合才能发挥最大效果。项目上下文文件里应该写清楚：技术栈、测试框架、测试命令、目录结构约定、代码风格。技能在执行时会读取这些信息，从而知道"测试该用什么框架写""跑测试该敲哪条命令"。
举个例子，如果项目用vitest，上下文文件里写明测试命令是npx vitest run，TDD 技能在执行"运行测试"这一步时就会用对命令，而不是瞎猜npm test。这个分工很清晰：技能是通用的，上下文是项目专属的，换项目只需要换上下文文件，技能不用动。
5. 技能体系落地时的真实坑与应对
5.1 技能装了不生效：先查目录再查触发
这是最高频的问题。表现是：skills list显示技能已安装，但 agent 干活时完全不理它。排查顺序应该是这样的。
第一步，确认 agent 实际扫描的目录。不同工具读取技能的路径不同，有的读项目根目录下的隐藏文件夹，有的读用户主目录下的全局配置。skills install默认装到哪，和 agent 默认读哪，不一定是同一个地方。用skills list --verbose或查看 CLI 文档确认路径。
第二步，确认触发条件。技能生效需要 agent 判断"当前任务匹配这个技能"。如果你的指令太笼统，或者技能描述里的触发词和你的表达对不上，就不会触发。解决办法是把技能描述写得更贴近你的实际用语。
第三步，检查指令冲突。如果项目上下文文件里有一条"直接给出完整实现"的指令，它会和 TDD 技能打架。agent 面对冲突指令时行为不可预测，可能随机选一个。保持指令一致很重要。
5.2 上下文窗口被技能撑爆
技能不是越多越好。每个加载的技能都会占用上下文窗口，装十几个技能后，留给实际代码的空间就被挤压了。表现是 agent 开始"忘事"、响应变慢、甚至报上下文超限。
我的做法是按项目启用技能，而不是全局全开。一个后端项目可能只需要 TDD、代码审查、提交规范三个技能；一个前端项目可能需要组件规范、可访问性检查。用 CLI 的按项目配置能力，让每个项目只加载自己需要的技能。
5.3 技能更新后行为突变
技能是可版本化的，这意味着它也会更新。更新后行为变化是常有的事——可能触发条件收紧了，可能步骤调整了。如果你在关键项目上依赖某个技能，更新前最好在测试项目里先验证一遍。
# 查看当前技能版本 skills list # 更新前先看变更 skills update --dry-run不是所有 CLI 都支持--dry-run，但思路是一样的：先看再更。团队协作时，把技能版本写进项目文档，避免有人用旧版有人用新版，导致 agent 行为不一致。
5.4 团队共享时的规范统一
技能体系在团队里最大的价值是统一 AI 的行为标准。但前提是大家用同一套技能、同一套上下文文件。我见过的情况是：每个人本地装了一堆自己的技能，结果同一个项目里，A 的 agent 会写测试，B 的 agent 不写，代码质量参差不齐。
解决办法是把技能配置和上下文文件一起纳入版本控制。项目仓库里放一份技能清单和上下文文件，新人 clone 下来后按文档装一遍技能，行为就对齐了。这跟统一代码风格工具（如 ESLint 配置）是一个道理——规范要能被机器执行，也要能被版本管理。
6. 我对这套体系的实际体会
用下来最深的感受是：AI coding agent 的上限不取决于模型多强，而取决于你给它搭的"工作环境"多规范。同一个模型，在没有任何技能约束时，产出像实习生随手写的草稿；配上 TDD、代码审查、提交规范几个技能后，产出质量能稳定到接近可 review 的水平。差别不在模型，在约束。
另一个体会是技能要从小处开始。别一上来就想搭一套覆盖全流程的技能体系，那大概率会失败。先挑一个最痛的场景——比如"每次都要手动补测试"——写一个 TDD 技能，跑通、验证、稳定之后，再往上加。技能之间也会互相影响，一次加太多，出了问题根本定位不到是哪个技能导致的。
最后分享一个我常用的小技巧：给每个技能写一个"反例"。也就是在技能描述里明确写"不要做什么"。比如 TDD 技能里写"不要在写测试之前就实现功能""不要修改测试来迁就实现"。正面指令告诉 agent 该做什么，反面指令堵住它走捷径的路。实测下来，加了反例的技能，行为稳定性明显更好。这个思路其实和带新人一样——你光告诉他"要写测试"不够，还得告诉他"别为了交差写假测试"。
