企业官网建设流程全解析

如果你也是天天泡在 AI 编码助手里的程序员，大概率遇到过这种场面：让 Claude Code 写个函数、修个 bug，它反应快得像个老手，几乎不用你多费口舌。可一旦换成“按团队规范审查这段代码”“给这个模块补齐单元测试”“整理本次发版变更日志”这类需要固定流程的任务，它在每个新会话里都像第一次干这活儿一样，问东问西、自由发挥，上次总结好的套路这次全忘了。你只能把需求和规范从头到尾再敲一遍，然后祈祷它这次别跑偏。

这个问题的本质，不是模型不够聪明，而是缺少一种把“操作经验”固化下来、随取随用的机制。我花了不少时间研究 Claude Code 里的 Agent Skills 机制，又动手拆了几个实际场景把流程跑通，才把这事儿彻底弄明白。这篇就围绕 Agent Skills 的架构定位、模块化组件的设计思路，以及我在实操中总结的踩坑经验展开。内容更适合已经在用 Claude Code、想把它从“会写代码的助手”升级成“熟悉你团队流程的资深同事”的人。

1. 为什么需要 Agent Skills——AI 编码助手在长会话里的三大痛点

1.1 “有知识，没流程”的尴尬

大模型确实“知道”代码审查该看什么、单元测试该覆盖哪些分支，它从海量代码和文档里学到过这些概念。但“知道”和“每次都按最优路径执行”是两码事。我让 Claude Code 给一个 Python 模块补测试时，第一次它认真地做了 mock、测了异常分支；第二次换了个会话，它却只顾着把正常路径跑通，边界条件全丢了。

这就是典型的能力与流程分离：模型拥有完成任务所需的知识储备，但它没有一个稳定的操作流程可遵循。同一个任务，在十个不同会话里会有十种做法，质量全靠“抽卡”。人可以通过 SOP 解决这个问题，模型在默认情况下却没有 SOP。

1.2 长上下文带来的“规则漂移”

另一个让人头疼的问题是，即使你在会话开头把规范完整贴给 Claude Code，对话进行到两三千行上下文时，它的注意力会被中间讨论的过程占据，早期那些规范细节开始变得模糊。表现为：一开始它还记着“变量命名按项目规范走”，到后面就开始按自己舒服的方式来。

这有点像让一个新人同时接收任务目标和过程记录，结果他记住了过程中的细枝末节，忘了最终验收标准。上下文越长，关键指令被稀释得越厉害。每次重新描述规范，既费时又不可靠。

1.3 团队经验无法沉淀

个人开发者还好，最多少写几遍。但在团队场景里，这个问题会放大成流程事故：代码规范散落在文档里、测试套路存在老员工的脑子里、发布检查项在群聊的聊天记录里。Claude Code 根本无从得知这些经验的存在，于是它每次都从零开始“发明”一套做法，和团队实际沉淀的套路经常对不上。

我真正开始重视 Agent Skills，就是因为在一次团队内部分享里看到同事把一个“发布前检查清单”做成了 Skill，模型每次发版前都会自动按这个清单逐项核对，而不是靠人提醒。那一刻我才意识到：这不只是给模型加功能，这是把组织经验变成可执行、可版本化、可审计的资产。

2. Agent Skills 的架构定位——它是 Claude Code 体系里的哪一层？

2.1 三层能力划分：对话、连接、方法论

理解 Agent Skills，最好先把它放进 Claude Code 的整体架构里看。按我的理解，整个体系可以粗略分成三层：

第一层是基础的对话与代码操作能力，模型本身就能完成，比如理解你的问题、搜索文件、生成代码。这一层是地基，决定了模型“聪不聪明”。

第二层是通过 MCP 这类协议引入外部工具和数据源，相当于给模型接上了外部的手脚：查数据库的客户端、调云平台 API 的 SDK、浏览网页的抓取器。这一层解决的是“够得着”的问题。

第三层就是 Agent Skills。它和 MCP 不同，它不提供新工具，而是提供做一件事的“方法论”。它封装的是：面对某类任务时，应该按什么步骤走、中间要注意什么、哪些做法是禁止的、最终产出应该长什么样。

用一句不太严谨但很好记的话来说：MCP 是给模型更多“手”，Skills 是给模型一本“操作手册”。

2.2 和 MCP、普通提示词模板的边界

我见过不少人对 Skills 和 MCP 的区别犯迷糊，这俩确实都叫“扩展”，但解决的问题完全不同。MCP 的价值在于让模型能调用你指定的外部工具，难点在接入和授权；Skills 的价值在于让模型以你期望的方式完成任务，难点在流程设计与指令表达。

至于它和普通提示词模板的区别，就更容易被忽略了。很多人把一段写好的提示词存成模板文件，用的时候复制粘贴给模型，这其实只是“一次性的输入优化”。Skill 则是一个自包含的、可被模型自动识别的模块：它有明确的触发条件（通过描述匹配任务），有结构化的指令正文，还能携带脚本、模板、参考资源文件。模型不仅会在用户显式要求时调用它，还会在任务特征匹配时主动加载它。

我整理了一张对比表，方便大家理解几个概念各自的侧重：

需要注意的是，几者并不互斥，实际使用中经常叠加。我做过一个“数据库迁移脚本检查”的 Skill，里面既要求模型调用 MCP 暴露的数据库连接工具去验证索引，又用模板规定了最终报告的格式，两边配合效果很好。

2.3 从“一次正确”到“稳定可复现”的关键跳跃

想让模型“一次正确”不难，难的是让它第一百次仍然稳定。Agent Skills 解决的核心问题，就是把个人或团队的隐性经验显性化、把零散指令模块化，从而让模型的表现从“看发挥”变成“看标准”。

这个定位决定了你设计 Skill 时的心态：你不是在写一段更有条理的提示词，你是在为某类任务建立一个可维护的执行标准。每一条指令都可能被模型反复咀嚼，每一个附带文件都可能被它在不同上下文里反复引用，所以它值得你用写生产代码的态度对待。

3. 模块化组件的结构设计——从 SKILL.md 到附属资源

3.1 最小目录骨架

一个 Skill 在文件系统层面是一个目录，目录里最关键的文件是SKILL.md。没有这个文件，整个目录就不能被识别为 Skill。除了入口文件外，一个完整的 Skill 往往还包含附属资源目录，常见结构是：

my-skill/ ├── SKILL.md ├── scripts/ │ └── check.py ├── resources/ │ └── example-report.md └── templates/ └── report-template.md

SKILL.md是入口，负责声明技能的身份和执行指令。scripts/放可执行脚本，用于模型需要“动手算、动手查”才能完成任务的场景。resources/放参考材料，比如样例代码、规范文档全文。templates/放输出模板，当任务的最终产出物格式固定时，模板能显著提升产出质量。

这种设计其实很像一个开源 npm 包的结构：入口文件负责导出接口，附属目录按职责划分，整个包可以整体被复制、分发、版本化。

3.2 frontmatter 里的学问：description 决定触发生命线

SKILL.md的头部通常是一段 YAML 格式的 frontmatter，里面至少包含name和description两个字段。name好办，起一个简洁明确的名字就行。真正的关键在于description的写法，因为它决定了模型什么时候会主动加载这个 Skill。

我踩过一个很典型的坑。第一次写 Skill 时，我在description里写“用于代码审查”，结果它在用户问代码风格建议、架构方案对比时都被触发了，表现得很突兀。原因是我把描述写得太宽泛，模型把一堆带“代码”字样的任务都关联了过来。

后来我总结出一个有效写法：描述里必须写清楚触发场景、任务目标、输入要求、输出要求四个要素。比如下面是“生成单元测试 Skill”的描述段，基本可以作为模板参考：

--- name: generate-unit-tests description: 当用户要求为某个函数、类或模块编写单元测试，或希望补充现有测试集覆盖率时使用。输入需要包含被测代码的文件路径或代码片段；输出生成 pytest/unittest 风格的测试文件，覆盖正常路径、边界条件和主要异常分支，并附简要覆盖说明。 ---

这段描述里没有一句废话：场景限定在“要求编写单元测试”，输入明确是“文件路径或代码片段”，输出明确是“pytest/unittest 风格测试文件”加上覆盖要求。模型精准匹配的概率就大大提高了。

3.3 指令正文的组织方式

SKILL.md的正文部分是真正指导模型行动的指令，组织方式直接决定执行质量。我的经验是把正文分成几个明确的部分：执行目标、执行步骤、分支处理、禁止事项。

执行目标要让模型明确知道“做完之后算完成”，比如“生成测试文件并确保覆盖率达到 80% 以上”。执行步骤按顺序编号，从解析输入到生成输出一步步来，尽量减少跳步。分支处理要覆盖常见的例外情况，比如被测代码依赖外部服务时该 mock 什么、找不到被测代码时该问什么。禁止事项则用否定句明确边界，例如“禁止生成依赖真实数据库连接的测试”“不要修改被测代码的源文件”。

一个关键技巧是，指令正文要用“祈使句 + 简洁理由”的结构。不要只写“解析输入参数”，可以写成“解析输入参数，提取被测函数的名称与参数列表，因为后续步骤需要基于这些信息生成对应测试骨架”。模型对带理由的指令执行得更稳定，这有点类似人在理解流程时，知道了为什么做之后动作会更精准。

3.4 脚本和模板的合理使用边界

在 Skill 里放脚本和模板不是必须的，但合理使用能大幅提升效果。我的判断标准是：如果任务里有“可计算的判断”，就用脚本；如果任务里有“格式固定的产出”，就用模板；如果任务本质是“按经验逐项检查”，就全写在指令正文里。

举个例子。我做一个检查“项目是否符合特定代码风格规范”的 Skill 时，光靠指令很难让模型精确执行所有规则，因为规则里有大量可量化的判断（缩进、行长度、导入顺序）。这种情况下我会写一个check.py脚本，把规则变成可执行的代码，让模型运行脚本并把输出整理成报告。指令正文只需要告诉它“运行 scripts/check.py 对目标目录进行检查，解析输出结果”，模型就能稳定复刻检查标准。

至于模板文件，适合那些产出物格式非常固定的任务。我做过一个“代码审查报告”Skill，templates/report-template.md里预先定义好了一二三级的章节结构，模型生成的报告每次结构都一致，团队阅读起来毫无负担。

4. 一个实际 Skill 从 0 到 1 的实现过程

4.1 选定目标：为什么要做“单元测试生成”

为了不再空谈概念，我用“生成单元测试”这个任务做例子，完整走一遍构建流程。选这个任务有三点考虑：它在后端开发里出现频率极高；它需要固定的流程才能保证覆盖率；它的产出物格式可以标准化。每个团队都可以把这里的思路迁移到自己的高频任务上。

设计 Skill 前，我先问了自己三个问题：这个任务的标准流程是什么？流程里有哪些容易出错的环节？最终产出物应该长什么样？答案分别是：先分析被测代码签名与依赖，再设计测试用例覆盖正常/边界/异常路径，最后生成测试文件并给出覆盖率说明；容易出错的是对依赖的 mock 不完整，以及遗漏异常分支；产出物就是一份 pytest 测试文件加上简要说明。

这三个问题的答案，就是后面所有指令和模板的骨架。

4.2 分步构建 Skill 包

第一步是创建目录并把SKILL.md放进去。第二步是编写 frontmatter，把触发描述写精准。第三步是写正文，分成“输入解析、用例设计、代码生成、自检”四段，每段都写明步骤和目标。

我直接把关键结构给出来，内容做了精简，读者可以根据自己项目调整：

--- name: generate-unit-tests description: 当用户要求为某个函数、类或模块编写单元测试，或希望补充现有测试集覆盖率时使用。输入需要包含被测代码的文件路径或代码片段；输出生成 pytest/unittest 风格的测试文件，覆盖正常路径、边界条件和主要异常分支，并附简要覆盖说明。 --- # 单元测试生成 ## 执行目标 生成与项目现有测试风格一致、可以独立运行的单元测试文件。 ## 分析被测代码 1. 找到被测代码的函数或类定义，提取全部公开方法签名与参数列表。 2. 识别被测代码的外部依赖，列出必须 mock 的服务与调用点。 3. 记录被测代码涉及的核心业务规则，作为用例断言的依据。 ## 设计测试用例 1. 对每个正常路径设计至少一个正向用例，断言返回值符合业务逻辑预期。 2. 对每个可能的分支条件设计边界用例，覆盖类型边界、数值边界、空值场景。 3. 对异常场景设计负向用例，验证错误抛出或降级行为符合预期。 4. 对包含外部依赖的调用点，使用 mock 隔离，保证测试不依赖真实环境。 ## 生成测试文件 1. 将测试文件保存到约定目录下，文件名以 `test_` 开头并对应被测模块名称。 2. 保持导入顺序与分组、命名风格与项目现有测试文件一致。 3. 为每个测试函数编写清晰命名，使用 given_when_then 格式，例如 `test_should_return_error_when_input_is_null`。 ## 自检 1. 回读生成的测试文件，确认没有引用未定义变量。 2. 再次排查是否遗漏了异常分支与边界条件。 3. 输出覆盖率预估说明，指出当前用例覆盖到哪些分支、哪些分支因环境限制未覆盖。 ## 禁止事项 - 禁止修改被测代码的源文件。 - 禁止生成依赖真实网络连接或数据库连接的测试。 - 禁止为了覆盖率而编写只调用不断言的空测试函数。

写完后，我还会在templates/里放一个简单的测试文件模板，让模型在输出结构上少一些自由发挥。如果 Step 4 希望效果更硬核，也可以再加一个scripts/coverage_hint.py，用来大致估算覆盖情况，不过第一版可以不做。

4.3 在 Claude Code 中验证与迭代

Skill 目录就位后，下一步是验证它真的能被识别和触发。我通常的做法是开一个新会话，先不提 Skill 的存在，而是直接说一句自然语言任务，例如“帮我给src/utils/validation.py里的validate_email函数写一份单元测试，尽量覆盖边界条件”。然后观察 Claude Code 的输出是否匹配 Skill 里定义的流程。

如果它完全没有触发，大概率是description里的关键词与用户表达不匹配。我会调整描述，把“单元测试”“用例覆盖”“pytest”“unittest”“补测试”这类高频近义词都纳入。如果它触发了，但产出不稳定，我会检查指令正文是否有歧义，并补齐分支处理细节。

这个验证流程看起来朴素，但非常有效，本质就是测试驱动开发。每一个 Skill 至少过三遍到五遍不同表述的触发测试，我才会把它放进团队共享库。

4.4 实测中遇到的真实问题：描述过宽与路径引用

这里说两个我在调试过程中撞上的实际问题，希望能帮你少走弯路。

第一个问题就是描述过宽。我最初一版 Skills 的 description 写的是“用于单元测试相关任务”，结果在很多不相关的场景都被触发，包括代码重构、性能优化、接口设计讨论。原因是“测试”这个词在开发语境里无处不在，模型把大量含相关性但实质不符的任务都匹配了过来。修复方式就是我把 description 改成了上面示例里的写法，加上了“输入是被测代码路径或代码片段”和“输出是测试文件”这两个强约束，触发精准度立刻上来了。

第二个问题是路径引用。我的 Skill 里有一行“参考模板文件位于 templates/unit_test_template.txt”，但实际执行时模型会结合自己的当前工作目录解析路径，如果工作目录不是 Skill 包所在位置，就找不到文件。这个问题困扰了我一阵子。最后的解决办法是，在指令正文里写明“模板文件路径与 SKILL.md 位于同一目录下，请先通过 SKILL.md 所在路径推算 templates 目录的绝对路径”，同时把模板内容的关键片段直接摘录进正文作为兜底。

这类问题的本质是：Skill 的执行者是模型，它并不天然知道文件系统布局和包结构的关系，必须在指令里明确教它怎么做路径推导。

5. 把 Skill 当作团队资产运营——后续维护与踩坑清单

5.1 版本化：Skill 也要进 Git、也要写 ChangeLog

Skill 不是写一次就完事的静态文档，它会随团队规范的演进持续变化。测试框架升级、代码风格调整、新工具引入，都会让旧版 Skill 逐步失效。我强烈建议把整个 Skill 目录放入独立仓库或仓库内独立目录，并遵循版本管理规范。

每一次调整都写清楚变更记录，尤其是description的变化和指令正文的删改。不要低估这个动作的价值：当你发现同一个 Skill 在几周内触发行为不一致时，只有版本历史能帮你找出是哪个改动影响了模型行为。

5.2 粒度控制：小而专优于大而全

刚开始做 Skill 时，我总想着一个包解决一类大问题，比如做一个“代码质量提升”大而全的 Skill，试图把审查、重构、补测试全塞进去。实测效果非常差：模型给了它一个用户提问，不知道该调取哪部分指令，经常只执行其中一段就草草收尾。

后来我把大 Skill 拆成code-review、generate-unit-tests、refactor-legacy-code三个独立 Skill，每个只负责一个职责，触发准确性和执行完成度都显着提高。Skill 的粒度应该控制在“一两次交互能完成的任务”级别，这跟函数的单一职责原则异曲同工。

5.3 重叠与冲突：多个 Skill 的触发优先级问题

当 Skill 数量多起来后，会出现一个隐蔽问题：多个 Skill 的 description 在语义上重叠，可能同时被触发。我遇到过的具体场景是“代码审查 Skill”和“安全审计 Skill”同时匹配了一条要求“帮我看看这段登录代码有没有漏洞”的任务，结果两套流程都被激活，模型的行为变得不可预测。

我的处理思路是：第一，尽量在写 description 时把场景边界说得尽可能窄，用“必要时才触发”的句式把使用范围圈住；第二，在相互关联的 Skill 的正文头部加一个说明，明确“如果本任务同时涉及安全审计，请以安全审计 Skill 的流程为准”；第三，如果冲突频繁出现，就考虑合并或者进一步拆分。这个优先级问题没有完美的自动解法，靠指令引导是最务实的路径。

5.4 高频踩坑清单

到最后，我把这一路实操里反复遇到的坑汇总成一张表，希望你能避开：

每一条我都真实趟过，写出来才发现还挺整齐，可见这类问题确实有共性。抄这份表的时候记得对着自己的场景改几笔，不用全盘照搬。

5.5 关于是否共享与团队使用的一点提示

最后想多说一句。如果团队要统一使用一批 Skill，比技术问题更难的是内容共识。我见过两个同事各写一套“代码审查 Skill”，细节分歧能吵上半天。实用的做法是找一个高频、低争议的任务先做试点，比如“变更日志生成”或“接口文档规范检查”，跑通后团队建立了对 Skill 的信心，再逐步扩展到更有争议的领域。

单个 Skills 的构建并不复杂，难的是持续维护、边界管理和团队内的共识。从一个小而准的技能开始，比一开始就搭建庞大体系更可靠。

如果你也想动手，建议今天就从自己最烦的那类重复性任务入手，把流程写进SKILL.md，跑通一次，你会立刻感受到“让模型按你的方法做事”和“让模型自由发挥”之间的差别。