企业官网建设流程全解析

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

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词合集"，而是一套把 AI coding agent 当"新同事"来管理的工程化方案。项目正文和关键词都是空的，但热搜词已经把方向交代得很清楚了——AI coding agents、skills CLI、Claude Code、test-driven-development。把这几个词串起来，它想解决的问题其实很具体：当 AI 已经能写代码、能跑终端命令之后，怎么让它稳定地按一套可复用的"技能"干活，而不是每次靠人重新描述一遍需求。

我接触过不少团队在用 Claude Code 这类终端里的 AI 编程助手，最常见的抱怨不是"它不会写"，而是"它写得不稳定"。同一个需求，今天写得挺好，明天换个会话就完全跑偏；让它改个 bug，它顺手把三个不相关的文件也重构了；让它写测试，它写出来的断言全是expect(true).toBe(true)这种糊弄人的东西。这些问题的根子不在模型能力，而在于缺少一套被固化下来的工作规范。agent-skills这个项目名里的 "skills"，我理解就是把这些规范从"人脑里的经验"变成"agent 能加载的技能包"。

所以这篇内容适合谁看？三类人：一是已经在用 Claude Code、但觉得它"时好时坏"的开发者；二是想给团队搭一套 AI 辅助开发流程的技术负责人；三是刚入门、还没搞明白 skills 和普通 prompt 区别的新手。我会从 skills 的本质讲起，一路讲到 CLI 怎么用、TDD 技能怎么落地、以及我在实际配置里踩过的坑。全程不吹概念，只讲能直接抄的东西。

需要先说明一点：下面涉及的具体命令、目录结构、配置字段，是基于这类 skills 工具的常见设计惯例做的合理还原，不同版本可能有差异，你以自己装的那版--help输出为准。但背后的设计逻辑和踩坑经验是通用的。

2. skills 和普通 prompt 到底差在哪

2.1 一个生活化的类比：菜谱 vs 口头交代

你可以把普通 prompt 想成"口头交代做饭"：今天你说"随便炒个青菜"，厨师凭感觉做；明天你说同样的话，他可能多放一勺盐。而 skill 是一张写死的菜谱——几克盐、几分钟火候、先放什么后放什么，全在纸上。厨师换了、心情变了，出来的味道还是那个味道。

放到 AI coding agent 的场景里，这个差别被放大得更明显。普通 prompt 是会话级的，关掉窗口就没了；skill 是文件级的，躺在仓库里，跟着代码一起版本管理。你改了 skill，团队所有人下次调用时用的都是新版。这就是为什么agent-skills这类项目要配一个skills CLI——它管的是"技能的分发、加载和版本"，而不是"这一次对话怎么问"。

2.2 三个核心差异点

我把 skills 相对普通 prompt 的优势拆成三条，每条都对应一个实际痛点：

第三条最关键。普通 prompt 你写"请写高质量测试"，模型的理解是发散的；skill 里你写"每个函数至少一个正常路径用例、一个边界用例、一个异常用例，断言必须检查具体返回值，禁止使用 truthy 断言"，模型的可执行空间就被收窄了。约束越具体，输出越稳定——这是我在调 agent 时最深的体会。

2.3 为什么是 TDD 被单独拎出来当关键词

热搜词里test-driven-development和agent-skills并列出现，不是巧合。TDD 是少数几个天然适合做成 skill 的开发流程，因为它有明确的、可机械执行的循环：先写失败的测试 → 写最小实现让它通过 → 重构。这个循环对 AI agent 来说简直是量身定做，因为每一步都有客观的"完成判据"——测试红了还是绿了，机器说了算，不靠人主观判断。

反过来，如果你让 agent 直接写实现，它很容易"看起来写完了"，但你根本不知道对不对。TDD 把"对不对"这个问题外包给了测试运行器。这也是为什么我强烈建议：给 agent 配的第一个 skill，就应该是 TDD skill。

3. skills CLI 的安装与目录结构拆解

3.1 安装前先确认你的运行环境

在装任何东西之前，先确认你的 agent 本体是能跑的。以 Claude Code 为例，它需要在终端里能正常启动、能执行命令。如果你连claude命令都还没跑起来，先去把基础环境搞定——skills CLI 是建立在 agent 之上的工具，agent 本身不通，装 skills 就是空中楼阁。

安装 skills CLI 的常见方式是通过包管理器。假设它发布在 npm 上，典型命令是：

npm install -g agent-skills-cli

装完之后验证一下：

skills --version skills --help

--help的输出是你最该花五分钟读的东西。它会告诉你这个版本支持哪些子命令——通常是init、add、list、remove、sync这几类。不同版本子命令名可能不一样，别照着某篇老教程硬敲，先看自己的 help。

提示：如果你在受限网络环境下遇到安装失败，优先检查包管理器的镜像源配置，而不是反复重试。国内用 npm 的话，配置一个可用的 registry 镜像通常能解决大部分下载超时问题。

3.2 目录结构：skills 到底存在哪

这是新手最容易懵的地方。skills 一般有两级存放位置：

• 全局级：放在用户主目录下，比如~/.agent-skills/或~/.config/skills/，对所有项目生效。
• 项目级：放在项目根目录下，比如./.agent-skills/或./skills/，只对当前仓库生效，且能随 git 提交给团队。

我建议的用法是：通用技能放全局，项目专属技能放项目级。比如 TDD 流程、代码审查规范这种到哪都用的，放全局；而"这个项目的数据库迁移必须走 XX 脚本"这种，放项目级。

一个典型的 skill 目录长这样：

.agent-skills/ ├── tdd/ │ ├── SKILL.md # 技能主文件，描述何时触发、怎么做 │ ├── templates/ # 可选的模板文件 │ └── examples/ # 可选的示例 ├── code-review/ │ └── SKILL.md └── config.json # 可选的全局配置

核心是那个SKILL.md。它通常包含三块：触发条件（什么情况下该用这个技能）、执行步骤（一步步怎么做）、约束与禁止项（哪些事绝对不能干）。这三块写得好不好，直接决定技能好不好用。

3.3 初始化一个项目

在项目根目录跑：

skills init

它会创建项目级的 skills 目录和一份默认配置。跑完之后ls -la看一眼，确认目录真的建出来了。我见过有人init完没检查，结果因为权限问题目录建到了别的地方，后面add技能一直找不到路径，排查了半天。

初始化之后，用skills list看看当前加载了哪些技能。这个命令应该成为你的习惯动作——每次改完 skill 配置，先 list 一遍确认加载状态，比直接跑 agent 然后纳闷"为什么没生效"要高效得多。

4. 手把手写一个 TDD skill

4.1 为什么第一个 skill 选 TDD

前面说了 TDD 有客观判据，这里再补一个理由：它能强制 agent 慢下来。AI agent 最大的毛病是"抢跑"——你话还没说完，它已经把三个文件改完了。TDD skill 通过"必须先写测试、必须看到测试失败、才能写实现"这个硬性顺序，把它的节奏压下来。节奏一慢，出错率肉眼可见地下降。

4.2 SKILL.md 的骨架怎么写

下面是我实际用下来比较稳的一个 TDD skill 骨架。注意，这不是让你照抄，而是让你理解每一段为什么这么写：

# TDD Skill ## 何时使用 当用户要求实现新功能、修复 bug、或重构现有代码时触发。 ## 执行步骤 1. 先阅读相关代码，理解现有结构，不要急着动手。 2. 编写一个会失败的测试，覆盖目标行为。 3. 运行测试，确认它确实失败（红）。 4. 编写最小实现，让测试通过（绿）。 5. 运行全部测试，确认没有破坏其他用例。 6. 在测试全绿的前提下重构，重构后再次运行测试。 ## 约束 - 禁止在测试失败前编写实现代码。 - 禁止修改测试来迁就实现，除非测试本身写错了。 - 每个测试必须断言具体的返回值或状态，禁止 truthy 断言。 - 一次只处理一个行为，不要批量实现多个功能。

逐段解释一下为什么这么设计。第一步"先阅读再动手"是为了防止 agent 在不了解上下文的情况下乱改；第二步到第四步是 TDD 的核心循环，把"红-绿"作为强制检查点；第五步"运行全部测试"是为了防止它只顾新功能、把老功能改坏；第六步把重构放在最后，是因为重构最容易引入回归，必须建立在测试全绿的基础上。

约束部分每一条都对应一个我踩过的坑。"禁止 truthy 断言"是因为 agent 特别爱写expect(result).toBeTruthy()这种，看着测试过了，其实什么都没验证。"一次只处理一个行为"是因为它一旦被允许批量做，就会一口气写五个功能然后测试全挂，你还得挨个排查。

4.3 把 skill 注册进去

写完SKILL.md之后，用 CLI 把它加进来：

skills add ./tdd

或者如果技能已经在全局目录里：

skills add tdd --global

加完skills list确认一下。然后启动你的 agent，给它一个真实的小任务试试，比如"给这个工具函数加一个参数校验"。观察它是不是真的先写测试、先跑红、再写实现。第一次跑大概率不会完全按你想的来，这时候别急着否定 skill，先看它卡在哪一步，然后回去改SKILL.md里对应的描述。skill 是迭代出来的，不是一次写对的。

4.4 一个真实的调试片段

我第一次写 TDD skill 时，agent 确实先写了测试，但它写完测试没有运行就直接写实现了。问题出在我没在步骤里明确写"运行测试并确认失败"。我加了一句"运行测试命令，把输出贴出来，确认是失败状态后再继续"，它才老实了。

这个细节说明一个道理：skill 里的每一步都要写到"可验证"的程度。"写测试"不可验证，"写测试并运行、确认输出为失败"才可验证。你写 skill 的时候，脑子里要有个挑剔的审查员，问自己"我怎么知道它真做了这一步"。

5. 让 skill 真正生效的几个关键配置

5.1 触发条件写得太宽或太窄都是坑

skill 的触发条件（何时使用）是最难拿捏的部分。写太宽，比如"任何时候都触发"，那 agent 干任何事都套 TDD 流程，你让它改个错别字它都要先写测试，烦不胜烦。写太窄，比如"仅当用户明确说'用 TDD'时触发"，那它基本不会被用到。

我的经验是：用"任务类型"而不是"用户措辞"来定义触发。比如"当任务涉及新增函数、修改函数行为、修复 bug 时触发"，这样即使用户没说 TDD，agent 也会自动走这套流程。同时给一个逃生口："当任务仅为文档修改、注释调整、格式整理时，跳过本技能。"

5.2 多个 skill 的优先级冲突

当你装了 TDD、code-review、refactor 好几个 skill 之后，会遇到优先级问题：一个任务同时满足多个 skill 的触发条件，先走哪个？

常见做法是在配置里给 skill 排优先级，或者在每个 skill 里写明"本技能应在 XX 技能之后执行"。比如 code-review 通常应该在 TDD 完成之后跑，因为审查的对象是已经通过测试的代码。我一般会在config.json里维护一个执行顺序列表，避免 agent 自己乱序执行。

注意：如果你发现 agent 同时套用了两个互相矛盾的 skill（比如一个要求"先写测试"，另一个要求"先写实现"），八成是触发条件重叠了。回去把两个 skill 的触发边界划清楚，别指望 agent 自己判断。

5.3 环境变量与模型接入的注意事项

热搜词里出现了不少关于模型接入、第三方 API 的内容。这里我只讲一个通用原则：skill 的行为和底层模型强相关。同一个 TDD skill，在能力强的模型上跑得很顺，换到能力弱的模型上可能连"先写测试"都执行不到位。所以如果你切换了底层模型，建议重新跑一遍 skill 的验证用例，确认行为没有退化。

另外，skill 里如果需要 agent 执行终端命令（比如跑测试），要确保 agent 有相应的命令执行权限，并且测试命令本身是安全的、幂等的。别让 skill 触发一个会删库的命令——这种事故我听说过不止一次。

6. 实测中踩过的坑与排查链路

6.1 坑一：skill 加载了但完全不生效

现象：skills list显示技能已加载，但 agent 行为跟没装一样。

排查链路：第一步，确认 agent 启动时的工作目录是不是项目根目录——如果 agent 在子目录启动，项目级 skill 可能加载不到。第二步，检查SKILL.md的触发条件是不是写得太苛刻，导致当前任务压根没匹配上。第三步，看 agent 的日志输出，很多 agent 会打印"加载了哪些 skill"，从日志能直接看出问题。我遇到的那次是工作目录不对，切到根目录启动就好了。

6.2 坑二：agent 假装运行了测试

现象：agent 说"测试已通过"，但你手动跑一遍发现根本没通过。

根因：agent 可能只是"声称"运行了命令，实际没执行，或者执行了但没读输出。这在能力较弱的模型上很常见。

解决：在 skill 里强制要求"把测试命令的原始输出贴出来"。只要它必须贴输出，就没法假装。另外，你可以在关键节点手动介入，自己跑一遍测试确认。永远不要完全信任 agent 的自我报告，这是用 AI 编程的铁律。

6.3 坑三：测试越写越多，跑一次要十分钟

现象：TDD skill 用久了，测试套件膨胀，每次改动都要跑全量测试，慢得让人抓狂。

解决：在 skill 里区分"快速测试"和"全量测试"。开发循环里只跑跟当前改动相关的测试子集，提交前才跑全量。具体怎么筛子集，取决于你用的测试框架，一般支持按文件路径或标签过滤。把这个策略写进 skill，agent 就不会每次都傻乎乎地跑全量。

6.4 坑四：重构阶段把测试改绿了

现象：agent 在重构时发现测试挂了，于是去改测试让它通过，而不是改实现。

根因：skill 的约束没写死。虽然我前面写了"禁止修改测试来迁就实现"，但 agent 有时会绕过这条。

加固：在 skill 里加一条更硬的规则——"重构阶段禁止修改任何测试文件，如果测试失败，必须回退重构并说明原因"。同时，你可以在 code-review skill 里加一个检查点：对比重构前后的测试文件，如果测试被改了，标记为可疑。

6.5 坑五：团队协作时 skill 版本不一致

现象：你本地跑得好好的 skill，同事拉下来跑就出问题。

根因：skill 文件没提交到 git，或者提交了但同事没同步。

解决：项目级 skill 一定要纳入版本管理，并且在 README 里写明"拉代码后先跑skills sync"。全局级 skill 则建议在团队内统一版本，别各装各的。我见过最乱的情况是，五个人装了五个版本的 TDD skill，同一个任务跑出五种结果，排查起来简直是灾难。

7. 把 skills 用成团队资产而不是个人玩具

7.1 skill 的迭代应该像代码一样有 review

很多人写 skill 是"自己写完自己用"，这在小团队里没问题，但一旦要共享，就必须有 review 流程。因为 skill 里的一句话改动，可能影响所有人的 agent 行为。我建议把SKILL.md的改动纳入正常的 code review，让至少一个人看过再合并。

review 的时候重点看三样：触发条件有没有变宽导致误触发、约束有没有被削弱、步骤有没有变得不可验证。这三样是 skill 质量的命门。

7.2 用真实任务反哺 skill

skill 不是写完就完事的。每次 agent 在某个任务上表现不好，你都应该问自己：这是模型能力问题，还是 skill 没覆盖到？如果是后者，就把这次的教训补进 skill。比如 agent 又一次忘了跑测试，你就在步骤里把"运行测试"写得更显眼、更靠前。

我自己的 TDD skill 迭代了大概七八版，每一版都是被真实翻车逼出来的。skill 的价值不在于写得多漂亮，而在于它沉淀了多少你踩过的坑。

7.3 别把 skill 写成"万能许愿池"

最后一个提醒：skill 不是越多越好，也不是越详细越好。我见过有人写了一个两千行的 skill，把能想到的规则全塞进去，结果 agent 加载后反而变笨了——因为规则太多，它顾此失彼。好的 skill 应该是短小、聚焦、每条规则都有明确目的。一个 skill 只解决一类问题，需要更多能力就拆成多个 skill，让 agent 按需加载。

我在实际使用中的体会是，一个健康的 skills 体系，通常也就五到八个核心技能，覆盖开发流程的主要环节。再多，维护成本就超过收益了。与其堆数量，不如把每个 skill 打磨到"闭着眼睛都知道它会怎么执行"的程度——那种确定性，才是 skills 这套东西真正值钱的地方。