企业官网建设流程全解析

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

第一次看到agent-skills这个项目名，我脑子里蹦出来的不是某个具体工具，而是一类正在快速成型的东西——给AI编码代理（AI coding agents）定义、管理和分发“技能”的基础设施。你可以把它理解成给一个刚入职的工程师发一本《岗位操作手册》，手册里写清楚：遇到什么任务、该调用哪些工具、按什么顺序执行、验收标准是什么。agent-skills干的就是这件事，只不过服务对象是 Claude Code 这类AI编码代理。

我接触 Claude Code 有一段时间了，从最早的命令行版本到后来在 VS Code 里配置插件，踩过的坑不算少。最开始我把它当成一个“更聪明的代码补全”，用着用着发现不对劲——它真正的价值在于能直接执行终端命令、读写文件、跑测试、迭代修复。但问题也随之而来：每次开新会话，它对我项目的约定、测试规范、目录结构一无所知，我得反复用自然语言交代背景。agent-skills这类项目要解决的核心痛点就在这：把重复的上下文和操作规范沉淀成可复用的“技能”，让代理一上来就知道该怎么干活。

这篇文章适合几类人看：一是已经在用 Claude Code 或类似AI编码代理、但觉得每次都要重新“调教”很烦的开发者；二是想搞清楚skills CLI这类工具到底解决什么问题、值不值得投入时间的中级工程师；三是团队里负责工程效率、想把AI代理纳入规范化流程的技术负责人。我会从设计思路、核心机制、实操落地、问题排查几个层面把它讲透，尽量让你看完就能动手试。

需要先说明一点：agent-skills这个标题本身比较宽泛，网络上围绕它的讨论大多和 Claude Code 的技能扩展、skills CLI的用法、以及 test-driven-development 这类具体技能包相关。我下面讲的内容，是基于这类项目的常见设计模式和我在实际使用中的经验做的合理补全，具体命令和目录结构请以你实际拿到的版本为准。

2. 核心设计思路拆解：技能包到底该怎么组织

2.1 为什么是“技能”而不是“配置”

很多人第一反应是：这不就是个配置文件吗？我写个.claude/config不就行了。我一开始也这么想，但实际用下来发现“配置”和“技能”有本质区别。配置是静态的声明，比如“用哪个模型”“超时时间多少”；技能是动态的能力单元，它包含触发条件、执行步骤、依赖工具、验收标准这一整套东西。

打个比方，配置像是你告诉新员工“公司用的是Mac、代码仓库在GitLab”；技能则是“当你收到一个bug报告时，先复现、再写失败测试、再修复、再跑全量测试、最后提交”。前者是环境信息，后者是行为模式。agent-skills把后者抽象出来，好处是可组合、可版本化、可跨项目复用。

从工程角度看，这个选择非常关键。如果只是配置，那每个项目都得重写一遍；做成技能包之后，你可以把“TDD开发流程”这个技能装到所有项目里，把“React组件规范”装到前端项目里，按需组合。这也是为什么skills CLI这类工具会出现——它需要一套机制来安装、卸载、列出、更新技能。

2.2 技能包的目录结构设计逻辑

基于我见过的几个类似实现，一个典型的技能包目录大概长这样：

skills/ test-driven-development/ SKILL.md scripts/ run-tests.sh templates/ test-template.ts code-review/ SKILL.md checklists/ security.md

核心是那个SKILL.md，它承担了“说明书”的角色。为什么用 Markdown 而不是 JSON 或 YAML？我的理解是：这个文件主要是给AI代理读的，不是给程序解析的。Markdown 的自然语言描述能力更强，代理可以直接理解“什么时候用这个技能”“步骤是什么”，而不需要严格的schema。当然，有些实现会在 Markdown 里嵌入结构化的 frontmatter 来做元数据管理，这是折中方案。

scripts/目录放的是技能执行时需要调用的脚本，比如跑测试的 shell 脚本。templates/放的是代码模板，比如新建测试文件时的骨架。这种分层的好处是技能本身保持轻量，重逻辑外置成可执行文件，代理只需要知道“什么时候调用哪个脚本”，不需要把脚本内容全塞进上下文。

2.3 与 Claude Code 的集成方式

Claude Code 本身支持通过CLAUDE.md文件来注入项目级上下文，这是最基础的定制方式。但CLAUDE.md的问题是它是扁平的、全量的——每次会话都会把整个文件读进去，不管当前任务用不用得上。技能包机制则更精细：代理可以根据当前任务按需加载相关技能。

我实测下来，集成方式通常有两种。一种是目录约定式：把技能包放在项目根目录的.claude/skills/下，Claude Code 启动时自动扫描。另一种是CLI 管理式：通过skills命令全局安装技能，然后在项目里通过配置文件声明启用哪些。前者适合项目专属技能，后者适合跨项目复用的通用技能。两种方式可以混用，优先级一般是项目级覆盖全局级。

注意：如果你在 Ubuntu 或 Mac 上配置 Claude Code，技能目录的路径要写对。Linux/macOS 下是~/.claude/skills/作为全局目录，Windows 下则是%USERPROFILE%\.claude\skills\。路径写错是新手最常见的“技能不生效”原因。

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

3.1 SKILL.md 到底该写什么

这是整个技能包最核心的文件，写得好不好直接决定代理能不能正确使用。我总结了一个实用的结构模板，分四块：

第一块是触发描述。用一两句话说明“什么情况下该用这个技能”。比如 TDD 技能的触发描述可以写：“当需要新增功能或修复bug时，在写实现代码之前使用本技能”。这里的关键是描述要具体到场景，不能写“用于开发”这种废话，代理没法判断什么时候该调用。

第二块是前置条件。说明执行这个技能需要什么环境。比如“项目已配置测试框架”“当前在git仓库中”“有可用的测试命令”。这些条件代理会去验证，不满足就跳过或提示。

第三块是执行步骤。这是重头戏，要写成有序的、可操作的步骤。我建议每一步都包含三个要素：做什么、用什么工具、怎么算完成。举个例子：

1. 阅读需求，在tests/目录下新建测试文件，文件名遵循*.test.ts规范。完成标志：文件创建成功。
2. 编写一个会失败的测试用例，覆盖需求的核心行为。完成标志：运行测试命令，确认测试失败且失败原因符合预期。
3. 编写最小实现让测试通过。完成标志：测试命令返回成功。
4. 重构实现，保持测试通过。完成标志：测试仍然成功，且代码符合项目规范。

第四块是验收标准。明确告诉代理“做到什么程度算完”。这一步很多人会忽略，导致代理做完一步就停下来问“还要继续吗”。写清楚验收标准能大幅减少来回确认。

3.2 脚本与模板的编写要点

scripts/里的脚本我建议遵循几个原则。第一是幂等，同一个脚本跑两次结果应该一致，避免代理重试时产生副作用。第二是输出可解析，脚本的 stdout 最好是结构化的，比如测试脚本输出PASS: 12 FAIL: 0，代理能直接读。第三是错误码规范，0 表示成功，非0表示失败，代理靠这个判断下一步。

templates/里的模板要注意占位符清晰。比如测试模板里用{{TEST_NAME}}、{{MODULE_PATH}}这种明确的占位符，代理替换时不容易出错。我见过有人用XXX做占位符，结果代理把代码里本来就有的XXX也替换了，闹出笑话。

3.3 skills CLI 的常用操作

skills CLI是管理技能包的命令行工具，我常用的几个操作：

# 列出已安装的技能 skills list # 安装一个技能包（从本地目录或远程仓库） skills install ./my-skill skills install github:user/repo # 在项目中启用某个技能 skills enable test-driven-development # 查看某个技能的详情 skills info test-driven-development # 更新所有技能 skills update

这里有个实操心得：安装技能后一定要用skills info确认一下，看看 SKILL.md 有没有被正确解析、依赖的脚本有没有执行权限。我有一次在 Ubuntu 上装完技能，代理死活不调用，查了半天发现是脚本没有+x权限，chmod +x scripts/*.sh之后就好了。

提示：如果你用的是第三方API接入方式（比如通过 cc switch 接入其他模型），技能包的兼容性要额外验证。不同模型对 Markdown 指令的遵循程度不一样，有些模型会忽略 SKILL.md 里的步骤直接干活。建议先用官方模型验证技能逻辑，再换其他模型。

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

4.1 从零搭建一个 TDD 技能包

我拿 test-driven-development 这个最典型的技能来走一遍完整流程。假设你已经在 Ubuntu 上装好了 Claude Code，项目是一个 TypeScript 的 Node 项目。

第一步，创建技能目录结构。

mkdir -p .claude/skills/test-driven-development/{scripts,templates} cd .claude/skills/test-driven-development

为什么放在.claude/skills/下？因为这是 Claude Code 默认扫描的项目级技能目录，放这里不需要额外配置就能被识别。

第二步，编写 SKILL.md。

--- name: test-driven-development description: 在编写实现代码前先写测试，确保代码行为符合预期 version: 1.0.0 --- # TDD 开发技能 ## 触发条件 当需要新增功能、修复bug、或重构现有代码时，在修改实现代码之前使用本技能。 ## 前置条件 - 项目已配置测试框架（如 jest、vitest） - 存在可执行的测试命令（如 `npm test`） - 当前工作目录是 git 仓库 ## 执行步骤 1. **理解需求**：阅读任务描述，明确要实现的输入输出行为。 完成标志：能用一句话描述预期行为。 2. **编写失败测试**：在 `tests/` 目录下创建或修改测试文件，编写一个覆盖目标行为的测试用例。 使用模板：`templates/test-template.ts` 完成标志：测试文件已保存。 3. **运行测试确认失败**：执行 `npm test`，确认新测试失败，且失败原因是功能未实现。 完成标志：测试输出显示新用例 FAIL。 4. **编写最小实现**：修改实现代码，只写让测试通过所需的最少代码。 完成标志：`npm test` 显示新用例 PASS。 5. **重构**：在测试保持通过的前提下优化代码结构。 完成标志：`npm test` 全部 PASS，代码符合项目 lint 规范。 ## 验收标准 - 所有测试通过 - 新增代码有对应的测试覆盖 - 没有跳过或注释掉的测试

这个文件的关键在于步骤足够具体，代理不需要猜“最小实现”是什么意思，它知道就是“只写让测试通过的最少代码”。

第三步，编写测试模板。

// templates/test-template.ts import { describe, it, expect } from 'vitest'; import { {{FUNCTION_NAME}} } from '{{MODULE_PATH}}'; describe('{{TEST_SUITE_NAME}}', () => { it('{{TEST_DESCRIPTION}}', () => { // Arrange const input = {{INPUT}}; const expected = {{EXPECTED}}; // Act const result = {{FUNCTION_NAME}}(input); // Assert expect(result).toEqual(expected); }); });

占位符用双花括号，清晰且不容易和代码冲突。

第四步，编写测试运行脚本。

#!/bin/bash # scripts/run-tests.sh set -e npm test -- --reporter=json 2>&1 | tee /tmp/test-output.json

set -e保证脚本在测试失败时返回非0退出码，代理能据此判断。输出重定向到文件方便代理读取详细结果。

第五步，赋予执行权限并验证。

chmod +x scripts/run-tests.sh skills list skills info test-driven-development

确认技能被正确识别后，就可以在 Claude Code 里触发它了。你可以直接说“用TDD方式实现一个字符串反转函数”，代理应该会自动加载这个技能并按步骤执行。

4.2 参数选择与配置细节

技能包里有几个参数值得单独说。版本号建议遵循语义化版本，因为skills update会依赖它判断是否需要更新。description 字段要写得足够区分度，如果你装了多个技能，代理靠这个字段做初步筛选。

关于技能的粒度，我的经验是一个技能只做一件事。我见过有人把“写代码+跑测试+提交git+发通知”全塞进一个技能，结果代理执行到一半卡住，你都不知道是哪一步的问题。拆成四个技能，每个都能独立验证，出问题好定位。

还有一个容易忽略的点是技能之间的依赖关系。比如“代码审查”技能可能依赖“运行测试”技能先通过。这种依赖可以在 SKILL.md 里用自然语言说明，但更可靠的做法是在脚本层面做检查——审查脚本先跑测试，测试不过直接退出。

4.3 在 VS Code 中的集成体验

如果你是通过 VS Code 插件使用 Claude Code，技能包的体验和命令行基本一致，但有几个细节要注意。插件的终端环境和系统终端可能有差异，脚本里用到的命令要确保在插件终端里也能找到。我遇到过npm在系统终端能用、在插件终端报 command not found 的情况，原因是插件的 PATH 没继承完整，在脚本里写绝对路径或者显式 source 环境变量就能解决。

另外，VS Code 插件里触发技能的方式通常是在对话中自然提及，比如“按TDD流程来做”。插件会把当前项目的技能列表注入上下文，代理自己判断该用哪个。如果发现代理没调用，可以在对话里明确说“使用 test-driven-development 技能”，强制它加载。

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

5.1 技能不生效的排查路径

这是最高频的问题，我整理了一个排查顺序，按这个走基本能定位：

我踩过最坑的一次是 SKILL.md 的 frontmatter 里name字段用了大写字母，而 CLI 内部做了小写归一化，导致skills info找不到。改成全小写就好了。这种细节文档里一般不写，只能靠踩坑积累。

5.2 代理执行到一半停下来的处理

有时候代理执行到某个步骤就停了，既不报错也不继续。这通常是因为步骤的完成标志不够明确，代理不确定自己做完了没有。解决办法是在 SKILL.md 里把完成标志写得更具体，比如把“测试通过”改成“运行npm test后终端输出包含Tests: 5 passed”。

另一个原因是步骤太长，代理的上下文窗口装不下。这时候要把技能拆细，或者把中间产物写到文件里，让代理读文件而不是靠记忆。我一般建议单个技能的步骤不超过7步，超过就考虑拆分。

5.3 第三方模型接入时的注意事项

通过 cc switch 这类工具接入其他模型时，技能包的兼容性要重点验证。不同模型对 Markdown 指令的遵循度差异很大。我的经验是：指令越结构化、越接近代码，兼容性越好。比如用有序列表加明确的完成标志，比用大段自然语言描述效果好。

还有一个坑是模型可能“自作聪明”跳过步骤。比如TDD技能里明确说“先写失败测试”，但某些模型会直接写实现然后补测试。这时候可以在 SKILL.md 里加一句“严禁跳过任何步骤，必须按顺序执行”，并在验收标准里检查测试是否真的先失败过。实测下来，加上这句之后遵循度明显提升。

注意：如果你在配置过程中遇到“claude code might not be available in your country”这类提示，那是服务可用性问题，和技能包本身无关。技能包是本地文件，只要代理能正常运行，技能机制就能用。

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

当团队多人使用同一套技能包时，版本管理就很重要。我的做法是把技能包纳入项目仓库，放在.claude/skills/下一起提交。这样每个人拉代码就自带技能，不需要单独安装。全局通用的技能则通过skills install从内部仓库安装，用版本号锁定。

更新技能时要小心破坏性变更。比如你把某个步骤的完成标志改了，之前依赖旧标志的自动化流程可能就断了。建议技能包也遵循语义化版本，破坏性变更升大版本，并在 CHANGELOG 里写清楚。

6. 技能包的扩展玩法与个人体会

技能包机制真正有意思的地方在于它可以承载团队的最佳实践。我们团队把代码审查清单、提交信息规范、甚至事故复盘模板都做成了技能。新同事入职，装好技能包，代理就会按团队规范引导他干活，比看文档效率高得多。

我还试过把技能包和 CI 结合。在 CI 脚本里调用skills命令验证技能包完整性，确保提交的技能文件格式正确、脚本可执行。这样能避免有人改了 SKILL.md 但忘了改脚本导致的运行时错误。

最后分享一个我个人的小技巧：给每个技能写一个“反例”。在 SKILL.md 里加一段“不要这样做”，列出常见的错误用法。比如TDD技能里写“不要在测试通过前重构”“不要一次写多个测试”。代理对否定指令的遵循度有时候比肯定指令还高，加上反例之后执行质量明显更稳。

这个方向后续还能扩展的地方很多，比如技能之间的自动编排、根据任务类型动态推荐技能、技能执行效果的数据回收和优化。我现在还在摸索的是怎么让代理自己判断“当前任务需要组合哪几个技能”，这比单个技能的执行要复杂一个量级，但一旦跑通，AI编码代理的自主性会上一个大台阶。