企业官网建设流程全解析

1. 从"agent-skills"这个标题能读出什么

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 当"新同事"来培养的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development，这三者放在一起，指向一个很明确的方向——用命令行工具管理技能包，让编码智能体在真实项目里按测试驱动的方式干活。

先把概念对齐。所谓agent skills，可以理解成给 AI 编码助手准备的"岗位操作手册 + 工具箱"。它不是模型权重，也不是插件市场里的黑盒，而是一组可读、可改、可版本控制的文件集合，通常包含技能描述、触发条件、执行步骤、参考脚本和验证方式。skills CLI则是管理这些技能包的命令行入口，负责安装、列出、启用、禁用、更新技能。

为什么这件事值得单独拿出来讲？因为大多数人用 AI 写代码的现状是：每次开新会话都要重新解释项目结构、编码规范、测试要求，模型还经常"自由发挥"，改完不跑测试就宣布完成。agent-skills 想解决的正是这个重复劳动和不可控问题——把"怎么干活"沉淀成技能，让 agent 每次都能按同一套标准执行。

这篇文章适合三类人看：一是已经在用 Claude Code 或类似编码智能体、但觉得输出不稳定的开发者；二是想给团队建立 AI 编码规范的技术负责人；三是刚接触 skills CLI、想知道这套东西到底怎么落地的新手。我会从技能包的内部结构讲起，一路讲到 TDD 工作流怎么和 agent 配合，中间穿插我自己踩过的坑。

需要说明的是，输入里项目正文和关键词都是空的，所以下面关于目录结构、命令用法、配置细节的部分，是基于这类工具在社区中的常见实践做的合理补全，具体字段名请以你实际安装的版本为准。

2. 技能包到底长什么样：拆开 agent-skills 的内部结构

2.1 一个技能的最小构成单元

很多人以为技能就是一个 markdown 文件，写一段提示词就完事。实际用下来，一个能稳定工作的技能通常包含四部分：元信息、触发描述、执行指令、验证手段。

元信息负责告诉 CLI 这个技能叫什么、版本多少、依赖哪些工具。触发描述决定 agent 在什么场景下会加载它——这部分写得含糊，技能就永远不会被激活，或者在不该激活的时候乱激活。执行指令是核心，描述具体步骤。验证手段最容易被忽略，但恰恰是 TDD 场景下最关键的一环：怎么判断这个技能执行成功了。

我见过太多人只写执行指令，结果 agent 干完活自己说"已完成"，实际测试全红。技能里如果没有明确的验证步骤，agent 就会用"看起来对"来代替"确实对"。

2.2 目录布局与文件职责

一个典型的技能包目录，大致是这样组织的：

agent-skills/ skills/ tdd-workflow/ SKILL.md # 技能主描述，含触发条件与步骤 scripts/ run-tests.sh # 可被 agent 调用的脚本 references/ testing-guide.md code-review/ SKILL.md skills.config.json # CLI 读取的全局配置

SKILL.md是入口，CLI 扫描目录时主要认这个文件。scripts/放可执行脚本，agent 可以直接调用而不是自己现编命令——这一点非常重要，脚本是确定性的，模型生成是概率性的，能用脚本就别让模型自由发挥。references/放参考资料，按需加载，避免一次性把上下文塞满。

skills.config.json管全局，比如技能搜索路径、默认启用的技能、优先级顺序。优先级这个字段值得单独说：当两个技能都能匹配当前任务时，谁先加载会直接影响 agent 的行为，配置不当会出现"该用 TDD 的时候用了快速修复技能"这种尴尬。

2.3 触发描述为什么比执行步骤还难写

执行步骤是"怎么做"，触发描述是"什么时候做"。后者更难，因为它要在自然语言层面和模型的意图识别对齐。

我的经验是，触发描述里要同时包含正向信号和负向信号。正向信号列出典型场景关键词，负向信号明确排除不该触发的情况。比如一个 TDD 技能，正向信号是"新增功能""修复 bug""需要写测试"，负向信号是"仅修改文档""仅调整格式"。

只写正向信号，技能会在文档修改时也被拉起来，白白消耗上下文。只写负向信号，又容易漏触发。两者结合，命中率会明显提升。这个思路和写正则表达式有点像：光有匹配规则不够，还得有排除规则。

提示：触发描述里避免使用过于宽泛的词，比如"代码""修改""优化"。这些词几乎在任何任务里都会出现，等于没有过滤效果。

2.4 技能之间的依赖与冲突

技能不是孤立的。TDD 技能可能依赖"运行测试"技能，代码审查技能可能依赖"读取 diff"技能。CLI 一般支持声明依赖，加载时自动把依赖项一起拉进来。

冲突则更隐蔽。两个技能如果都定义了"修改文件前先备份"这类步骤，重复执行会浪费时间；如果两个技能对同一类文件给出矛盾指令，agent 会随机选一个，行为不可预测。我的做法是给技能划分清晰的职责边界，一个技能只干一件事，交叉部分抽成公共技能被双方依赖。

3. skills CLI 的安装与日常操作

3.1 环境准备里最容易翻车的两步

skills CLI 通常通过包管理器分发。以常见的 Node 生态为例，安装命令大致是：

npm install -g agent-skills-cli

装完之后先别急着用，跑一下版本检查：

skills --version

如果提示命令找不到，九成是全局 bin 目录没进 PATH。这是新手最常卡的地方，尤其在 macOS 和 Ubuntu 上，npm 全局目录和系统 PATH 经常对不上。解决办法是查npm config get prefix，把输出的 bin 路径加进 shell 配置。

第二步容易翻车的是权限。在 Ubuntu 上用 sudo 装全局包，后续普通用户运行时可能读不到配置目录。我的建议是配置 npm 使用用户级目录，避免 sudo，省掉后面一堆权限问题。

3.2 安装、列出、启用技能的标准流程

CLI 的核心命令就那么几个，记住就能覆盖日常：

典型流程是：先skills install tdd-workflow，再skills list确认装上了，然后skills enable tdd-workflow。注意安装和启用是两回事，装了不启用，agent 不会加载。我一开始就犯过这个错，装完以为万事大吉，结果 agent 行为毫无变化，排查半天才发现忘了 enable。

3.3 技能加载顺序与优先级调优

当启用的技能变多，加载顺序就成了关键。CLI 一般按配置文件里的优先级排序，数字小的先加载。先加载的技能会先进入上下文，对 agent 的初始行为影响更大。

我的调优原则是：约束性强的技能放前面，辅助性的放后面。比如"必须写测试"这种硬约束应该优先于"代码风格建议"这种软引导。如果顺序反了，agent 可能先被风格建议带偏，再看到测试要求时已经生成了不合规的代码。

调整优先级直接改skills.config.json里的顺序字段即可，改完记得重启会话，因为技能通常在会话初始化时加载，运行中改配置不一定即时生效。

3.4 用 CLI 做技能的健康检查

技能写多了，难免有失效的。CLI 一般提供校验命令，检查技能文件格式、依赖是否满足、脚本是否可执行。定期跑一次能提前发现问题。

我自己的习惯是每次改完技能就校验一遍，尤其是改了脚本路径之后。脚本路径写错，技能加载时不报错，等 agent 真去调用才失败，那时候排查成本高得多。提前校验能把这类问题挡在前面。

4. 把 TDD 工作流塞进 agent 的执行循环

4.1 为什么 TDD 特别适合交给 agent

测试驱动开发的核心是"先写测试，再写实现，最后重构"。这个循环对人类来说有点反直觉，需要刻意练习；但对 agent 来说反而顺理成章，因为每一步都有明确的、可验证的产出。

红阶段：写一个会失败的测试。绿阶段：写最少的代码让测试通过。重构阶段：在不破坏测试的前提下优化结构。每个阶段的完成标准都是"测试结果"，而不是"我觉得写完了"。这正好补上了 agent 最容易出问题的地方——自我评估不可靠。

把 TDD 做成技能，等于给 agent 装了一个强制性的质量闸门。它不能跳过测试直接宣布完成，因为技能里明确要求"必须展示测试通过的结果"。

4.2 技能里怎么描述红绿重构三步

在SKILL.md里，我会把三步拆成独立的、带验证的子步骤：

1. 红：根据需求写测试，运行测试，确认它失败，并记录失败原因。
2. 绿：写最小实现，运行测试，确认全部通过。
3. 重构：在测试保持绿色的前提下调整代码，每次调整后重跑测试。

关键在于每一步都要求 agent实际运行命令并展示输出，而不是口头描述。技能里要明确写"禁止在未运行测试的情况下声称完成"。这句话看着啰嗦，但确实能拦住不少偷懒行为。

4.3 让 agent 真正执行测试而不是"假装执行"

这是实操中最容易出问题的一环。agent 有时会生成一段测试代码，然后直接说"测试通过"，根本没运行。要杜绝这种情况，技能里必须绑定可执行脚本。

比如在scripts/run-tests.sh里封装好测试命令，技能指令中要求 agent 调用这个脚本，并把脚本的退出码作为判断依据。退出码为 0 才算通过，非 0 一律视为失败。这样判断标准就从"模型说通过"变成了"脚本返回 0"，确定性大大提高。

#!/bin/bash # run-tests.sh set -e npm test echo "EXIT_CODE=$?"

技能里引用这个脚本，agent 调用后拿到真实结果，就没法糊弄了。

4.4 测试失败时 agent 的自我修复边界

测试失败后，agent 应该尝试修复，但要有边界。我的经验是设置最大重试次数，比如三次。三次还修不好，就停下来报告，而不是无限循环。

技能里可以这样描述：修复失败时，先分析失败原因，再针对性修改，每次修改后重跑测试；连续三次失败则停止，输出当前状态和已尝试的方案，交回人工判断。这个边界很重要，没有它，agent 可能在一个死胡同里反复打转，浪费大量 token 和时间。

5. 和 Claude Code 配合时的配置细节

5.1 技能目录与工作区的相对关系

Claude Code 这类工具通常从当前工作区读取配置。技能目录放在哪，直接影响它能不能被发现。常见做法是把agent-skills放在项目根目录，或者放在用户主目录下的全局配置位置。

项目级技能跟着仓库走，团队成员共享；全局技能跟着个人走，跨项目复用。我的建议是：项目特有的规范放项目级，通用能力放全局。比如"本项目的测试命令是 pnpm test"属于项目级，"写测试前先确认测试框架"属于全局。

放错位置会导致技能要么找不到，要么在不该出现的项目里冒出来干扰。

5.2 上下文预算：技能不是越多越好

每个启用的技能都会占用上下文窗口。技能装太多，留给实际代码的空间就被挤压，模型反而变笨。我实测下来，同时启用的技能控制在五到八个比较舒服，超过十个就开始出现"顾此失彼"。

选择启用哪些技能时，按当前任务类型来。做新功能就启用 TDD 相关，做代码审查就启用审查相关，不要一股脑全开。CLI 的 enable/disable 就是为这种场景准备的，养成按需开关的习惯。

5.3 权限与命令执行的注意事项

agent 执行终端命令涉及权限。Claude Code 一般会询问是否允许某类命令，或者通过配置预先授权。技能里如果包含脚本调用，要确保这些脚本在允许列表内，否则每次都要人工确认，体验很差。

我的做法是把技能用到的脚本集中放在一个目录，配置里对这个目录放行，其他位置保持谨慎。这样既保证技能顺畅运行，又不至于把整个终端权限都交出去。安全边界和便利性之间要找个平衡点。

5.4 会话初始化时技能是怎么被加载的

技能通常在会话启动时加载。这意味着会话中途改了技能文件，当前会话不一定生效，需要重开。理解这一点能省下不少困惑——改了配置没反应，先想想是不是没重启会话。

另外，加载是有顺序的，前面提到的优先级在这里起作用。如果发现 agent 行为和你预期的技能不符，先检查加载顺序，再看技能是否真的被启用，最后才怀疑技能内容本身。排查要按这个顺序来，从外到内。

6. 我在实操中踩过的坑和总结的技巧

6.1 技能描述写太满反而失效

刚开始我恨不得把一个技能写成百科全书，把所有可能的情况都覆盖。结果 agent 加载后反而抓不住重点，执行时东一榔头西一棒子。后来我把技能拆小，一个技能只解决一类问题，每个技能的主描述控制在合理长度，效果明显好转。

技能不是文档，是操作指令。指令要短、要准、要可执行。参考资料放references/里按需加载，不要全塞进主描述。

6.2 触发条件模糊导致的"技能不生效"

"技能明明启用了，agent 却不用"——这个问题我遇到不止一次。排查下来，八成是触发描述太模糊。模型判断要不要加载技能，靠的是当前任务和触发描述的语义匹配。描述里如果全是抽象词汇，匹配不上具体任务，技能就形同虚设。

解决办法是往触发描述里加具体场景词。比如不要写"处理代码质量问题"，而要写"当需要为新功能编写测试时""当测试失败需要定位原因时"。越具体，命中越准。

6.3 脚本路径与执行环境的坑

脚本路径写相对路径，在不同工作目录下执行会找不到文件。我现在的习惯是一律用相对于技能目录的路径，或者在脚本里先cd到确定位置。执行环境也要注意，脚本用的解释器、依赖的命令行工具，都要确认在目标环境里存在。

跨平台更麻烦，Windows 和 Unix 的路径分隔符、换行符都不一样。如果团队里有不同系统的成员，脚本尽量写得兼容，或者干脆用跨平台的运行时来写。

6.4 版本管理：技能也要进 Git

技能是代码资产，必须进版本控制。我见过有人把技能放在本地随便一个目录，改来改去没有历史记录，出了问题无法回滚。把agent-skills目录纳入 Git，每次改动都有迹可循，团队协作时也能通过 PR 评审技能变更。

技能变更其实挺敏感的，一个措辞改动可能让 agent 行为大变。有评审流程能拦住不少拍脑袋的修改。

6.5 给新手的上手路径建议

如果你刚接触这套东西，我的建议是别一上来就自己写技能。先从社区现成的技能包开始，装上、启用、观察 agent 行为，理解技能是怎么影响输出的。跑通之后再尝试改一个现成技能，最后才从零写自己的。

这个顺序能让你先建立"技能长什么样、怎么起作用"的直觉，再动手创作。直接上手写，很容易写出不生效的技能，然后陷入"为什么没用"的困惑里。

7. 技能体系的扩展方向

技能跑通之后，可以往几个方向扩展。一是把技能和 CI 打通，让 agent 的产出在提交前自动过一遍测试和检查。二是建立技能库，团队共享常用技能，新人入职直接拉取。三是给技能加指标，统计每个技能的触发频率和成功率，用数据指导优化。

我最近在尝试的是把技能按项目阶段分组，开发阶段启用一组，上线前启用另一组，通过 CLI 快速切换。这样上下文里永远只有当前阶段需要的技能，既省空间又减少干扰。

这套东西的价值不在于技术多复杂，而在于它把"怎么和 AI 协作"这件事从口头约定变成了可执行、可版本化、可复用的资产。刚开始搭的时候会花点时间，但一旦跑顺，后面每个项目都能受益。我自己从零散提示词转到技能体系之后，最大的感受是：终于不用每次开新会话都从头解释一遍了。