企业官网建设流程全解析

1. 从"agent-skills"说起：为什么这个项目值得你花时间

第一次看到agent-skills这个标题，我脑子里蹦出来的不是某个具体工具，而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套"插件化的能力说明书"，让 Claude Code、Cursor、Windsurf 这类 AI 编程代理在特定任务上表现得更像一个有经验的工程师，而不是一个只会补全代码的自动机。

我接触 AI coding agent 的时间不算短，从最早拿 Claude Code 当高级 grep 用，到后来把它接进 CI 流程里跑测试、改 bug、写迁移脚本，中间踩过的坑足够写一本小册子。agent-skills这类项目的核心价值，说白了就一句话：把"怎么让 agent 干好一件事"从散落在各处的 prompt 里抽出来，变成可复用、可版本管理、可组合的技能单元。它解决的是"每次都要重新教 agent 做事"这个重复劳动问题，适合所有已经在用或准备用 AI coding agent 的开发者，尤其是那些想让 agent 参与真实工程流程、而不是只当玩具的人。

这篇文章我会从设计思路、核心机制、实操落地、问题排查四个层面把agent-skills拆开讲透。不管你是刚装好 Claude Code 的新手，还是已经在用 skills CLI 管理一堆技能的老手，都能从里面找到能直接抄作业的东西。我尽量不写那种"官方文档翻译"式的废话，多讲我在实际项目里验证过的做法和踩过的坑。

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

2.1 为什么需要"技能"这一层抽象

在没有 skills 概念之前，大家是怎么让 AI coding agent 干活的？无非几种方式：在对话里临时写一段 prompt、在项目根目录放一个CLAUDE.md或.cursorrules、或者干脆把指令塞进代码注释里。这些方式在单次任务里够用，但一旦任务变复杂、团队变多人、项目变多仓库，问题就全冒出来了。

我举个真实场景。我们团队之前有个需求：每次改数据库 schema，都要同步更新 migration 文件、更新 ORM 模型、更新 API 文档、跑一遍集成测试。最开始我把这套流程写成一段长 prompt 存在笔记里，每次复制粘贴。后来发现三个问题：第一，prompt 越写越长，agent 开始"选择性失忆"，后面的指令经常被忽略；第二，不同人复制的时候会漏掉几步；第三，prompt 和代码不在一个仓库里，改代码的人不知道 prompt 也该改。

agent-skills这类项目的设计思路，本质上是把"一段长 prompt"拆成"多个职责单一的小技能"，每个技能有自己的触发条件、输入输出约定和执行步骤。这跟软件工程里"函数拆分"是一个道理——一个函数只做一件事，组合起来完成复杂流程。技能拆开之后，agent 每次只需要加载当前任务相关的那几个技能，上下文压力小，执行准确率自然就上去了。

提示：技能拆分的粒度很关键。拆得太粗，等于没拆；拆得太细，agent 光加载技能就耗掉大量上下文。我的经验是，一个技能对应"一个可独立验证的产出"，比如"生成一个 migration 文件"是一个技能，"跑通集成测试"是另一个技能。

2.2 技能包的核心组成要素

一个设计良好的 skill，通常包含这么几个部分，我按重要性排序：

• 触发描述（description）：告诉 agent 什么情况下该用这个技能。这段文字的质量直接决定技能会不会被正确调用。写得太泛，agent 到处乱用；写得太窄，该用的时候想不起来。
• 执行指令（instructions）：具体怎么做，分步骤写清楚。这里要避免"正确的废话"，比如"写出高质量的代码"这种指令等于没写，要写成"函数不超过 50 行，每个公开方法必须有 docstring"这种可验证的约束。
• 输入输出约定：技能需要什么参数、产出什么结果。这一步很多人会忽略，但它是技能能组合的前提。
• 示例（examples）：给一两个正例，最好再给一个反例。agent 对示例的敏感度远高于抽象描述。
• 依赖声明：这个技能依赖哪些工具、哪些其他技能、哪些环境变量。

我见过太多人写 skill 只写"执行指令"这一块，结果 agent 要么不触发，要么触发了但产出不符合预期。触发描述和示例这两块，才是决定技能好不好用的关键，值得多花时间打磨。

2.3 与 test-driven-development 的天然契合

热词里出现了test-driven-development，这不是巧合。agent-skills和 TDD 的结合点非常自然：TDD 的核心是"先写测试，再写实现，测试通过才算完成"，而 AI coding agent 最擅长的恰恰是"根据明确的验收标准反复迭代"。

我现在的做法是，凡是让 agent 参与的开发任务，都尽量走 TDD 流程。具体来说，先让 agent 根据需求写测试用例（这一步人必须 review，因为 agent 写的测试经常漏边界），测试跑失败，然后让 agent 写实现直到测试通过。这个流程里，"写测试"和"写实现"就是两个独立的 skill，中间用"测试结果"作为输入输出约定连接起来。

这样做的好处是，agent 有了明确的"完成信号"——测试全绿。没有 TDD 的时候，agent 经常写完代码就说"完成了"，但你一跑发现一堆问题。有了测试作为验收标准，agent 会自己迭代到通过为止，人只需要在最后 review 一次。

2.4 方案选型：为什么是 CLI 而不是插件

skills CLI这个热词说明这类项目普遍选择命令行作为主要交互方式。我一开始也疑惑，为什么不做成 IDE 插件，图形界面不是更友好吗？用了一段时间之后我理解了：CLI 的天然优势是"可组合"和"可脚本化"。

技能管理这件事，本质上和包管理很像——安装、卸载、更新、列出、搜索。这些操作用 CLI 做，可以轻松接进 CI、接进 git hook、接进其他脚本。而 IDE 插件受限于宿主环境，跨编辑器复用困难。更重要的是，CLI 让技能包可以像 npm 包一样被版本管理，agent-skills的更新可以走标准的依赖升级流程，而不是手动去插件市场点更新。

当然 CLI 也有代价，就是学习曲线。但考虑到目标用户本来就是开发者，这个代价可以接受。我的建议是，如果你刚开始用，先把 CLI 的基本命令摸熟，别急着上图形界面。

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

3.1 技能目录结构与文件组织

一个规范的 skills 仓库，目录结构通常长这样：

agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── db-migration/ │ │ ├── SKILL.md │ │ └── templates/ │ └── api-doc-sync/ │ └── SKILL.md ├── skills.json └── README.md

每个技能一个目录，目录名就是技能标识符，用 kebab-case 命名。核心文件是SKILL.md，里面用 frontmatter 写元数据，正文写指令。examples/放示例，scripts/放技能执行时可能调用的辅助脚本，templates/放模板文件。

skills.json是清单文件，记录所有技能的元信息，方便 CLI 快速索引而不用遍历所有目录。这个设计跟package.json是一个思路。

注意：技能目录名一旦确定就不要随便改，因为其他技能可能通过名字引用它。改名等于破坏性变更，要走版本升级流程。

3.2 SKILL.md 的写法：从"能跑"到"好用"

SKILL.md是整个技能的核心，我把它拆成 frontmatter 和正文两部分讲。

frontmatter 部分至少要包含这几个字段：

--- name: tdd-workflow description: 当需要按测试驱动开发流程实现新功能时使用。先写失败测试，再写实现，迭代到测试通过。 version: 1.2.0 tags: [testing, workflow, tdd] dependencies: [test-runner] ---

description这一行是重中之重。我踩过的坑是，早期把 description 写成"用于 TDD 开发"，结果 agent 在写文档、改配置的时候也偶尔触发它。后来改成"当需要按测试驱动开发流程实现新功能时使用"，触发准确率明显提升。description 要写清楚"什么时候用"，而不是"这是什么"。

正文部分我一般按这个结构写：

1. 前置检查：执行前需要确认什么，比如"确认测试框架已配置"。
2. 执行步骤：分步骤，每步一个明确动作。
3. 验收标准：怎么算完成，比如"所有测试通过且覆盖率不低于 80%"。
4. 失败处理：测试不通过时怎么办，比如"分析失败原因，修改实现，重新运行，最多迭代 5 次"。
5. 示例：一个完整的正例。

这里有个经验：步骤要写成"动词开头"的祈使句，比如"运行npm test"而不是"测试应该被运行"。agent 对祈使句的执行意愿明显更高。

3.3 触发机制：agent 怎么知道该用哪个技能

这是很多人困惑的地方。agent 不是人，它不会"记住"所有技能然后按需调用。实际机制通常是：把所有技能的 description 拼成一段索引，放在 agent 的上下文里，agent 根据当前任务判断该加载哪个技能的完整内容。

这就解释了为什么 description 的质量如此关键。它相当于技能的"广告词"，要在几十个技能里脱颖而出，让 agent 在正确的时机想起它。

我总结了几条写 description 的实操技巧：

• 用"当……时使用"的句式，明确触发场景。
• 包含具体的动作词，比如"生成""校验""重构""迁移"。
• 避免和其他技能的 description 高度重叠，否则 agent 会犹豫。
• 长度控制在 50 到 100 字，太短信息不够，太长挤占上下文。

实测下来，description 写得好，技能触发准确率能从六七成提到九成以上。这个投入产出比非常高。

3.4 技能组合：让多个技能串成工作流

单个技能能做的事有限，真正的威力在于组合。agent-skills支持技能之间互相引用，形成一个有向图。比如"实现新功能"这个高层技能，可以依次调用"写测试""写实现""跑测试""更新文档"四个子技能。

组合的时候要注意几点：

• 避免循环依赖：A 调用 B，B 又调用 A，agent 会陷入死循环。设计时画一下依赖图。
• 明确数据传递：上一个技能的产出怎么传给下一个。通常通过文件或者约定的变量名。
• 失败要能中断：子技能失败时，父技能应该停止而不是继续往下走。

我一般会把常用的组合固化成"工作流技能"，比如feature-development就是一个组合技能，内部编排了 TDD 全流程。这样日常使用只需要触发一个技能，不用手动串。

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

4.1 环境准备：从零搭起 skills 工作区

假设你现在什么都没装，我带你走一遍完整流程。这里以 Claude Code 作为 agent 宿主举例，其他 agent 的接入方式类似。

第一步，确认 Node.js 环境。skills CLI 通常基于 Node 生态：

node -v # 建议 18.x 或以上 npm -v

第二步，安装 skills CLI。具体包名以项目文档为准，一般形式是：

npm install -g @your-scope/skills-cli skills --version

第三步，初始化工作区。在你的项目根目录执行：

skills init

这会生成skills/目录和skills.json清单文件。如果你已经有现成的技能仓库，用skills link把它链接进来。

第四步，验证 agent 能读到技能。在 Claude Code 里输入一句"列出当前可用的技能"，如果配置正确，agent 会返回技能列表。如果返回空，检查skills.json的路径配置和 agent 的技能索引配置。

提示：不同 agent 读取技能索引的方式不一样。Claude Code 通常通过项目根目录的配置文件指定技能目录，具体字段名以官方文档为准。配置错了不会报错，只是技能静默不生效，这点很坑，一定要主动验证。

4.2 写第一个技能：以"生成数据库迁移"为例

我拿一个真实需求来演示：每次改 schema，自动生成 migration 文件。这个技能我用了大半年，很稳。

先建目录：

mkdir -p skills/db-migration/templates

然后写SKILL.md：

--- name: db-migration description: 当需要根据 schema 变更生成数据库迁移文件时使用。读取当前模型定义，对比目标 schema，生成可回滚的 migration。 version: 1.0.0 tags: [database, migration] dependencies: [] --- ## 前置检查 1. 确认项目使用支持 migration 的 ORM（如 Prisma、TypeORM、Alembic）。 2. 确认当前工作区没有未提交的 migration 文件。 ## 执行步骤 1. 读取 `schema/` 目录下的当前 schema 定义。 2. 对比目标 schema，列出所有差异（新增表、删除表、字段变更、索引变更）。 3. 为每个差异生成对应的 up 和 down 操作。 4. 将 migration 写入 `migrations/` 目录，文件名格式为 `YYYYMMDDHHMMSS_description.sql`。 5. 运行 migration 的 dry-run 校验语法。 ## 验收标准 - migration 文件能通过 dry-run。 - 每个 up 操作都有对应的 down 操作。 - 不包含任何数据删除操作，除非显式要求。 ## 失败处理 - dry-run 失败：读取错误信息，修正语法，重新生成。 - 存在无法自动处理的差异：停止并输出差异清单，请求人工介入。

写完这个文件，用skills validate db-migration校验格式。然后在一个真实 schema 变更上测试，观察 agent 是否按步骤执行。

我实测下来，这个技能把原来每次 15 分钟的迁移编写压缩到 2 分钟 review。关键是 down 操作也自动生成了，回滚的时候不用临时补。

4.3 接入 TDD 工作流：完整跑一遍

现在把 TDD 技能和迁移技能组合起来，演示一个完整的功能开发流程。

场景：给用户表加一个last_login_at字段，并写一个记录登录时间的接口。

第一步，触发tdd-workflow技能，让 agent 先写测试：

请用 tdd-workflow 技能为"记录用户登录时间"功能编写测试。

agent 会生成测试文件，包含：登录成功后last_login_at被更新、登录失败时不更新、时间格式正确等用例。这一步人必须 review，我见过 agent 写的测试只覆盖 happy path，边界全漏。

第二步，跑测试，确认全部失败（因为实现还没写）。这是 TDD 的红灯阶段。

第三步，触发实现技能，让 agent 写代码直到测试通过：

请实现上述测试对应的功能，迭代到所有测试通过。

agent 会进入"写代码—跑测试—看失败—改代码"的循环。这里有个经验：给 agent 设置最大迭代次数，比如 5 次。超过就停下来让人介入，否则它可能在一个死胡同里反复撞墙，浪费 token。

第四步，测试全绿后，触发db-migration技能生成字段变更的迁移文件。

第五步，人工 review 所有产出：测试、实现、迁移。确认无误后提交。

整个流程走下来，一个中等复杂度的功能大概 20 到 30 分钟，其中人的介入主要是两次 review。相比纯手写，效率提升明显，而且测试覆盖率有保障。

4.4 参数与配置：几个容易配错的点

实操中有几个配置项特别容易出问题，我列一下：

上下文预算这一项我要多说一句。agent 的上下文窗口是有限的，技能加载、代码读取、对话历史都在抢这个空间。我见过有人装了 50 个技能，结果 agent 每次响应都变慢、变笨，就是因为索引占用了太多上下文。技能不是越多越好，常用的十几个就够了，其余按需临时加载。

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

5.1 技能不触发：从三个方向排查

技能不触发是最常见的问题，我按排查顺序列一下。

第一，检查 description 是否清晰。把 description 单独拿出来读，问自己"这句话能让我在正确的场景想起这个技能吗"。如果答案模糊，重写。

第二，检查技能是否被正确索引。运行skills list看技能在不在列表里。不在的话，检查skills.json和目录结构。

第三，检查触发场景是否真的匹配。有时候是任务描述太模糊，agent 无法判断。试着在任务里明确提到技能名，比如"用 db-migration 技能生成迁移"。

我整理了一个速查表：

5.2 执行结果不稳定：如何提高可复现性

同一个技能，今天跑得好，明天跑得差，这是 AI agent 的固有特性。但可以通过一些手段提高稳定性。

固定输入。技能执行依赖的文件、环境变量、工具版本，尽量固定。比如测试框架版本变了，agent 生成的测试可能就不兼容。

降低温度参数。如果 agent 支持调 temperature，技能执行时调低，输出更确定。

加自检步骤。在技能末尾加一步"检查产出是否符合验收标准"，让 agent 自己发现问题。

记录执行日志。每次执行把输入输出存下来，出问题时能对比。我一般会在技能里加一步"把本次执行的关键信息写入.skills-log/目录"。

5.3 踩过的坑：几个血泪教训

坑一：技能里写了破坏性操作。早期我写过一个"清理临时文件"的技能，指令是"删除所有未跟踪的文件"。结果 agent 在一个没配好 gitignore 的项目里执行，删掉了一堆本该保留的文件。教训是，破坏性操作必须加确认步骤，或者限制作用范围。

坑二：技能依赖外部服务但没处理失败。有个技能要调外部 API，我没写失败处理，结果 API 挂了之后 agent 一直重试，把配额耗光了。现在所有外部依赖都加超时和重试上限。

坑三：技能之间循环引用。A 技能说"参考 B 技能的做法"，B 技能说"参考 A 技能的做法"，agent 直接懵了。设计依赖图的时候一定要检查有没有环。

坑四：description 用了太多同义词。我写过一个技能 description 里同时出现"重构""优化""改进"，结果 agent 在三种场景都触发它，但实际它只适合重构。一个技能只描述一种场景。

5.4 性能优化：让技能跑得更快更省

技能执行慢、耗 token 多，是规模化使用后的主要痛点。我总结了几条优化经验。

精简技能内容。把不常用的分支拆出去，主技能只保留核心路径。我有个技能从 800 行精简到 300 行，执行时间降了一半。

缓存中间结果。技能执行中如果某一步结果可复用，存到缓存目录，下次直接读。

并行化独立步骤。如果技能里有多个互不依赖的步骤，让 agent 并行执行。不过要注意，不是所有 agent 都支持并行，得看具体实现。

按需加载。别把所有技能都塞进上下文，用索引加按需加载的方式。这个前面提过，是省 token 的大头。

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

6.1 版本管理：像管代码一样管技能

技能是代码，就该用代码的方式管理。我的做法是，技能仓库独立成一个 git 仓库，走标准的 PR 流程。每次修改技能，都要说明改了什么、为什么改、怎么验证的。

版本号用语义化版本。改 description 或加示例，算 patch；加步骤或改验收标准，算 minor；改输入输出约定或删步骤，算 major。major 变更要通知所有使用方。

skills.json里记录每个技能的版本，CLI 可以据此检查更新。我一般会定期跑skills outdated看有没有新版本，但不会自动升级，因为技能变更可能影响现有工作流，得先测试。

6.2 团队协作：让技能成为团队资产

一个人用技能和团队用技能，复杂度完全不一样。团队用的时候，要考虑几个问题。

统一技能源。别每个人维护自己的技能副本，用一个共享仓库，大家 link 过去。这样改一处，所有人受益。

明确 owner。每个技能指定一个负责人，负责 review 变更、处理问题。没有 owner 的技能会慢慢腐烂。

写使用文档。技能本身是给 agent 看的，但团队需要一份给人看的文档，说明有哪些技能、各自干什么、怎么组合。这份文档我一般放在仓库 README 里。

定期清理。过时的技能及时删，别留着占索引。我每季度清理一次，删掉三个月没人用的技能。

6.3 安全与合规：技能里的红线

技能会执行真实操作，安全不能马虎。几条红线我列一下。

• 不写破坏性操作，或者必须加二次确认。
• 不硬编码密钥，用环境变量。
• 不访问未授权的资源，技能里涉及的外部调用要明确声明。
• 不生成可能有害的内容，比如批量删除、绕过校验的代码。
• 技能变更要 review，尤其是涉及文件系统、网络、数据库操作的。

我见过有人写了个技能自动提交代码到主分支，结果 agent 误触发，把半成品推上去了。涉及 git 操作的技能，一定要限制在 feature 分支。

7. 从 agent-skills 延伸出去的几个方向

7.1 技能市场与共享生态

agent-skills这类项目发展到一定阶段，自然会走向技能共享。现在已经能看到一些技能市场的雏形，大家可以发布、搜索、安装别人写的技能。这对新手特别友好，不用从零写，先拿现成的用。

但共享也带来质量参差的问题。我的建议是，用别人的技能前先读一遍SKILL.md，确认它做的事符合你的预期，尤其是涉及文件操作的。别看到名字就装。

7.2 技能与 CI/CD 的集成

技能不只能在本地用，还能接进 CI。比如在 PR 流程里加一步"用 code-review 技能自动审查变更"，或者在发布流程里加"用 changelog 技能生成发布说明"。

我现在的做法是，把几个稳定的技能接进 CI，作为自动化检查的一部分。注意 CI 环境里 agent 的权限要收紧，别给它写仓库的权限。

7.3 技能的可观测性

技能跑多了之后，你会想知道：哪些技能用得最多、哪些经常失败、平均执行多久。这些数据能指导优化。我一般会在技能执行时打点，记录技能名、耗时、结果状态，汇总到一个看板里。

有了数据之后，优化就有方向了。比如发现某个技能失败率特别高，就去查原因；发现某个技能没人用，就考虑删掉。

8. 我个人的一些实操体会

用agent-skills这套东西大半年，最大的体会是：技能的质量不取决于你写了多少，而取决于你删了多少。一开始我恨不得把每个操作都写成技能，结果索引臃肿、触发混乱。后来砍到十几个核心技能，反而好用多了。

另一个体会是，技能要跟着项目演进。项目初期和成熟期需要的技能完全不一样。初期可能需要大量脚手架类技能，成熟期更需要重构、审查、文档类技能。定期回顾技能库，该加的加，该删的删。

最后分享一个小技巧：给每个技能加一个"最后验证时间"字段，记录上次实际跑通是什么时候。超过一个月没验证的技能，用之前先跑一遍，别直接信。技能依赖的外部环境会变，昨天能跑的今天不一定能跑。

这套东西还在快速演进，今天的最佳实践明天可能就过时了。保持关注，但别追新追到忘了目的——目的是让 agent 帮你把活干好，不是收集技能。