企业官网建设流程全解析

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

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 当"可训练员工"来管理的技能体系。标题里的agent指向的是执行主体——AI 编码代理；skills指向的是它被赋予的能力集合。两者拼在一起，本质上回答了一个很实际的问题：当 AI 已经能写代码、能跑终端命令之后，我们到底该用什么方式把"人的工程经验"喂给它，让它稳定地按团队规范干活？

这个问题的背景，是最近一年 AI coding agent 从"补全工具"进化成了"能自己开终端、自己跑测试、自己改文件"的协作角色。以 Claude Code 为代表的命令行代理，已经可以在项目目录里读文件、执行命令、跑测试、提交改动。但很多人上手之后会发现一个尴尬的现实：模型本身很聪明，可一旦进入真实项目，它就开始"自由发挥"——命名风格不统一、测试写得敷衍、改完不跑验证、遇到报错就绕路。这不是模型不行，而是缺少一套结构化的技能约束。

agent-skills要解决的正是这个断层。它把"一个合格的工程师在这个项目里应该怎么做"拆成一条条可复用的技能单元，让 agent 在特定场景下加载特定技能，从而把行为收敛到可预期的范围。关键词里出现的test-driven-development就是最典型的例子：它不是让 agent"记得写测试"，而是把 TDD 的完整流程——先写失败测试、再写最小实现、再重构——固化成一个技能，agent 每次进入开发任务时按这个流程走。

这篇文章适合三类人看：一是刚开始用 Claude Code 这类命令行代理、还在摸索怎么让它"听话"的开发者；二是团队里想把 AI 编码规范沉淀下来的技术负责人；三是单纯好奇"skills 这种组织方式到底比一堆提示词强在哪"的工程爱好者。我会从技能的本质、目录结构、加载机制、TDD 技能拆解、CLI 工具链、以及实际踩坑几个角度，把agent-skills这套东西讲透。

2. 技能不是提示词：agent-skills 的核心抽象

2.1 提示词和技能的本质区别

很多人第一次接触 skills 概念时，会下意识把它等同于"更长的系统提示词"。这个理解偏差会导致后面所有设计都走偏。我用一个类比说清楚：提示词像是你临时口头交代同事一件事，技能像是公司写进 SOP 手册的标准作业流程。

临时交代的问题是，它依赖上下文、依赖你当时说清楚没有、依赖对方记不记得。你这次说"记得写测试"，下次忘了说，agent 就不写了。而技能是持久化的、可被检索的、有明确触发条件的。它不依赖你每次重复，而是 agent 在识别到"当前任务是开发新功能"时，主动去加载对应的技能文档。

从工程角度看，这个区别带来三个实际收益：

• 可复用：一个 TDD 技能写一次，所有走开发流程的任务都能用，不用在每个提示词里重复。
• 可版本化：技能是文件，能进 Git，能 review，能回滚。提示词散落在聊天记录里，改了什么根本追溯不了。
• 可组合：一个任务可以同时加载"代码风格技能 + 测试技能 + 提交规范技能"，像搭积木一样组合出完整行为。

2.2 技能单元应该包含哪些要素

一个设计良好的技能，不是一段散文式的说明，而是有固定结构的。根据我在实际项目里沉淀的经验，一个技能至少应该包含这几块：

这个结构看起来简单，但真正写起来，最难的是"触发条件"和"验证标准"。触发条件写太宽，技能到处被加载，干扰正常任务；写太窄，该用的时候用不上。验证标准则是区分"玩具技能"和"生产技能"的分水岭——没有验证标准的技能，agent 做完自己都不知道对不对。

2.3 为什么用 Markdown 而不是代码

agent-skills这类仓库普遍用 Markdown 来写技能，而不是 JSON 或 YAML 配置。这个选择背后有很实际的考虑。Markdown 对模型来说是最自然的输入格式，它能理解标题层级、列表、代码块、引用块这些结构，而且能容忍一定程度的自然语言描述。如果用严格的 JSON schema，写技能的人会被格式绑死，反而写不出"为什么这么做"这种关键的上下文。

但 Markdown 也有代价：它没有强制的字段校验，容易写得松散。所以实践中通常会在仓库里放一个技能模板文件，规定好标题层级和必备小节，让每个技能保持结构一致。这样既保留了自然语言的表达力，又有一定的规范性。

提示：如果你打算在自己的项目里引入 skills，第一件事不是写技能，而是先定一个技能模板。模板定好了，后面所有人写的技能才能被 agent 稳定解析。

3. 目录结构与技能加载机制

3.1 一个可落地的目录布局

agent-skills这类仓库的目录结构，直接决定了 agent 能不能高效找到并加载技能。我见过不少项目把技能全堆在一个文件夹里，结果几十个文件平铺，agent 检索时经常加载错。一个更合理的布局是按"领域 + 场景"分层：

agent-skills/ ├── README.md ├── templates/ │ └── skill-template.md ├── skills/ │ ├── development/ │ │ ├── test-driven-development.md │ │ ├── code-review-checklist.md │ │ └── refactoring-guide.md │ ├── workflow/ │ │ ├── git-commit-convention.md │ │ └── pr-description.md │ └── debugging/ │ ├── root-cause-analysis.md │ └── log-investigation.md └── cli/ └── skills.js

这个布局的关键在于：一级目录按技能的大类分，二级目录放具体技能文件。development 放开发相关的，workflow 放流程相关的，debugging 放排查相关的。agent 在识别任务类型后，能快速定位到对应目录，而不是在几十个平铺文件里瞎找。

3.2 技能是怎么被"加载"的

这里要澄清一个常见误解：skills 不是自动生效的魔法。它需要一个加载机制，通常有两种模式。

第一种是显式加载。用户在对话里明确说"用 TDD 技能来做这个功能"，agent 就去读对应的技能文件，然后按里面的步骤执行。这种方式可控性最强，适合关键任务。

第二种是条件触发。agent 在分析任务时，根据任务描述匹配技能里的触发条件，自动加载。比如任务里出现"修复这个 bug"，agent 就去找 debugging 目录下的技能。这种方式更顺滑，但对触发条件的写法要求很高。

实际项目里，两种模式通常混用。核心流程用显式加载保证稳定，边缘场景用条件触发提升效率。skills CLI这类工具的价值，就是提供一个统一的入口，让用户能列出所有可用技能、查看某个技能的详情、手动触发加载。

3.3 加载顺序和优先级

当多个技能同时匹配时，谁先谁后是个真问题。比如一个任务既涉及开发又涉及提交，TDD 技能和 commit 规范技能都要用。这时候需要一个优先级规则。

我的做法是在技能文件头部加一个priority字段（用注释或 frontmatter 都行），数值越小越先加载。流程类技能（如提交规范）优先级高，因为它们约束的是"什么时候做什么"；具体实现类技能优先级低，因为它们约束的是"具体怎么做"。这样 agent 先确定流程框架，再填充实现细节，逻辑上更顺。

注意：不要给所有技能都设成最高优先级，那样等于没有优先级。真正需要抢占的只有少数几个流程性技能。

4. TDD 技能拆解：把工程纪律写成 agent 能执行的步骤

4.1 为什么 TDD 是 skills 的最佳样本

关键词里test-driven-development排在很靠前的位置，这不是偶然。TDD 是软件工程里少有的"流程极其明确、验证标准极其清晰"的实践，天然适合写成技能。它的红-绿-重构三步，每一步都有明确的输入、动作、输出，几乎没有模糊地带。

更重要的是，TDD 恰好能治 agent 的一个通病：改完不验证。很多 agent 写完代码就宣布完成，根本不跑测试。而 TDD 技能强制要求"先写一个会失败的测试"，这就把验证环节前置了——测试跑不通，agent 就没法进入下一步。

4.2 一个 TDD 技能的完整结构

我把实际用过的 TDD 技能结构拆给你看。它大致长这样：

# Test-Driven Development ## 触发条件 - 任务是新增功能或修改现有功能的行为 - 项目已有测试框架（jest / pytest / go test 等） ## 目标 用红-绿-重构循环实现功能，确保每一步都有测试覆盖。 ## 步骤 1. 阅读需求，写出一个描述期望行为的最小测试 2. 运行测试，确认它失败（红） 3. 写最少的代码让测试通过（绿） 4. 运行全部测试，确认没有破坏其他功能 5. 在测试保护下重构代码 6. 重复 1-5 直到功能完成 ## 验证标准 - 每个新增行为都有对应测试 - 最终测试全绿 - 重构后测试仍然全绿 ## 禁忌 - 不允许先写实现再补测试 - 不允许跳过"确认测试失败"这一步 - 不允许为了让测试通过而修改测试断言

这个结构里，最容易被忽视但最关键的是第 2 步"确认测试失败"。很多人（包括 agent）会觉得这步多余——测试都写了，直接写实现不就行了？但确认失败是 TDD 的灵魂：它证明你的测试确实在检验新行为，而不是一个永远为真的空断言。如果测试一开始就通过，说明要么功能已经存在，要么测试写错了。

4.3 agent 执行 TDD 时的真实表现

我在实际项目里让 agent 跑 TDD 技能，观察到的行为很有意思。当技能写得好时，agent 会老老实实先写测试、跑一遍、看到红色、再写实现。但当技能里"确认失败"这一步写得含糊时，agent 十有八九会跳过它，直接写实现，然后跑测试看到绿色就宣布完成。

这说明一个道理：agent 会严格执行你写清楚的步骤，也会严格执行你省略的步骤。技能文档的完整度，直接决定 agent 行为的完整度。这也是为什么我一直强调技能要有"验证标准"和"禁忌"两块——它们是在给 agent 划边界。

另一个观察是，agent 在重构阶段容易过度发挥。它可能把"重构"理解成"顺便优化一下架构"，然后改动范围失控。所以 TDD 技能里最好明确写一句"重构仅限消除重复和改善命名，不改变外部行为"，把范围锁死。

5. skills CLI：让技能可发现、可调用、可管理

5.1 CLI 存在的意义

有人会问：技能就是一堆 Markdown 文件，直接让 agent 读不就行了，为什么还要一个 CLI？这个问题问得好。CLI 的价值不在于"读文件"，而在于提供统一的发现和调用接口。

想象一下，你的仓库里有三十个技能，散落在不同目录。用户想知道"有没有处理数据库迁移的技能"，靠翻目录很累。CLI 提供skills list命令，一次性列出所有技能和它们的触发条件，用户扫一眼就知道有什么可用。再比如，用户想手动触发某个技能，skills run test-driven-development就能把技能内容注入当前会话，不用手动复制粘贴。

5.2 一个最小可用的 CLI 设计

skills CLI不需要做得很复杂，核心就三个命令：

实现上，用 Node.js 写一个脚本，遍历skills/目录，解析每个 Markdown 文件的标题和触发条件，输出成列表。run命令则是把文件内容读出来，通过标准输出或 API 传给 agent。

// cli/skills.js 的核心逻辑示意 const fs = require('fs'); const path = require('path'); function listSkills(dir) { const skills = []; const categories = fs.readdirSync(dir); for (const category of categories) { const categoryPath = path.join(dir, category); if (!fs.statSync(categoryPath).isDirectory()) continue; for (const file of fs.readdirSync(categoryPath)) { if (!file.endsWith('.md')) continue; const content = fs.readFileSync(path.join(categoryPath, file), 'utf8'); const title = content.match(/^#\s+(.+)$/m)?.[1] || file; skills.push({ category, file, title }); } } return skills; }

这段代码很朴素，但它解决了一个真实痛点：让技能从"藏在文件系统里"变成"可被程序枚举的资源"。有了这个基础，后面可以扩展出按关键词搜索、按标签过滤、自动匹配任务等功能。

5.3 CLI 和 agent 的协作方式

CLI 和 agent 之间怎么协作，有两种思路。一种是 CLI 作为独立工具，用户手动调用，把输出贴给 agent。另一种是 CLI 作为 agent 可调用的工具，agent 在执行任务时自己调用skills list来发现技能。

第二种更优雅，但需要 agent 支持工具调用。以 Claude Code 这类支持终端命令的 agent 为例，它可以直接执行node cli/skills.js list，拿到技能列表，然后决定加载哪个。这就形成了一个闭环：agent 自己发现技能、自己加载、自己执行。

提示：如果你用的 agent 支持执行终端命令，把 skills CLI 注册成一个可调用工具，能大幅提升技能的使用率。手动贴技能的方式，用几次就懒得用了。

6. 把 skills 接入 Claude Code 这类命令行代理

6.1 接入前要搞清楚的事

在动手接入之前，有几个概念要先理清。Claude Code 这类命令行代理的工作方式，是在你的项目目录里运行，能读写文件、执行命令。它读取项目里的配置文件（比如CLAUDE.md）作为上下文。所以接入 skills 最自然的方式，就是在项目根目录放一个入口文件，告诉 agent 技能在哪里、怎么用。

这个入口文件通常叫CLAUDE.md或AGENTS.md，内容大致是：

# 项目 Agent 配置 ## 技能库 本项目使用 agent-skills 管理技能，技能位于 `skills/` 目录。 ## 使用方式 - 开发新功能时，加载 `skills/development/test-driven-development.md` - 提交代码前，加载 `skills/workflow/git-commit-convention.md` - 排查问题时，加载 `skills/debugging/root-cause-analysis.md` ## 技能发现 运行 `node cli/skills.js list` 查看所有可用技能。

这个文件的作用是给 agent 一个"地图"。它不需要包含所有技能内容，只需要指明方向。agent 在需要时自己去读具体技能文件。

6.2 环境准备中的几个细节

接入过程中有几个容易忽略的细节。第一是路径问题。agent 执行命令时的工作目录，可能和你手动执行时不一样。CLI 脚本里最好用绝对路径或基于__dirname解析，避免"在我机器上能跑"的尴尬。

第二是权限问题。agent 执行终端命令需要相应权限。在配置里要确保 agent 有读取技能目录、执行 node 脚本的权限。如果权限不足，agent 会静默失败，你甚至不知道技能没加载。

第三是模型选择。不同模型对长上下文技能文档的理解能力差异很大。技能文档动辄几百上千字，如果模型上下文窗口小，加载几个技能就爆了。实践中建议把单个技能控制在 500 字以内，把详细示例放到单独的参考文件里，按需加载。

6.3 验证接入是否成功

接入完成后，怎么确认技能真的生效了？我的做法是设计一个"冒烟测试"：给 agent 一个明确需要某技能的任务，观察它的行为是否符合技能描述。

比如测试 TDD 技能，就给 agent 一个"实现一个字符串反转函数"的任务。如果技能生效，agent 应该先写测试、跑测试、看到失败、再写实现。如果它直接写实现，说明技能没加载成功。这个验证步骤很重要，因为技能加载失败往往是静默的，不主动验证根本发现不了。

7. 实操中踩过的坑和应对

7.1 技能写太细，agent 反而僵化

我一开始写技能，恨不得把每个细节都写进去，结果发现 agent 变得很死板。比如我在代码风格技能里规定了"变量名必须用驼峰"，agent 遇到一个必须用下划线的场景（比如对接某个 API 的字段名），也硬要用驼峰，导致代码报错。

后来我调整了思路：技能规定原则和边界，不规定所有细节。原则是"命名要一致、要表意清晰"，边界是"遵循项目现有风格"。具体用驼峰还是下划线，让 agent 根据上下文判断。这样既保证了方向，又保留了灵活性。

7.2 技能之间互相冲突

当多个技能同时加载时，冲突几乎不可避免。我遇到过最典型的一次：TDD 技能要求"先写测试"，而另一个"快速原型"技能要求"先跑通再补测试"。两个技能同时加载，agent 直接卡住，不知道该听谁的。

解决办法是给技能加互斥标记。在技能头部注明"本技能与 XX 技能互斥，不可同时加载"。CLI 在加载时检查冲突，发现互斥就提示用户选择。这个机制看起来简单，但能避免大量诡异行为。

7.3 技能文档的维护成本被低估

技能写出来只是开始，维护才是大头。项目在演进，代码规范在变，技能文档如果不同步更新，agent 就会按过时的规范干活。我见过一个团队，技能里还写着用某个已经废弃的测试框架，结果 agent 生成的测试全跑不起来。

应对办法是把技能文档纳入代码 review 流程。每次改代码规范，同步改技能文档。更进一步，可以在 CI 里加一个检查：如果技能文档里引用的文件路径不存在，就报错。这样至少能保证技能里的引用不会失效。

7.4 agent 对技能的理解偏差

即使技能写得再清楚，agent 也可能理解偏。我遇到过一次，技能里写"重构时不要改变外部行为"，agent 理解成"不要改变函数签名"，结果它把函数内部逻辑大改了一通，虽然签名没变，但行为变了。

这类偏差很难完全避免，但可以通过增加具体示例来降低概率。在技能里放一两个"正确做法"和"错误做法"的对比示例，agent 的理解准确率会明显提升。示例比抽象描述有效得多，这是我在实践中反复验证过的。

8. 技能体系的扩展方向

8.1 从单机技能到团队技能库

个人用 skills，一个目录就够了。但团队用，就需要考虑共享和版本管理。一个可行的做法是把技能库做成独立的 Git 仓库，各项目通过 submodule 或包管理器引入。这样技能更新一次，所有项目都能同步。

更进一步，可以给技能加版本号，项目锁定特定版本。这样技能升级不会突然改变 agent 行为，避免"昨天还好好的，今天 agent 就抽风了"的情况。

8.2 技能的效果度量

技能到底有没有用，不能靠感觉。我建议记录几个指标：agent 任务的一次通过率、需要人工干预的次数、生成代码的测试覆盖率。对比引入技能前后的数据，就能看出技能的实际价值。

这个度量不需要很复杂，手动记录几十个任务就能看出趋势。如果某个技能引入后，相关任务的通过率没提升，那这个技能可能写得有问题，或者根本不该存在。

8.3 技能和提示词的边界

最后说一个容易混淆的点：技能和提示词不是替代关系，而是互补。技能管的是"稳定的、可复用的流程和规范"，提示词管的是"这次任务的特殊要求"。比如 TDD 流程用技能固化，但"这次要用递归实现"这种一次性要求，还是写在提示词里更合适。

搞清楚这个边界，就不会陷入"什么都想写成技能"的误区。技能库应该保持精简，只放那些真正跨任务复用的东西。一个塞满几十个技能的库，维护成本会高到没人愿意碰。

我在实际项目里用下来，最深的体会是：skills 的价值不在于让 agent 变聪明，而在于让 agent 变稳定。模型本身的能力已经足够强，真正拖后腿的是行为的不确定性。把工程经验沉淀成技能，本质上是在给这种不确定性套上缰绳。缰绳套得好，agent 就是一个可靠的协作者；套得不好，它就是一个随时给你惊喜（吓）的黑盒。这套东西值得每个认真用 AI 编码的人花时间琢磨。