企业官网建设流程全解析

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

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 当"新同事"来培养的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development，这三者放在一起，指向一个很明确的问题域——如何让一个命令行里的 AI 编码代理，稳定地按照工程规范干活，而不是每次都要你从头解释一遍"我们团队怎么做事"。

大多数人用 AI 编码工具的方式是"对话式"的：打开终端，敲一句需求，等它吐代码，不满意再补一句。这种方式在一次性脚本上没问题，但一旦进入真实项目——有测试、有 lint、有提交规范、有目录约定——你就会发现每次都要重复交代背景，而且它经常"自作聪明"地跳过测试、改坏命名、把临时文件留在仓库里。agent-skills这类项目要解决的就是这个：把"怎么做事"从每次对话里抽出来，固化成可复用、可版本管理的技能包，让 agent 在需要的时候自动加载。

这篇文章适合三类人看：一是已经在用 Claude Code 或类似 CLI agent、但觉得"每次都要重新调教"的开发者；二是想给团队建立 AI 编码规范、但不知道从哪下手的技术负责人；三是刚接触 agent 概念、想搞清楚"skill 到底和 prompt 有什么区别"的入门者。我会从技能包的本质讲起，拆到目录结构、CLI 用法、TDD 技能的具体设计，再聊实测中踩过的坑。

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

2.1 普通 prompt 和 skill 的本质区别

很多人把 skill 理解成"长一点的 prompt"，这个理解会直接导致用错。我打个比方：prompt 像是你临时给同事口头交代一件事，说完就散了；skill 像是公司里的一份 SOP 文档，放在共享盘里，谁需要谁去翻，而且文档本身会被 review、被更新、被版本控制。

具体到技术层面，差异体现在三个地方。第一是加载时机：prompt 是你主动塞进上下文的，skill 通常是 agent 根据当前任务判断"我需要这个能力"再去读取的。第二是结构化程度：prompt 可以是一段自由文本，skill 一般有固定的元数据头（名称、描述、触发条件）加正文。第三是可组合性：多个 skill 可以叠加使用，比如"写测试"的 skill 和"提交规范"的 skill 同时生效，而多个 prompt 堆在一起很容易互相打架。

提示：判断一个东西是不是真正的 skill，看它能不能被"按需触发"。如果每次都必须你手动粘贴，那它本质上还是 prompt，只是长一点而已。

2.2 为什么是 CLI 而不是 IDE 插件

关键词里skills CLI排在很前面，这个选择值得说一下。IDE 插件（比如 VS Code 里的各种 AI 助手）的优势是图形化、上手快，但劣势也很明显：它和编辑器强绑定，换编辑器就没了；而且插件的上下文管理往往是黑盒，你不太清楚它到底把哪些文件塞进了模型。

CLI 形态的 skill 管理则更"工程化"。它天然适合放进 CI、适合写进脚本、适合和 git 一起做版本管理。你可以想象一个场景：团队里新来一个人，clone 仓库之后跑一条命令，所有 AI 编码规范就装好了，不需要他手动配置任何东西。这种"基础设施化"的能力，是插件形态很难做到的。

2.3 目标用户和使用边界

agent-skills这类东西不是给"我就想让 AI 帮我写个正则"的人用的。它的目标用户是那些把 AI agent 当成日常生产力工具、并且对代码质量有要求的开发者。如果你只是偶尔用一下，配置 skill 的投入产出比不划算。

它的边界也要说清楚：skill 管的是"流程和规范"，不管"模型能力"。如果模型本身写不出正确的算法，再好的 skill 也救不了。skill 的价值在于——当模型有能力做对的时候，确保它每次都按对的方式做，而不是这次记得写测试、下次就忘了。

3. 一个 skill 包的目录长什么样

3.1 核心文件与元数据约定

虽然agent-skills的具体实现细节会随版本变化，但这类项目的目录结构有很强的共性。一个典型的 skill 包大致是这样组织的：

agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── testing-patterns.md │ ├── commit-conventions/ │ │ └── SKILL.md │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── lint-check.sh ├── cli/ │ └── index.js └── README.md

关键在SKILL.md这个文件。它通常以 YAML frontmatter 开头，声明这个技能的元信息：

--- name: test-driven-development description: 在实现新功能或修复 bug 时，强制先写失败测试再写实现 trigger: 当任务涉及新增函数、修改业务逻辑、修复缺陷时 ---

name是唯一标识，description是给 agent 看的"这个技能是干嘛的"，trigger则是判断何时加载的依据。正文部分才是真正的指令内容，写清楚"第一步做什么、第二步做什么、什么情况下算完成"。

3.2 为什么要把 references 和 scripts 分开

我特别想强调references/和scripts/这两个子目录的设计。很多人写 skill 喜欢把所有东西塞进一个 md 文件，结果文件长到几千行，agent 读起来反而抓不住重点。

正确的做法是分层：SKILL.md只放决策逻辑和主流程，控制在几百行以内；references/放详细的参考资料，比如具体的测试写法示例、边界情况清单，agent 需要深入某个细节时再去读；scripts/放可执行的脚本，比如跑 lint、跑测试的命令封装。

这样设计的好处是上下文经济。agent 的上下文窗口是有限资源，主流程必须精简，细节按需加载。我实测下来，把一个大 skill 拆成"主文件 + 3 个 reference"之后，agent 执行任务的准确率明显提升，因为它不会被无关细节干扰。

3.3 命名与版本管理的一些经验

命名上有个坑我踩过：不要用太泛的词做 skill 名，比如coding、helper这种。agent 判断是否加载时，靠的是 name 和 description 的语义匹配，名字太泛会导致它在不该加载的时候加载。用test-driven-development、api-error-handling这种具体到动作的名字，匹配精度高很多。

版本管理方面，skill 应该和代码一起进 git。每次你发现 agent 又犯了某个老毛病，不要只是在对话里纠正它，而是回头去改对应的 skill 文件，然后提交。这样规范是"长出来"的，而不是一次性设计出来的。我自己的仓库里，test-driven-development这个 skill 改了不下二十次，每次都是被实际问题逼出来的改进。

4. skills CLI 的安装与日常用法

4.1 环境准备中最容易忽略的细节

CLI 类工具的安装本身不复杂，通常是 npm 全局安装或者直接 clone 仓库跑脚本。但有几个细节新手经常忽略。

第一是Node 版本。这类 CLI 工具往往用了较新的语法特性，Node 版本太低会直接报错。装之前先node -v看一眼，建议 18 以上。第二是全局 bin 路径是否在 PATH 里，npm 全局安装后命令找不到，十有八九是这个问题。第三是权限，在类 Unix 系统上全局安装可能需要处理目录权限，但我不建议直接用管理员权限跑 npm，更稳妥的做法是配置一个用户级的全局目录。

# 检查环境 node -v npm -v # 查看 npm 全局路径是否在 PATH 中 npm config get prefix echo $PATH

如果 prefix 不在 PATH 里，把它加进去，然后重新打开终端。这一步看起来基础，但我见过太多人卡在这里以为是工具坏了。

4.2 常用命令与工作流

CLI 的核心命令一般围绕"列出、安装、更新、移除"这几个动作。假设命令入口是skills，典型用法如下：

# 列出当前可用的技能 skills list # 安装某个技能到当前项目 skills add test-driven-development # 查看某个技能的详细内容 skills show test-driven-development # 更新所有已安装技能 skills update

这里有个工作流上的建议：区分全局技能和项目级技能。像"提交信息规范"这种跨项目通用的，装到全局；像"这个项目特有的 API 错误处理约定"这种，装到项目级，跟着仓库走。混在一起会导致项目之间互相污染。

4.3 让 agent 真正用上技能的关键一步

装完技能不等于 agent 就会用。这里有个衔接问题：CLI 把技能文件放到了某个约定目录，但 agent 怎么知道去那里读？

通常有两种机制。一种是约定目录自动发现，agent 启动时会扫描特定路径（比如项目根目录下的.agent/skills/），把技能元数据加载进上下文。另一种是显式声明，在项目的 agent 配置文件里列出要启用的技能。

我建议优先用第一种，因为它对 agent 透明，你不需要每次提醒。但要确认你的 agent 版本支持自动发现，并且目录路径和它期望的一致。实测中，路径差一个层级就会导致技能静默失效——不报错，但也不生效，这种问题最难查。

注意：技能"装了但没生效"是最高频的问题。排查顺序是：目录路径对不对 → 元数据格式对不对 → agent 版本支不支持自动发现 → 有没有被其他配置覆盖。

5. test-driven-development 技能的设计拆解

5.1 为什么 TDD 特别适合做成 skill

在agent-skills的关键词里，test-driven-development是唯一一个具体的方法论，这不是偶然。TDD 天然适合做成 skill，原因有三。

第一，TDD 有明确的、可验证的步骤序列：先写失败测试 → 运行确认失败 → 写最小实现 → 运行确认通过 → 重构。这种"有明确检查点"的流程，正好是 agent 擅长的——它不需要创造力，只需要按步骤执行并在每步验证。

第二，TDD 是反直觉的。模型的默认行为是"直接写实现"，因为训练数据里大部分代码都是实现代码。如果不强制，它几乎不会主动先写测试。skill 的作用就是把这个反直觉的流程"钉死"。

第三，TDD 的失败模式很清晰。如果 agent 跳过了"确认测试失败"这一步，你很容易发现——因为测试可能一开始就是通过的，说明测试根本没测到东西。这种可观测性让 skill 的调试变得简单。

5.2 技能正文里应该写死哪些约束

一个能真正约束住 agent 的 TDD skill，正文不能只是"请遵循 TDD"这种废话。它需要写死具体的、可检查的约束。我总结了几条必须写进去的：

• 禁止在测试文件存在之前创建实现文件。这条是硬约束，防止 agent"先写实现再补测试"。
• 每次只处理一个测试用例。防止它一口气写十个测试再写一大坨实现，那样就退化成"先实现后测试"了。
• 必须实际运行测试命令并展示输出。不能只是"我认为测试会失败"，要真的跑。
• 红灯阶段必须确认失败原因是"功能未实现"，而不是"语法错误"或"导入失败"。这条特别重要，我后面会展开。

把这些写成明确的"必须/禁止"句式，比写成"建议"有效得多。模型对祈使句的遵循度明显高于建议句。

5.3 红灯阶段的验证为什么不能省

这是我在实际使用中体会最深的一点。TDD 的红灯阶段（测试应该失败）看起来是走形式，但它其实是整个流程的质量闸门。

问题在于，测试失败有很多种原因：可能是功能没实现（正确），也可能是测试文件本身有语法错误、导入路径写错、测试框架没配置好（错误）。如果 agent 看到"测试失败了"就认为红灯通过，然后去写实现，最后测试"通过"了——但通过的原因可能是它顺手把测试也改对了，而不是实现真的正确。

所以 skill 里必须要求 agent 在红灯阶段检查失败信息的具体内容。失败信息应该明确指向"断言失败"或"函数未定义"，而不是"模块找不到"或"语法错误"。这个检查动作，是把 TDD 从"形式"变成"实质"的关键。

# 红灯阶段应该看到类似这样的输出 FAIL src/calculator.test.js ✕ add(1, 2) should return 3 ReferenceError: add is not defined # 而不是这样的输出 FAIL src/calculator.test.js ✕ Test suite failed to run SyntaxError: Unexpected token

前者说明测试写对了、实现还没写，是健康的红灯；后者说明测试本身有问题，得先修测试。

6. 把技能接进 Claude Code 的实际配置

6.1 项目级配置与全局配置的取舍

Claude Code 这类 CLI agent 的配置分两层：全局配置（用户目录下）和项目级配置（项目根目录下）。技能放哪一层，取决于它的适用范围。

我的做法是：通用工程规范放全局，项目特有约定放项目级。比如"提交信息用约定式提交"这种，放全局，所有项目受益；"这个项目的 API 层必须走统一的错误包装函数"这种，放项目级，跟着仓库走。

项目级配置的好处是团队共享。你把技能文件提交进仓库，同事 clone 下来就自动生效，不需要口头传达。这也是为什么我前面强调技能要进 git——它本质上是团队规范的可执行版本。

6.2 让 agent 在正确的时机加载技能

配置好之后，还要验证 agent 是否在正确的时机加载了技能。这里有个实用技巧：故意制造一个应该触发技能的场景，观察 agent 的行为。

比如你配置了 TDD 技能，那就给它一个"给现有函数加一个边界处理"的任务。如果它直接改实现，说明技能没生效；如果它先去找测试文件、或者先写一个测试，说明生效了。这种"行为验证"比看配置文件可靠得多，因为配置对不对和生效不生效是两回事。

如果没生效，排查顺序是：技能目录路径 → 元数据格式 → agent 版本 → 是否有其他配置覆盖。我遇到过元数据里description写得太模糊导致匹配不上的情况，改成具体的动作描述后就正常了。

6.3 和模型选择的关系

关键词里提到了用第三方模型接入的场景。这里要说清楚一点：技能的有效性和模型能力是乘法关系，不是加法。技能提供流程约束，模型提供执行能力。如果模型本身遵循指令的能力弱，再好的技能也会被打折扣——它可能读了技能但执行时走样。

所以我的建议是：技能体系先在能力较强的模型上跑通、验证有效，再考虑迁移到其他模型。迁移时重点观察的是"流程遵循度"——它是否还老老实实按步骤走，还是开始跳步。如果跳步严重，可能需要把技能里的约束写得更强硬，或者接受这个模型只适合做更简单的任务。

7. 实测中踩过的坑和排查思路

7.1 技能冲突：两个技能给出矛盾指令

我遇到过一次典型冲突：一个技能要求"每次修改都先跑全量测试"，另一个技能要求"快速迭代，只跑相关测试"。结果 agent 在两个指令之间反复横跳，行为很不稳定。

这类问题的根因是技能之间没有优先级机制。解决办法有两个：一是合并冲突的技能，把矛盾点在一个文件里说清楚"什么情况下用哪种策略"；二是给技能加优先级标记，让 agent 知道谁覆盖谁。我倾向于第一种，因为合并的过程本身就是梳理规范的过程。

7.2 技能太长导致 agent "读了但没记住"

前面提过上下文经济，这里展开说。我一开始写 TDD 技能时，恨不得把所有测试技巧都塞进去，结果文件两千多行。实测发现 agent 执行时经常漏掉后面的约束——不是它不想遵守，是上下文里信息太多，注意力被稀释了。

后来我做了拆分：主文件只保留核心流程和硬约束，控制在 300 行以内；详细的测试模式、边界情况清单挪到references/里，主文件里用一句话指路"需要具体测试写法时参考 references/testing-patterns.md"。改完之后，流程遵循度明显提升。

7.3 技能"看起来生效了"但实际没约束住

这是最隐蔽的坑。表现是：agent 确实先写了测试，看起来在走 TDD，但仔细看，它是先在心里想好了实现，然后补了一个刚好能通过的测试。测试是有了，但失去了 TDD 的意义——测试没有驱动设计，只是事后装饰。

识别这种情况的方法是看测试的粒度。真正的 TDD，测试是一个一个加的，每个测试对应一小步实现。如果 agent 一次性写了五个测试然后一次性写完实现，那基本可以判定是"伪 TDD"。对策是在技能里明确要求"一次一个测试用例，写完一个跑一次"。

7.4 排查链路的一个真实案例

有次我发现 TDD 技能完全没生效，agent 直接改实现。排查过程是这样的：

第一步，确认技能文件存在且路径正确——没问题。第二步，检查元数据格式，发现trigger字段我写成了中文描述，而 agent 的匹配逻辑可能对中文支持不好。第三步，把trigger改成中英混合、并加上具体的关键词（如 "new feature"、"bug fix"、"implement"），重新测试。第四步，行为验证，这次 agent 先去找测试文件了。

这个案例的教训是：元数据里的触发条件要写得"机器友好"，用具体的动作词，而不是抽象的概念词。抽象词人看得懂，但匹配算法不一定能对上。

8. 关于技能体系长期维护的一些想法

技能体系不是一次配好就完事的，它需要持续维护。我的做法是建立一个简单的反馈循环：每次 agent 犯了重复性的错误，就问自己"这是不是应该在技能里约束一下"，如果是，就去改技能文件并提交。

这个循环跑久了，你会发现技能库慢慢变成了团队工程规范的"活文档"——它不只是给 AI 看的，新人读一遍也能快速理解团队怎么做事。这可能是agent-skills这类项目最有价值的副产品：为了让 AI 遵守规范，你被迫把规范写清楚了，而写清楚规范这件事，对团队里的人来说同样有价值。

另外提醒一点，技能不要贪多。我见过有人一口气装了二十个技能，结果 agent 每次任务都要在大量技能里做匹配，反而变慢、变不准。从三五个核心技能开始，用出效果了再加，是比较稳的节奏。技能的价值在于被真正用起来，而不是躺在目录里。