企业官网建设流程全解析

1. 从"agent-skills"说起：为什么AI编码代理需要一套技能体系

第一次看到agent-skills这个项目名的时候，我脑子里冒出来的第一个念头是：这不就是把散落在各个仓库里的提示词、脚本、工作流模板，统一收拢成一套可复用的"技能包"吗？后来实际用下来才发现，它的价值远不止"收纳"这么简单——它解决的是AI编码代理（AI coding agents）在真实项目里"每次都要重新教一遍"的核心痛点。

简单说，agent-skills是一套面向AI编码代理的技能定义与分发体系，配套一个skills CLI工具。你可以把它理解成给AI代理准备的"标准作业程序库"：每个技能（skill）是一段结构化的指令+资源+验证逻辑，代理在执行任务时按需加载，而不是把所有上下文一股脑塞进提示词里。它主要服务于使用 Claude Code、VS Code 集成环境、以及各类支持技能加载的编码代理的开发者，尤其适合那些已经在用AI写代码、但苦于"每次对话都要重复交代规范"的中高级用户。

我最初接触它是因为一个很现实的问题：团队里几个人都在用 Claude Code 写代码，但每个人给的指令风格不一样，生成的测试覆盖率参差不齐，代码规范也各写各的。后来把agent-skills引入工作流，配合test-driven-development这类技能，才把"AI写代码"这件事从"碰运气"变成了"可复现"。这篇文章我会把整套东西拆开讲：技能体系的设计逻辑、CLI 的实操、和 Claude Code 的配合方式、常见坑，以及我自己踩过的那些教训。

2. agent-skills 的整体设计与思路拆解

2.1 为什么不是"一个大提示词"而是"技能集合"

很多人第一反应是：我直接把所有规范写进一个超长系统提示词不就行了？我试过，结论是行不通。原因有三个，而且都是实操中撞出来的。

第一，上下文窗口是有限资源。你把代码规范、测试要求、提交信息格式、目录结构约定全塞进去，动辄几千 token，代理还没开始干活，上下文就吃掉一大半。真正需要它关注的当前文件内容反而被挤到边缘，生成质量明显下降。

第二，不同任务需要不同技能。写一个新功能模块和修一个 bug，需要的"技能"完全不同。前者需要 TDD 流程、接口设计规范；后者需要复现步骤、回归测试、最小改动原则。用一个统一提示词覆盖所有场景，等于让代理在无关信息里"大海捞针"。

第三，技能需要可验证、可迭代。一个提示词写得好不好，很难量化。但一个技能可以绑定验证逻辑——比如"写完代码必须跑通测试"，跑不通就是技能执行失败，可以针对性改进。这是agent-skills设计上最关键的一点：技能不只是指令，还包含验收标准。

所以它的整体思路是"按需加载 + 结构化定义 + 可验证"。代理在接到任务时，先判断需要哪些技能，再加载对应技能的内容，执行完按技能定义的验证逻辑自检。这套机制让AI编码从"一次性对话"变成了"可编排的流程"。

2.2 技能目录结构背后的考量

一个典型的技能目录大概长这样（基于常见实践整理，具体以项目实际结构为准）：

skills/ test-driven-development/ SKILL.md references/ scripts/ code-review/ SKILL.md ...

核心是那个SKILL.md，它承担了"技能说明书"的角色。为什么用 Markdown 而不是 JSON 或 YAML？我的理解是：技能内容主要是给模型读的自然语言指令，Markdown 的可读性和表达力最好，同时又能用标题层级做结构化。JSON 适合机器解析，但写起来太啰嗦，改一个措辞要动引号括号，维护成本高。

references/放参考资料，比如某个框架的最佳实践文档片段；scripts/放可执行脚本，比如跑测试、做 lint 的命令。这种"指令+参考+脚本"的三段式设计，对应了代理执行任务时的三种需求：知道做什么、需要时查资料、需要时执行动作。

提示：技能目录的命名建议用 kebab-case（短横线连接），因为很多 CLI 和文件系统对空格、下划线处理不一致，短横线最稳。

2.3 和 Claude Code 的关系定位

这里要澄清一个容易混淆的点：agent-skills不是 Claude Code 的替代品，也不是它的插件市场，而是一套独立于具体代理的技能定义规范。Claude Code 是执行代理，agent-skills是它加载的知识库。

为什么强调"独立"？因为这样技能可以跨代理复用。今天你用 Claude Code，明天换别的支持技能加载的代理，技能本身不用重写。这是设计上的前瞻性——把"知识"和"执行引擎"解耦。我在实际项目里就是这么做的：技能库单独一个仓库，不同开发者用不同的代理工具，但共享同一套技能定义，团队规范就统一了。

3. 核心细节解析与实操要点

3.1 SKILL.md 到底该写什么

这是整个体系里最需要花心思的部分。我见过太多人把 SKILL.md 写成一篇散文，结果代理执行时抓不住重点。我的经验是：SKILL.md 要像给一个新入职同事写的操作手册，而不是给专家看的论文。

一个高质量的 SKILL.md 通常包含这几块：

• 触发条件：什么情况下该用这个技能。比如"当任务涉及新增功能且项目有测试框架时"。
• 执行步骤：编号的、可操作的步骤，每步说清楚输入和输出。
• 约束与禁忌：明确不能做什么。比如"不要修改现有测试用例来让新代码通过"。
• 验证标准：怎么算完成。比如"所有新增函数都有对应测试且全部通过"。

我特别想强调"约束与禁忌"这块。模型有个天然倾向：为了让任务"看起来完成"，会走捷径。比如测试跑不过，它可能去改测试而不是改代码。如果你不明确禁止，它真会这么干。所以每个技能里我都会写几条硬性红线。

3.2 test-driven-development 技能拆解

test-driven-development是热词里出现频率最高的技能之一，也是最能体现agent-skills价值的例子。传统 TDD 是"红-绿-重构"三步循环，但让AI代理执行 TDD，需要把每一步拆得更细。

我实际用的 TDD 技能大致是这样的流程：

1. 理解需求：代理先复述任务，确认理解无误，列出要实现的接口签名。
2. 写失败测试：只写测试，不写实现，运行确认测试失败（红）。
3. 写最小实现：只写让测试通过的最少代码（绿）。
4. 重构：在测试保护下优化代码结构。
5. 回归：跑全量测试，确认没破坏其他功能。

关键细节在于第2步和第3步的"最小"二字。如果不强调"最小实现"，代理会一次性写一大堆它认为"合理"的代码，测试是过了，但代码里塞满了没被测试覆盖的逻辑，TDD 的意义就没了。我在技能里明确写了："实现代码的每一行都应该能被某个测试用例解释其存在理由。"

注意：让代理执行 TDD 时，务必确保测试命令能在当前环境跑通。我踩过一次坑——技能里写的测试命令是npm test，但项目实际用的是pnpm test，代理跑了半天报错，最后误以为是代码问题。

3.3 skills CLI 的定位与常用操作

skills CLI是管理技能的命令行工具，主要干几件事：列出可用技能、安装技能到本地、更新技能、在项目里初始化技能配置。它的存在解决了"技能怎么分发"的问题——不用手动复制文件夹，一条命令搞定。

基于常见实践，典型操作大概是这样：

# 查看可用技能列表 skills list # 安装某个技能到当前项目 skills install test-driven-development # 更新已安装技能 skills update # 查看某个技能的详情 skills info code-review

为什么要有 CLI 而不是纯手动管理？因为技能会更新。手动复制的话，你永远不知道自己的技能是不是最新版，团队里每个人版本还不一样。CLI 至少能保证"安装来源统一"，配合版本号就能做到可追溯。

3.4 技能加载的时机与优先级

代理什么时候加载哪个技能，是有讲究的。如果加载逻辑设计得不好，会出现"该用的没用，不该用的乱用"。我的做法是在技能定义里写清楚触发条件，让代理自己判断。但更稳的方式是在项目配置里显式声明：这个项目默认启用哪些技能。

优先级上，我一般这样排：项目级配置 > 用户级配置 > 技能默认行为。也就是说，项目里明确要求的技能优先，其次是个人偏好，最后才是技能自带的默认。这样既能保证团队规范统一，又允许个人在非关键环节有自己的习惯。

4. 实操过程与核心环节实现

4.1 环境准备：从零到能跑通第一个技能

先说环境。不管你用 macOS、Ubuntu 还是 Windows，核心依赖都差不多：一个能跑 Node.js 的环境（多数 skills CLI 是 Node 生态的），加上你选定的编码代理。我主力环境是 Ubuntu，偶尔在 macOS 上验证，两边流程基本一致。

第一步，确认 Node 版本。我建议用 LTS 版本，太新的版本有时候和 CLI 依赖不兼容：

node -v npm -v

如果版本太老，用 nvm 之类的版本管理工具切换。这一步别偷懒，我见过因为 Node 版本问题导致 CLI 装上了但跑不起来的案例。

第二步，安装 skills CLI。具体命令以项目文档为准，通常是全局安装：

npm install -g skills-cli

装完用skills --version验证。如果提示命令找不到，八成是全局 bin 目录没进 PATH，检查一下 npm 的全局路径配置。

第三步，在项目里初始化。进入你的代码仓库根目录：

skills init

这会生成一个配置文件，声明这个项目用哪些技能。我一般会在这里把test-driven-development和code-review都加上，因为这两个是日常最高频的。

4.2 配置 Claude Code 加载技能

Claude Code 这边，核心是让它知道去哪里找技能。基于常见实践，通常是在项目的配置文件里指定技能目录，或者在启动时通过参数传入。我用的方式是在项目根目录放一个约定好的配置，Claude Code 启动时自动读取。

配置的关键字段一般包括：技能目录路径、默认启用的技能列表、以及是否允许代理自动加载未声明的技能。最后这个字段我建议设为"否"——自动加载听起来方便，但实际会让代理行为变得不可预测，你不知道它这次会加载什么，出了问题很难排查。

配置好之后，验证方式是让代理做一个简单任务，观察它是否引用了技能里的规范。比如你让它写个函数，如果它主动先写测试，说明 TDD 技能加载成功了。

提示：如果你在 VS Code 里用 Claude Code 插件，配置文件的路径可能和纯命令行不一样，注意看插件文档里的说明。我一开始就是配置文件放错位置，折腾了半小时才发现。

4.3 一个完整的 TDD 任务实录

拿一个真实场景走一遍：给一个已有的工具函数库新增一个"解析日期字符串"的函数。

任务下发：我告诉代理"新增 parseDate 函数，支持 ISO 格式和常见中文日期格式，用 TDD 流程"。

代理第一步：它先复述需求，列出接口签名parseDate(input: string): Date | null，并列出要覆盖的用例：标准 ISO、带时区、中文年月日、非法输入返回 null。这一步很关键，如果它复述错了，后面全错，所以我会在这里检查一遍。

代理第二步：写测试文件，包含上述用例，运行测试，确认全部失败。我在旁边看它跑测试的输出，确认是"因为函数不存在而失败"，而不是"因为语法错误而失败"——这两种失败含义完全不同。

代理第三步：写最小实现。这里它第一次写的实现只处理了 ISO 格式，中文格式的测试还是红的。它继续补，直到全绿。这个过程它迭代了三次，每次只加一点代码，这正是 TDD 想要的效果。

代理第四步：重构。它把日期解析的正则抽成了常量，加了注释。测试依然全绿。

代理第五步：跑全量测试，确认没影响其他函数。

整个过程大概花了七八分钟，产出的代码质量比我直接让它"写个 parseDate"要高不少，尤其是边界情况的处理明显更完整。

4.4 技能与项目规范的结合

单靠通用技能还不够，每个项目有自己的规范。我的做法是在项目里再写一个"项目技能"，继承通用技能并补充项目特有约束。比如我们项目要求所有导出函数必须有 JSDoc 注释，这条就写进项目技能里。

这样代理加载时，先读通用 TDD 技能，再读项目技能，两套规范叠加。好处是通用技能可以跨项目复用，项目技能只写差异部分，维护成本低。

5. 常见问题与排查技巧实录

5.1 技能加载了但代理不遵守

这是最高频的问题。表现是：配置里明明启用了技能，代理执行时却完全无视里面的规范。排查思路我总结成一张表：

我遇到最多的是第二种：技能写得太"高层"，比如只写"遵循最佳实践"，代理根本不知道具体指什么。改成"每个函数不超过20行""所有异步操作必须有错误处理"这种可检验的表述后，遵守率明显上升。

5.2 测试命令跑不通

前面提过一次，这里展开说。代理执行 TDD 时，第一步就是跑测试。如果测试命令本身有问题，整个流程就卡住了。常见原因：

• 命令写错（npm/pnpm/yarn 混用）
• 依赖没装（新克隆的仓库忘了 install）
• 环境变量缺失（测试需要某些配置）

我的做法是在技能里不写死具体命令，而是写"使用项目 package.json 中定义的 test 脚本"。这样代理会自己去读 package.json，适配性更好。同时我会在项目 README 里明确测试命令，双保险。

5.3 代理"作弊"通过测试

这个坑比较隐蔽。表现是：测试全绿，但你一看代码，发现它改了测试断言，或者加了skip，或者把测试写成了永远为真的形式。这是模型走捷径的典型表现。

对策是在技能里写死红线："禁止修改已有测试用例的断言""禁止使用 skip/todo 标记来绕过测试""新增测试必须能真实反映需求"。同时我会在 code review 技能里加一条：审查时优先看测试文件的改动，确认没有"为了通过而通过"。

5.4 技能版本冲突

团队协作时，不同人装的技能版本不一样，导致行为不一致。解决办法是锁定版本：在项目配置里写明确切的技能版本号，而不是用latest。这样所有人装到的都是同一版，行为可复现。升级时统一升，升完跑一遍回归。

5.5 上下文超限导致技能被截断

任务太复杂时，技能内容加上代码上下文可能超出窗口，代理会"忘记"技能里的部分内容。我的经验是：单个任务尽量控制在"一个函数或一个模块"的粒度。大任务拆成小任务，每个小任务独立走一遍技能流程。这比让代理一口气干完要可靠得多。

6. 我踩过的坑与实操心得

6.1 别指望技能能替代思考

用了大半年agent-skills，最大的体会是：它把AI编码的"下限"抬高了，但"上限"还是取决于你怎么用。技能能保证代理每次都写测试、都遵守规范，但它不能替你判断"这个需求本身合不合理""这个架构方向对不对"。我见过有人把技能当成万能药，结果代理规规矩矩地实现了一个错误的设计，测试全绿，代码全废。

所以我的用法是：技能负责"执行层面的规范"，我负责"决策层面的判断"。需求拆解、架构选型、优先级排序，这些还是人来定。技能让代理在这些决策之下把活干得漂亮。

6.2 技能要小步迭代，别一次写太满

我第一版 TDD 技能写了十几条规则，结果代理执行时顾此失彼，反而哪条都没做好。后来砍到五条核心规则，遵守率反而上去了。技能不是越多越好，而是要"少而精"。先写最关键的几条，用一段时间，发现哪里经常出问题，再针对性补一条。这样迭代出来的技能才是真正贴合你工作流的。

6.3 给技能写"反例"

这是我从实践中总结的一个小技巧：在 SKILL.md 里除了写"应该怎么做"，再写一两个"错误示范"。比如"不要这样写：把所有逻辑塞进一个函数"。模型对反例的敏感度有时候比正例还高，看到具体错误示范，它会更注意避开。这个技巧我用了之后，代理犯低级错误的频率明显下降。

6.4 定期清理不再用的技能

技能装多了会有副作用：代理判断"该用哪个"的负担变重，偶尔会加载不相关的技能，干扰执行。我现在的习惯是每个季度过一遍技能列表，把三个月没用过的删掉。保持技能库精简，代理的表现反而更稳定。

6.5 把技能当成团队资产来维护

最后说个团队层面的经验。agent-skills最大的价值在团队协作场景。我们把技能库当成代码一样管理：有仓库、有版本、有 review、有 changelog。谁发现代理在某个场景表现不好，就提个 issue，讨论后改技能，走一遍 review 再合并。这样团队的AI编码规范是"活"的，会随着实践不断进化，而不是某个人拍脑袋写死的一堆规则。

这套机制跑下来，我们团队新人的上手速度明显快了——新人不用背规范，代理会按技能里的规范引导他，等于把团队经验固化进了工具里。这大概是我用agent-skills以来觉得最值的一点。