企业官网建设流程全解析

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

第一次看到agent-skills这个仓库名，我的直觉是：这大概率不是一个应用项目，而是一个技能集合——也就是给 AI coding agent 用的"能力包"。事实也确实如此。它解决的是一个非常具体、也非常痛的问题：AI 编程助手很聪明，但它不知道你的项目该怎么写、该遵守什么规范、该跑哪些命令。

你可以把 agent-skills 理解成给 AI 助手准备的一套"上岗培训手册"。没有它的时候，你让 Claude Code 帮你改一个函数，它可能给你写出一堆风格完全不符合项目习惯的代码；有了它，AI 会先读你的规范、再动手，甚至会自动跑测试、自动检查 lint。

这个仓库的核心价值在于三点：

• 把"隐性知识"显性化：团队里老员工才知道的编码规范、测试流程、提交信息格式，全部写成 AI 能读懂的 skill 文件。
• 让 AI 的行为可复现：同一个 skill 在不同人、不同机器上跑出来的效果一致，不会因为"今天 AI 心情好"就写出不一样的代码。
• 降低上手门槛：新人接手项目，AI 已经知道该怎么做了，不需要口口相传。

适合谁来读这篇内容？三类人最合适：一是已经在用 Claude Code 或类似 AI coding agent、但觉得"它总是不听话"的开发者；二是团队里负责工程规范、想让 AI 帮忙落地规范的技术负责人；三是想搞清楚"skills CLI 到底是个什么东西"的探索型选手。如果你还没装过 Claude Code，也没关系，我会在讲 skill 机制的时候顺带把相关背景补上。

需要提前说明的是，agent-skills 本身是一个约定和目录结构，不是某个特定厂商的私有格式。它的设计思路是"用 Markdown 描述技能，用 CLI 管理技能"，所以理论上任何支持读取本地上下文文件的 AI agent 都能用。这也是它比"某个 IDE 插件内置的提示词模板"更有生命力的地方。

2. agent-skills 的目录结构与 skill 文件到底长什么样

2.1 一个 skill 的最小构成

在 agent-skills 的约定里，一个 skill 通常就是一个目录，目录里至少有一个入口文件（一般是SKILL.md或skill.md），再加上可选的辅助资源。这个设计非常像"给 AI 看的一份说明书 + 一堆参考资料"。

一个典型的最小 skill 长这样：

skills/ test-driven-development/ SKILL.md examples/ red-green-refactor.md scripts/ run-tests.sh

SKILL.md是核心，它用自然语言 + 结构化字段告诉 AI：这个技能叫什么、什么时候用、怎么用、有哪些注意事项。辅助目录则是"证据"和"工具"——例子给 AI 参考，脚本给 AI 直接调用。

2.2 SKILL.md 里通常写什么

我拆过不少 skill 文件，结构上大同小异，一般包含这几块：

• name / description：技能名和一句话描述。description 特别关键，AI 就是靠它判断"当前任务要不要加载这个技能"。
• when to use：触发条件。写得越具体，AI 误触发越少。
• instructions：具体步骤。这是主体，通常用有序列表写。
• examples：正例和反例。反例往往比正例更有价值，因为 AI 最容易犯的错就是"看起来对但实际错"。
• constraints：硬性约束，比如"禁止直接修改 main 分支""必须跑完测试才能提交"。

这里有个很多人忽略的细节：description 的写法直接决定了 skill 的命中率。如果你写"用于测试"，AI 基本不会在合适的时候想起来用它；如果你写"当用户要求新增功能或修复 bug 时，在写任何实现代码之前使用本技能，先写失败测试"，命中率会高得多。这是我在实际配置里反复验证过的经验。

2.3 为什么用 Markdown 而不是 JSON/YAML

有人会问：既然是给机器读的，为什么不用结构化格式？答案很简单——AI 读自然语言比读结构化配置更准。JSON 适合程序解析，但 AI 在理解"什么时候该用"这种模糊判断时，自然语言的表达力更强。Markdown 还能顺便给人看，团队 review skill 文件时不需要额外工具。

提示：skill 文件不是越长越好。我见过有人把整个编码规范 3000 字全塞进一个 skill，结果 AI 加载后反而抓不住重点。单个 skill 控制在 500 到 1500 字比较合适，超出的部分拆成多个 skill 或用引用文件。

3. skills CLI：安装、管理与在 Claude Code 里跑起来

3.1 环境准备与安装路径

skills CLI 是一个命令行工具，用来安装、列出、更新、删除 skill。它的安装方式通常是包管理器一把梭。以常见的 Node 生态为例：

# 全局安装 skills CLI npm install -g skills-cli # 验证安装 skills --version

如果你用的是 Claude Code，安装完 CLI 之后，还需要让 Claude Code 知道去哪里找 skill。通常有两种做法：

1. 项目级：在项目根目录放一个skills/目录，Claude Code 启动时会自动扫描。
2. 用户级：放在用户主目录下的配置目录里，对所有项目生效。

我个人的建议是：通用技能放用户级，项目专属技能放项目级。比如"如何写 commit message"这种通用规范放用户级；"本项目用 pnpm 不用 npm"这种放项目级。这样既避免重复配置，又保证项目隔离。

3.2 用 CLI 管理 skill 的常用命令

CLI 的价值在于把"手动复制目录"这种容易出错的操作标准化。常用命令大致是这几类：

skills doctor这个命令我要特别提一下。很多人配完 skill 发现 AI 根本不读，八成是路径不对或者文件权限有问题。doctor 会把扫描路径、找到的文件、解析结果全列出来，比瞎猜快得多。

3.3 在 Claude Code 里验证 skill 是否生效

配好之后怎么确认 AI 真的在用？我的做法是故意制造一个违反规范的场景。比如你的 skill 里写了"所有函数必须有 JSDoc 注释"，那就让 Claude Code 写一个新函数，看它会不会自动加注释。如果没加，说明 skill 没被加载，回去查路径。

另一个验证方法是直接问 AI："你现在加载了哪些 skill？" 大多数 agent 会如实回答。这招在调试阶段特别好用，能快速定位是"没加载"还是"加载了但没触发"。

注意：不同版本的 Claude Code 对 skill 的扫描时机不一样。有的是启动时扫一次，有的是每次对话前扫。如果你改了 skill 文件但没生效，先重启一次 agent 再判断。

4. 用 test-driven-development 这个 skill 讲清楚"技能怎么落地"

4.1 为什么拿 TDD 当例子

test-driven-development是 agent-skills 里最经典、也最能体现"技能价值"的一个。原因很简单：TDD 是一种反直觉的工作方式。人的本能是先写实现再补测试，而 TDD 要求先写失败测试。AI 如果没有被明确约束，默认也会走"先实现"的老路。所以这个 skill 的存在，本质上是在对抗 AI 的默认行为。

4.2 这个 skill 的核心指令拆解

一个写得好的 TDD skill，指令通常包含这几个关键点：

• 强制顺序：先写测试，运行确认失败（红），再写实现让它通过（绿），最后重构。
• 禁止跳步：明确写"在测试失败之前，不允许写任何实现代码"。
• 失败验证：要求 AI 必须实际运行测试并展示失败输出，而不是"我觉得它会失败"。
• 小步提交：每个红绿循环结束后才允许提交。

这里最关键的是第三条。我踩过的坑是：AI 会"假装"测试失败了，直接进入实现阶段。后来我在 skill 里加了一句"必须粘贴测试运行的真实输出"，问题才解决。这就是 skill 需要迭代的原因——第一版永远不够，要根据 AI 的实际行为不断打补丁。

4.3 实际跑一遍的流程

假设你让 Claude Code 实现一个"计算购物车总价"的函数，加载了 TDD skill 之后，理想流程是这样的：

1. AI 先写一个测试文件，断言calculateTotal([])返回 0。
2. AI 运行测试，展示失败输出（函数还不存在）。
3. AI 写最小实现让测试通过。
4. AI 再加一个测试用例（比如有商品的情况），重复红绿循环。
5. 全部通过后，AI 才做重构。

这个流程看起来慢，但实测下来返工率大幅下降。因为 AI 在写实现之前已经被测试"框住"了，不会天马行空地加一堆用不上的功能。

4.4 常见失效场景

TDD skill 也不是万能的。我遇到过几种失效情况：

• 项目没有测试框架：AI 想跑测试但跑不起来，skill 就卡住了。解决办法是在 skill 里加一句"如果项目没有测试框架，先询问用户是否安装"。
• 测试运行太慢：AI 等不及就跳过验证。可以在 skill 里指定只跑相关测试文件，而不是全量。
• AI 把测试写得太宽松：断言写得跟没写一样。这需要在 skill 的 examples 里放反例，明确"这种测试不算数"。

5. 自己写一个 skill：从需求到可用的完整过程

5.1 先想清楚"这个技能解决什么重复问题"

写 skill 之前先问自己：这件事我是不是每次都要跟 AI 重复说一遍？如果是，它就值得写成 skill。比如"我们的 API 错误码必须用枚举""数据库迁移必须写回滚脚本""组件必须用函数式写法"——这些都是高频重复的规范。

反过来，一次性的任务不值得写 skill。skill 的维护成本不低，写多了反而让 AI 的选择变困难。

5.2 描述触发条件的写法

触发条件是 skill 的灵魂。我总结了一个模板：

当 [具体场景] 时，在 [具体动作] 之前，使用本技能。

比如："当用户要求新增 API 接口时，在写任何路由代码之前，使用本技能。" 这种写法把"场景"和"时机"都锁死了，AI 误触发和漏触发的概率都会降低。

5.3 指令要写成"可执行步骤"而不是"原则"

这是新手最容易犯的错。写"代码要整洁"没用，AI 不知道什么叫整洁。要写成"函数不超过 30 行""每个函数只做一件事""变量名用完整单词不用缩写"。原则是给人看的，步骤才是给 AI 用的。

5.4 用 examples 校准 AI 的判断

examples 部分我建议至少放两组：一组"正确示范"，一组"错误示范"。错误示范要标注清楚"为什么错"。实测下来，AI 对反例的敏感度比正例高，因为反例帮它划定了边界。

5.5 迭代：第一版跑一周再改

skill 不是一次写完的。我的习惯是：第一版先上线，用一周，记录 AI 哪些地方没按预期做，然后针对性补指令。通常迭代两三轮之后，skill 就稳定了。

6. 把 skill 用顺的几个实战心得

6.1 skill 数量要克制

我见过有人装了 30 多个 skill，结果 AI 每次都要在大量描述里做选择，反而容易选错。我的经验是：常用 skill 控制在 5 到 10 个，其余按需临时启用。skill 太多不是能力强，是噪音大。

6.2 命名要能"自解释"

skill 的名字最好一眼能看出用途。tdd不如test-driven-development清晰，api-style不如api-error-handling具体。名字清晰，AI 在选择时也更准。

6.3 版本管理别偷懒

skill 文件应该跟代码一起进版本库。这样团队里谁改了规范，其他人 pull 一下就同步了。我见过把 skill 放在本地不提交的，结果每个人 AI 行为都不一样，排查问题极其痛苦。

6.4 定期清理失效 skill

项目重构之后，有些 skill 可能已经过时了。比如原来用 Jest，现在换 Vitest，测试相关的 skill 就得更新。建议每个季度过一遍 skill 列表，删掉不再用的。

6.5 别指望 skill 解决所有问题

skill 能约束 AI 的行为，但约束不了 AI 的理解能力。如果任务本身描述不清，再好的 skill 也救不了。skill 是放大器，不是补丁。

7. 关于 agent-skills 生态的一点个人观察

agent-skills 这类项目的出现，其实反映了一个趋势：AI coding agent 的竞争，正在从"模型多聪明"转向"上下文多准确"。模型能力大家都能买到，但"AI 懂不懂你的项目"是买不到的，只能靠 skill 这种机制一点点喂出来。

我在实际使用中最大的体会是：skill 写得好的团队，AI 的产出质量能接近中级工程师；skill 写得差的团队，AI 就是个高级自动补全。差距不在模型，在上下文工程。

另外，skills CLI 这种工具的价值会随着 skill 数量增长而放大。当你有几十个 skill 要管理时，手动复制目录就是灾难。所以如果你打算认真用，早点把 CLI 用起来，别等到乱了再补。

最后分享一个小技巧：把 skill 当成"给新同事的入职文档"来写。如果你写的东西能让一个刚入职的工程师看懂并照做，那 AI 大概率也能看懂。这个标准比"写给机器看"更实用，也更容易写出高质量的 skill。