企业官网建设流程全解析

1. 从“agent-skills”说起：为什么我们需要给AI编码代理装上技能包

第一次看到“agent-skills”这个词，很多人会以为它又是一个新的AI模型或者某个大厂的新产品。其实不是。它更像是一套“技能说明书”或者“能力插件集合”，专门用来给AI编码代理（AI coding agents）补充它们原本不具备或者不够熟练的操作能力。你可以把它理解成给一个刚入职的实习生发了一本《公司内部工具使用手册》——实习生本身聪明，但不知道你们公司用什么命令跑测试、用什么格式提交代码、遇到冲突怎么处理，这本手册就是解决这个问题的。

我最早接触这个概念是在折腾Claude Code的时候。Claude Code本身已经很强了，能读代码、能改文件、能执行终端命令，但它在某些特定场景下会“犯傻”。比如你让它跑一个测试，它可能直接敲npm test，但你的项目用的是pnpm，而且测试前需要先启动一个本地数据库容器。这时候它就会卡住，或者给你一个错误的执行结果。agent-skills要解决的就是这类问题：把“在这个项目里应该怎么做某件事”的知识，以结构化的方式喂给AI代理，让它从“通用聪明”变成“项目内行”。

这套东西适合谁？三类人最应该关注。第一类是已经在用Claude Code、Cursor、Windsurf这类AI编码工具的开发者，你肯定遇到过“它明明能改代码，但就是跑不对命令”的情况。第二类是团队里的技术负责人，你们想让AI代理遵守团队的代码规范、测试流程和部署步骤，而不是每个人各自调教。第三类是对AI代理底层机制好奇的玩家，你想知道这些工具到底是怎么被“扩展”的，能不能自己写一套技能包。

热搜词里出现了“test-driven-development”，这其实点出了agent-skills最核心的应用场景之一。TDD（测试驱动开发）的流程非常固定：先写一个失败的测试，然后写最少的代码让它通过，最后重构。这个流程对人类开发者来说是肌肉记忆，但对AI代理来说，它需要被明确告知“现在处于哪个阶段”“下一步该做什么”“什么情况下算完成”。agent-skills就是把这些阶段性的指令和检查点固化下来，让AI代理能够真正按照TDD的节奏工作，而不是一口气把代码和测试全写完然后告诉你“都通过了”。

还有一个热搜词是“skills CLI”，这说明已经有人在做命令行工具来管理这些技能包了。你可以用类似skills install、skills list这样的命令来给当前项目安装、查看、更新技能。这个思路很合理，因为AI代理本身就是在终端里工作的，用CLI来管理它的能力扩展是最自然的交互方式。后面我会详细讲这套CLI大概长什么样、怎么用。

2. agent-skills到底长什么样：核心结构与设计逻辑

2.1 一个技能包的基本组成

我拆过几个开源的agent-skills实现，也自己写过几个，基本结构大同小异。一个技能包通常包含以下几个部分：

• 元数据文件：一般叫skill.json或者SKILL.md，里面写清楚这个技能叫什么、版本号、作者、依赖什么环境、适用于哪些文件类型。这个文件的作用是让AI代理在加载技能之前就知道“这个技能是干什么的”，避免加载一堆用不上的东西。
• 指令模板：这是核心。它是一段结构化的文本，告诉AI代理在特定场景下应该执行什么命令、按照什么顺序执行、遇到什么情况应该停下来询问。比如一个“运行测试”的技能，指令模板会写：“首先检查项目根目录是否存在pnpm-lock.yaml，如果存在则使用pnpm test，否则使用npm test。如果测试失败，不要自动修复，先输出失败用例的完整堆栈信息。”
• 脚本或工具定义：有些技能需要调用外部脚本，比如一个“生成数据库迁移”的技能可能会附带一个generate-migration.sh脚本。AI代理在执行到这个技能时，会直接调用这个脚本，而不是自己从头拼命令。
• 示例与反例：好的技能包会包含“正确示例”和“错误示例”。正确示例告诉AI代理“这样做是对的”，错误示例告诉它“这样做会出问题”。这比单纯写“不要做X”要有效得多，因为AI代理对具体例子的理解能力远强于对抽象规则的理解能力。

2.2 为什么是“技能”而不是“插件”

这里有一个关键的设计选择：为什么叫“skills”而不是“plugins”或者“extensions”？我个人的理解是，插件通常意味着代码级的扩展，你需要写JavaScript或者Python来注册钩子、修改行为。而技能更偏向于“知识注入”，它不改变AI代理的底层运行逻辑，只是给它补充上下文和操作指南。

这个区别很重要。插件式的扩展往往需要你理解AI代理的内部API，门槛高，而且一旦代理升级，插件可能就失效了。技能式的扩展则相对稳定，因为它本质上就是一段文本，AI代理读懂了就能用。即使代理的底层模型换了，只要它还能理解自然语言指令，技能包就还能工作。这也是为什么agent-skills这个概念在Claude Code社区里特别流行——Claude Code本身就非常擅长理解和执行自然语言指令，给它喂技能包是最高效的扩展方式。

2.3 技能包的加载时机与优先级

另一个需要想清楚的问题是：技能包什么时候被加载？是在会话开始时全部加载，还是按需加载？我实测下来，按需加载是更合理的方案。原因很简单：如果你给AI代理一次性加载了20个技能，它的上下文窗口会被大量无关指令占据，反而容易混淆。按需加载的意思是，AI代理先读取项目的技能索引文件，知道有哪些技能可用，然后在遇到具体任务时再去读取对应的技能详情。

优先级方面，通常遵循“项目级技能 > 用户级技能 > 全局技能”的规则。项目级技能放在项目根目录的.agent-skills/文件夹下，只对当前项目生效。用户级技能放在用户主目录的.agent-skills/下，对所有项目生效。全局技能则是工具自带的默认技能。这个优先级设计很符合直觉：项目特有的规则应该覆盖通用规则。

3. 手把手搭建一个agent-skills工作流

3.1 环境准备与目录结构

假设你已经在用Claude Code，并且项目是一个Node.js的TypeScript项目。我们要搭建一个最小可用的agent-skills工作流。首先在项目根目录创建以下结构：

.agent-skills/ ├── index.json ├── run-tests/ │ ├── SKILL.md │ └── scripts/ │ └── check-db.sh ├── commit-code/ │ └── SKILL.md └── tdd-workflow/ └── SKILL.md

index.json是技能索引，内容大概长这样：

{ "skills": [ { "name": "run-tests", "description": "在当前项目中运行测试，自动检测包管理器并处理数据库依赖", "triggers": ["运行测试", "跑测试", "test", "run tests"] }, { "name": "commit-code", "description": "按照团队规范提交代码，包括格式化、lint检查和提交信息模板", "triggers": ["提交代码", "commit", "git commit"] }, { "name": "tdd-workflow", "description": "按照测试驱动开发的流程引导AI代理逐步完成功能开发", "triggers": ["TDD", "测试驱动", "先写测试"] } ] }

这个索引文件的作用是让AI代理在会话开始时快速了解“这个项目里有哪些技能可用”。注意triggers字段，它定义了哪些用户输入会触发这个技能。当用户说“帮我跑一下测试”时，AI代理会匹配到run-tests技能，然后去读取对应的SKILL.md。

3.2 编写第一个技能：run-tests

run-tests/SKILL.md的内容是整个工作流的核心。我写一个实际可用的版本：

# 运行测试技能 ## 适用场景 当用户要求运行测试、检查代码是否正确、验证功能是否正常时，使用本技能。 ## 执行步骤 1. 首先检测项目使用的包管理器： - 如果存在 `pnpm-lock.yaml`，使用 `pnpm` - 如果存在 `yarn.lock`，使用 `yarn` - 如果存在 `package-lock.json`，使用 `npm` - 如果都不存在，询问用户使用什么包管理器 2. 检查测试是否需要数据库： - 读取 `package.json` 中的 `scripts.test` 字段 - 如果测试命令包含 `db` 或 `database` 关键字，先执行 `scripts/check-db.sh` 确认数据库容器是否运行 - 如果数据库未运行，执行 `docker compose up -d db` 启动数据库，等待5秒后再继续 3. 执行测试命令： - 使用检测到的包管理器运行 `test` 脚本 - 例如：`pnpm test` 或 `npm test` 4. 处理测试结果： - 如果所有测试通过，输出“所有测试通过”并附上测试用例数量 - 如果有测试失败，不要自动修复代码，而是输出失败用例的名称、错误信息和完整堆栈 - 如果测试命令本身报错（如找不到命令），输出错误信息并建议用户检查环境 ## 注意事项 - 不要跳过数据库检查步骤，否则测试会以奇怪的方式失败 - 如果测试运行超过120秒，输出当前进度并询问用户是否继续等待 - 不要自动修改测试文件来让测试通过，这是作弊行为

这个技能文件写得很具体，每一步都有明确的判断条件和执行动作。AI代理读到这个文件后，就知道“跑测试”不是简单地敲一个命令，而是一个包含环境检测、依赖启动、结果处理的完整流程。

3.3 编写TDD工作流技能

TDD工作流技能稍微复杂一些，因为它涉及多个阶段的切换。tdd-workflow/SKILL.md的核心内容是：

# TDD工作流技能 ## 适用场景 当用户要求按照测试驱动开发的方式实现一个新功能时，使用本技能。 ## 阶段划分 ### 阶段一：写一个失败的测试 - 询问用户要实现的函数名、输入和预期输出 - 在对应的测试文件中添加一个测试用例 - 运行测试，确认这个测试失败（这是关键，必须确认失败） - 如果测试意外通过，说明功能已经存在或者测试写错了，停下来询问用户 ### 阶段二：写最少的代码让测试通过 - 只修改必要的源文件，不要添加任何测试没有覆盖的功能 - 运行测试，确认新测试通过 - 同时确认之前的测试没有被破坏 ### 阶段三：重构 - 检查代码是否有重复、命名是否清晰、结构是否合理 - 如果进行了重构，再次运行所有测试确认没有破坏功能 - 询问用户是否继续下一个功能点 ## 关键规则 - 绝对不允许跳过阶段一直接写实现代码 - 每个阶段结束后必须运行测试并输出结果 - 如果用户说“别这么麻烦，直接写实现”，回复“TDD流程需要先有失败的测试，这是为了确保测试真的在验证行为。如果你确定要跳过，请明确告诉我。”

这个技能包把TDD的纪律性带给了AI代理。我实测下来，没有这个技能的时候，Claude Code经常一口气把测试和实现都写完，然后告诉你“测试通过了”。但你仔细看，它写的测试可能根本没有验证到关键逻辑，只是走个形式。有了TDD技能之后，它会老老实实先写一个失败的测试，运行给你看，然后再写实现。这个流程虽然慢一点，但代码质量明显更高。

3.4 技能包的安装与更新

热搜词里提到了“skills CLI”，我猜未来会出现这样的工具。目前我是手动管理这些文件的，但可以想象一个CLI工具的工作方式：

# 安装一个技能包 skills install run-tests # 查看当前项目已安装的技能 skills list # 更新所有技能到最新版本 skills update # 移除某个技能 skills remove commit-code

这个CLI的背后逻辑很简单：从某个技能仓库下载技能文件，放到.agent-skills/目录下，然后更新index.json。如果团队内部有私有的技能仓库，也可以配置CLI从内部源拉取。这样团队里每个人都能用同一套技能包，保证AI代理的行为一致性。

4. 实操中踩过的坑与排查技巧

4.1 技能冲突与优先级混乱

我遇到的最常见问题是技能冲突。比如我同时安装了“run-tests”和“tdd-workflow”两个技能，当我说“跑一下测试”时，AI代理有时候会触发TDD工作流，开始问我“你要实现什么功能”。这是因为两个技能的触发词有重叠，“测试”这个词同时出现在两个技能的triggers里。

解决办法是在index.json里给每个技能设置更精确的触发词，并且加上优先级字段。比如：

{ "name": "run-tests", "triggers": ["运行测试", "跑测试", "执行测试"], "priority": 10 }, { "name": "tdd-workflow", "triggers": ["TDD", "测试驱动", "先写测试再实现"], "priority": 5 }

优先级高的技能先匹配。同时，触发词要尽量具体，“跑测试”和“先写测试再实现”虽然都包含“测试”，但语义完全不同，AI代理更容易区分。

4.2 技能文件太长导致上下文溢出

另一个坑是技能文件写得太长。我一开始把run-tests/SKILL.md写了快2000字，结果AI代理读取这个文件后，上下文里塞满了测试相关的指令，导致它在处理其他任务时也会受到干扰。后来我把技能文件控制在500字以内，只保留最关键的步骤和规则，细节放到单独的脚本里。

提示：技能文件不是文档，不需要面面俱到。它更像是一张“操作卡片”，只写AI代理在执行这个任务时最容易出错的地方。

4.3 AI代理不遵守技能指令

有时候AI代理会“忘记”技能里的规则。比如TDD技能明确说了“阶段一必须确认测试失败”，但它有时候会跳过这个确认步骤。我分析下来，原因是技能文件里的规则不够“显眼”。AI代理在长上下文里容易忽略中间部分的指令。

解决办法是把最关键的规则放在技能文件的开头和结尾，并且用加粗、列表等格式突出。另外，可以在index.json的description字段里也重复一遍核心规则，因为AI代理在匹配技能时会先读这个字段。

4.4 技能包与项目实际环境不匹配

我写过一个“部署到测试环境”的技能，里面写死了kubectl apply -f k8s/test/。结果换了一个项目，那个项目用的是Docker Compose，技能就完全失效了。后来我学乖了，技能文件里不写死具体命令，而是写“检测项目使用的部署工具，如果是Kubernetes则执行X，如果是Docker Compose则执行Y”。

这个思路和前面run-tests技能里的包管理器检测是一样的：让技能具备一定的环境自适应能力，而不是假设所有项目都一样。

4.5 常见问题速查表

5. 技能包设计的心法：从“能跑”到“好用”

5.1 把“判断逻辑”写进技能，而不是留给AI

很多人写技能包的时候，只写“执行什么命令”，不写“什么情况下执行什么命令”。比如只写“运行pnpm test”，但没写“如果pnpm不存在怎么办”。AI代理遇到这种情况时，会自己发挥，而它的发挥往往不符合你的预期。

好的技能包应该把判断逻辑写清楚。我总结了一个模板：

如果 [条件A]，则 [动作X] 如果 [条件B]，则 [动作Y] 如果以上都不满足，则 [询问用户/输出错误]

这个模板看起来很简单，但它能覆盖90%的异常情况。AI代理不需要“猜”你的意图，它只需要按照条件分支执行就行。

5.2 用“反例”约束AI代理的行为

前面提到过，好的技能包会包含错误示例。我举一个实际的例子。在“commit-code”技能里，我写了这样一段：

## 错误示例 - 不要使用 `git commit -m "fix"` 这种无意义的提交信息 - 不要在提交前跳过lint检查，即使代码看起来没问题 - 不要一次性提交多个不相关的修改，应该拆分成多个提交 ## 正确示例 - `git commit -m "fix(auth): 修复登录token过期后未正确刷新"` - 提交前先运行 `pnpm lint` 和 `pnpm format` - 如果修改了多个文件但属于同一功能，可以一起提交

反例的作用是给AI代理划定边界。它可能不知道“什么样的提交信息算好”，但它能理解“fix这种太短的不行”。通过具体例子，AI代理的行为会更接近你的预期。

5.3 技能包的版本管理与团队协作

当团队里有多个人在维护技能包时，版本管理就很重要。我的做法是给每个技能包加一个version字段，并且在SKILL.md的末尾写一个变更日志。比如：

## 变更日志 - v1.2 (2025-01-15): 增加数据库容器检测步骤 - v1.1 (2025-01-10): 支持pnpm和yarn - v1.0 (2025-01-05): 初始版本，仅支持npm

这样当AI代理的行为发生变化时，你能快速定位是哪个版本的技能包导致的。如果团队用Git管理项目，.agent-skills/目录也应该提交到仓库里，这样每个人拉取代码后都能获得相同的技能配置。

5.4 技能包的测试与验证

技能包本身也需要测试。我的做法是写一个简单的验证脚本，模拟AI代理读取技能文件并执行关键步骤。比如对于run-tests技能，验证脚本会：

1. 创建一个临时目录，放入pnpm-lock.yaml和package.json
2. 模拟AI代理读取SKILL.md
3. 检查AI代理是否选择了pnpm而不是npm
4. 检查是否执行了数据库检测步骤

这个验证脚本不需要真的调用AI代理，只需要用正则表达式检查技能文件里是否包含了必要的判断逻辑。虽然简单，但能防止明显的错误。

6. 从agent-skills看AI编码代理的演进方向

折腾了这几个月的技能包之后，我有一个明显的感受：AI编码代理的竞争力正在从“模型有多聪明”转向“生态有多丰富”。Claude Code的底层模型确实强，但如果没有一套好的技能包体系，它在具体项目里的表现可能还不如一个配置了完善技能包的普通代理。

这个趋势对开发者来说是个好消息。你不需要等待模型升级来解决所有问题，你可以通过写技能包来“教”AI代理怎么做你项目里的事。这就像给一个聪明的助手写SOP（标准作业程序），写得好，他就能帮你干很多活；写得不好，他就只能干瞪眼。

热搜词里还有“claude code harness可以不登录用其他模型吗”这样的问题，这说明大家在探索AI编码代理的灵活配置。agent-skills这套思路其实和模型选择是正交的：无论你用哪个模型，技能包都能帮它更好地适应你的项目。模型决定“它有多聪明”，技能包决定“它有多懂你”。

我个人的体会是，花一个小时写一个高质量的技能包，比花一个小时反复给AI代理解释“你应该这样做”要划算得多。技能包是一次性投入，长期复用；而口头解释每次都要重复，而且AI代理还不一定记得住。如果你也在用AI编码代理，强烈建议从今天开始，把你最常重复的那几条指令写成技能包。