企业官网建设流程全解析

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

第一次看到agent-skills这个项目名，我的直觉是：这不是一个具体的应用，而是一套给 AI coding agent 用的技能集合。换句话说，它解决的不是"AI 能不能写代码"，而是"AI 写代码时该按什么套路来"。

这个区别很关键。现在市面上讨论 AI 编程，绝大多数注意力都放在模型能力上——哪个模型跑分高、哪个模型上下文长、哪个模型便宜。但真正在项目里用过 AI coding agent 的人都知道，模型能力只是下限，决定产出质量的是你喂给它的工作流。同一个模型，你让它"帮我写个登录功能"，和让它"先写测试、再写实现、最后跑一遍验证"，出来的东西完全是两个档次。

agent-skills要干的事，就是把这套工作流固化下来，变成 agent 可以加载、可以复用、可以组合的"技能包"。关键词里出现的skills CLI、test-driven-development、Claude Code这几个词，基本勾勒出了它的轮廓：一个命令行工具，用来管理技能；技能的核心范式之一是测试驱动开发；主要面向 Claude Code 这类 AI coding agent 生态。

所以这篇东西适合谁看？三类人。第一类是在用 Claude Code 或者类似工具、但总觉得产出不稳定的开发者；第二类是想给自己团队搭一套 AI 编程规范的技术负责人；第三类是对"agent 技能"这个概念还比较模糊、想搞清楚它到底和 prompt 有什么区别的人。我会从概念拆解讲到实操落地，中间穿插我自己踩过的坑。

2. agent-skills 到底解决了什么问题

2.1 从"每次都要重新交代"说起

用 AI coding agent 最烦的一件事，是上下文重置。你开一个新会话，它对你的项目一无所知：不知道你用什么测试框架、不知道你的目录结构约定、不知道你的错误处理风格、不知道你提交前要跑哪些检查。你得重新交代一遍，交代得不全，它就自由发挥，发挥出来的东西你还得改。

有人会说，那我写个CLAUDE.md或者系统提示词不就行了？可以，但很快就会遇到瓶颈。当你的规范越来越多——代码风格、测试要求、提交规范、review 清单、特定框架的坑——全塞进一个文件里，它会变得又长又难维护，而且 agent 每次都要读全部内容，token 消耗上去了，注意力还被稀释了。

agent-skills的思路是把这些规范模块化。一个技能就是一个独立单元，比如"写单元测试"是一个技能，"做代码审查"是一个技能，"处理数据库迁移"是一个技能。需要哪个加载哪个，互不干扰。这就像从"一本厚厚的员工手册"变成"一柜子可以按需取用的操作手册"。

2.2 技能和 prompt 的本质区别

很多人第一次接触这个概念会问：这不就是 prompt 模板吗？不完全是。区别在三个地方。

第一是触发方式。prompt 模板需要你手动调用，你得记得"哦这个场景该用那个模板"。而技能通常带有触发条件描述，agent 会根据当前任务自动判断该不该加载。你让它改一个 bug，它自己意识到"这需要先复现问题"，然后加载对应的调试技能。

第二是结构化程度。一个 prompt 模板往往就是一段文字。而一个技能通常包含：适用场景说明、前置条件、执行步骤、验证方法、常见错误。它是流程，不是话术。

第三是可组合性。技能之间可以嵌套和引用。一个"实现新功能"的技能，内部可能调用"写测试"和"更新文档"两个子技能。这种组合能力是纯 prompt 做不到的。

2.3 为什么 test-driven-development 会成为核心技能

关键词里test-driven-development单独列出来，不是偶然。在 AI 编程场景下，TDD 的价值被放大了。

原因很直接：AI 写的代码，你需要一个自动化的方式来判断它对不对。人写代码，你 review 一遍心里有数。AI 写代码，尤其是它一次生成几百行的时候，你 review 的成本可能比自己写还高。但如果先让它写测试，测试跑通了，至少说明行为符合预期。

更妙的是，测试本身就是一种精确的需求描述。你用自然语言说"实现一个用户注册功能"，歧义一大堆。但你写一个测试说"传入已存在的邮箱应该返回 409 错误"，这个要求就没有歧义了。所以 TDD 在 agent 场景下不只是质量保障手段，它还是需求传递手段。

我在实际项目里的做法是：先和 agent 一起把测试用例讨论清楚，让它写测试，我确认测试逻辑没问题，然后再让它写实现。这样我的 review 精力集中在"测试写得对不对"上，而不是"实现写得对不对"上。前者是几十行，后者可能是几百行。

3. skills CLI 的工作方式与目录约定

3.1 技能在文件系统里长什么样

agent-skills这类工具通常遵循一个约定：技能以目录形式存在，每个目录里有一个描述文件加若干资源文件。典型结构是这样：

skills/ test-driven-development/ SKILL.md examples/ templates/ code-review/ SKILL.md checklist.md

SKILL.md是这个技能的主文件，里面用 frontmatter 声明元信息，正文写具体内容。frontmatter 一般包含name（技能名）、description（什么时候该用这个技能）、可能还有version和依赖声明。

这里有个容易忽略的细节：description 的写法直接决定技能会不会被正确触发。我见过太多人把 description 写成"这是一个用于测试的技能"这种废话，结果 agent 根本不知道什么时候该加载它。好的 description 应该写清楚触发场景，比如"当需要为新功能编写测试、或修复 bug 需要先复现问题时使用"。

3.2 CLI 的常见命令与用途

skills CLI一般提供这几类操作，我按使用频率排：

skills validate这个命令值得单独说。技能文件的 frontmatter 格式错了、description 缺失、引用的资源文件不存在，这些问题在运行时往往表现为"技能莫名其妙不生效"，排查起来很痛苦。养成改完技能就跑一次 validate 的习惯，能省很多时间。

3.3 全局技能与项目技能的取舍

技能可以放在两个位置：用户级目录（全局）和项目级目录。这个选择有讲究。

放全局的技能，是那些跨项目通用的，比如"如何写清晰的 commit message"、"如何做代码审查"。放项目级的，是那些和具体技术栈绑定的，比如"这个项目用 Vitest 不用 Jest"、"这个项目的 API 错误码规范"。

我的经验是：宁可先放项目级，用一段时间确认真的通用了再往上提。反过来操作的话，你会在全局目录里堆一堆只用过一次的技能，然后skills list输出长得没法看，找东西全靠 grep。

4. 把 TDD 技能真正跑起来的关键细节

4.1 测试先行不等于测试乱写

让 agent 写测试，最大的风险是它写出一堆看起来很像测试但实际没验证任何东西的代码。比如：

test('用户注册功能正常', () => { const result = register('test@example.com', 'password123'); expect(result).toBeDefined(); });

这个测试永远会通过，因为它只检查了"有返回值"。agent 很容易生成这种测试，因为它在"模仿测试的样子"而不是"验证具体行为"。

所以 TDD 技能里必须有一条硬性要求：每个测试都要有明确的、可能失败的断言。我在自己的技能文件里会写这么一段约束：

禁止使用toBeDefined、toBeTruthy这类弱断言作为主要验证手段。每个测试必须验证具体的值、具体的错误类型或具体的状态变化。

加了这条之后，agent 写出来的测试质量明显不一样。

4.2 红绿重构在 agent 场景下的变形

标准 TDD 是"红-绿-重构"：先写一个失败的测试，再写让测试通过的最少代码，最后重构。在 agent 场景下，这个循环需要一点调整。

问题在于，如果你让 agent 一次性写完所有测试再写实现，它会倾向于根据实现来倒推测试，而不是根据需求来写测试。这就失去了 TDD 的意义。

我的做法是分批。一次只让 agent 处理一个测试用例：写测试、跑、确认失败、写实现、跑、确认通过。一个用例走完再走下一个。这样虽然交互轮次多了，但每一步都是可控的，出问题能立刻定位。

如果嫌轮次太多，可以退一步：让它一次写 3 到 5 个相关测试，但要求它先只写测试、不要写实现，等我确认测试逻辑后再继续。这个"暂停点"很关键。

4.3 测试跑不起来时先怀疑环境

有个坑我踩过不止一次：agent 写完测试，跑起来报错，然后它开始"修复"——改测试、改配置、装依赖，越改越乱。最后发现是测试命令本身就不对。

所以在 TDD 技能的前置条件里，我会明确写：在开始写任何测试之前，先确认测试命令能跑通一个最简单的样例测试。这一步花不了两分钟，但能避免后面半小时的瞎折腾。

具体操作就是先手动跑一次npm test或者对应的命令，看它能不能正常启动、能不能识别测试文件、退出码是不是符合预期。确认了再让 agent 接手。

5. 技能组合与 Claude Code 的配合方式

5.1 技能不是越多越好

刚开始用的时候很容易上头，恨不得把能想到的规范都写成技能。结果就是 agent 每次任务要加载七八个技能，上下文被塞满，反而变笨了。

我的建议是控制在 5 到 8 个核心技能。超过这个数量，就该考虑合并或者分层了。比如"写测试"和"跑测试"可以合成一个"测试工作流"技能，没必要拆开。

判断一个技能该不该独立存在，我的标准是：它是否有独立的触发场景。如果两个技能总是在同一时间被用到，那它们大概率应该合并。

5.2 技能之间的引用要克制

技能 A 引用技能 B，听起来很优雅，但实际维护起来是噩梦。B 改了，A 可能就失效了，而且这种失效往往是静默的——agent 加载了 A，A 说"参考 B 的做法"，但 B 的内容已经变了。

我的做法是：技能之间尽量不互相引用，需要共享的内容直接复制。这违反了 DRY 原则，但在技能这个场景下，可预测性比复用性重要。技能文件本来就不长，复制带来的维护成本远低于隐式依赖带来的调试成本。

5.3 和 Claude Code 的加载时机

Claude Code 这类工具加载技能的方式，通常是读取项目根目录下的约定目录。所以你要确保技能目录在正确的位置，并且 agent 有权限读取。

一个实际会遇到的问题是：技能加载了但没生效。排查顺序我一般是这样的：

1. 先确认技能文件格式对不对，跑skills validate
2. 再看 description 是否写清楚了触发场景
3. 然后检查是不是有多个技能冲突，agent 不知道该用哪个
4. 最后才怀疑是不是 agent 本身的问题

大部分情况问题出在前两步。description 写得太模糊是重灾区。

6. 我在实际使用中踩过的坑

6.1 技能写得太抽象等于没写

我最早写的一个技能叫"写高质量代码"，description 是"当需要编写代码时使用"。结果就是它要么不触发，要么触发了也没用——因为里面全是"要注意可读性""要遵循最佳实践"这种正确的废话。

后来我把它拆成了三个具体技能：错误处理规范、命名约定、函数拆分原则。每个都带具体例子。效果立刻不一样了。技能的价值在于具体，抽象的原则 agent 本来就知道，不需要你教。

6.2 忘了给技能加"停止条件"

agent 有个特点：你让它做一件事，它倾向于一直做下去。比如你让它"重构这个模块"，它可能重构完一个文件接着重构下一个，最后改了一大片。

所以技能里要写清楚边界。比如"只处理当前指定的文件，不要主动扩展到其他文件"、"如果发现需要改动超过 3 个文件，先停下来询问"。这些约束看起来啰嗦，但能省掉大量回滚的麻烦。

6.3 测试通过不等于功能正确

这是最隐蔽的坑。agent 写的测试通过了，实现也写完了，但功能就是不对。原因往往是测试和实现犯了同一个错误——比如对需求的理解本身就偏了。

所以我现在会加一步：让 agent 用自然语言复述一遍它理解的验收标准，我确认无误后再让它动手。这一步花不了一分钟，但能拦住相当一部分方向性错误。

6.4 版本升级后技能失效

agent-skills这类工具和 Claude Code 本身都在快速迭代，技能文件的格式、frontmatter 的字段、加载机制都可能变。我有一次升级工具版本后，所有技能都不触发了，排查半天才发现是 frontmatter 的字段名改了。

所以升级工具后，第一件事是跑一遍 validate，第二件事是拿一个技能做端到端测试，确认整条链路还是通的。别等到写代码写到一半才发现技能没加载。

7. 给想上手的人几条实在建议

如果你现在想开始用agent-skills，我的建议是别一上来就搭大而全的体系。先挑一个你最近反复遇到的场景，比如"每次让 AI 写测试都要重新交代测试框架"，把它做成一个技能。用一周，感受一下它到底省了多少事、有没有副作用。

确认有效之后，再逐步扩展。扩展的顺序我建议是：测试相关 → 代码审查相关 → 提交规范相关 → 项目特定的技术栈约定。这个顺序是从通用到具体，符合大多数项目的实际需求分布。

另外，技能文件本身也是代码，值得纳入版本管理。团队里谁改了什么技能、为什么改，都应该有记录。我见过团队把技能文件放在共享盘里，结果两个人同时改冲突了，谁也不知道该用哪个版本。

最后说一个心态上的事：技能是帮你省事的，不是给你添活的。如果一个技能维护起来比它省下的时间还多，那就该删掉。我每隔一两个月会清理一次技能目录，把那些一个月都没触发过的删掉。留下来的，才是真正有价值的。