企业官网建设流程全解析

1. 踩坑总结：为什么前 30 个 Skill 基本是白写的

先把结论放在前面：我前后写了 50 个 Claude Code Skill，但真正留下来、还在日常用的只有 20 个左右。前 30 个里的大部分，要么被我重写了好几遍，要么直接删了。不是那些 Skill 写得不对，而是我一开始对 Skill 这个机制的理解就是错的。

先说 Skill 到底是什么。在 Claude Code 里，Skill 本质上是一组预先定义好的指令包，通常由一个 SKILL.md 文件（也可以带上辅助脚本、模板、示例）组成。它的作用不是替代 Claude 的推理能力，而是给 Claude 提供一套清晰的"这个任务该怎么干"的工作流。你可以把它理解成给一个很聪明但没干过这个活的新人，递上一本带 SOP 的操作手册。

我最早犯的第一个错误，是把 Skill 当成"提示词收藏夹"。那时候我觉得，只要把一些常用的 prompt 写进 SKILL.md，任务来了让 Claude 读一遍，效果应该就差不多。结果实测下来完全不是这么回事。普通的 prompt 只是告诉 Claude"你要做什么"，而一个合格的 Skill 要告诉 Claude"你按什么步骤做、每一步怎么判断、输出什么格式、什么情况下要停下来问人、什么情况下可以直接干"。后者才是 Claude Code 真正吃的那一套东西。

第二个错误，是我把大量具体内容塞进了 SKILL.md。一开始写"代码审查"这个 Skill 的时候，我几乎把团队所有的代码规范、历史问题清单、禁止事项全写进去了。文件洋洋洒洒几千字，Claude 每次加载都要消耗大量上下文窗口，而且规范之间还有冲突，Claude 反而不知道按哪条来。后来我才明白，好的 SKILL.md 应该是"薄"的，它应该是一份指南、一套触发条件、一系列流程节点，而不是一本百科全书。

前 30 个 Skill 里，有一多半就是这两种错误写出来的。真正让我开窍的，是后来重新设计的一个"单元测试生成"Skill。当时我的思路很简单：不要告诉 Claude"你要生成测试"，而是告诉它"拿到任务后，先读源码，列出函数清单，然后逐个函数按 输入构造—边界分析—Mock 依赖—断言设计 四步来，每一步输出一个小标题，最后把所有测试代码合并到一个文件里"。这个 Skill 写得很短，但 Claude 跑出来的效果，比之前那个写了好几千字的版本强了不止一个档次。

从那次以后我就明白了：Skill 的价值不在于"写得多"，而在于"结构对"。下面我把这 50 次迭代里沉淀下来的经验，按设计、写作、调试三条线拆开讲。

2. 设计 Skill 前，先回答三个问题

动手写 SKILL.md 之前，先花十分钟想清楚三件事。这个环节省掉的话，后面大概率要返工。

2.1 这个 Skill 到底解决什么问题

Skill 不是越通用越好，也不是越细分越好。它应该落在一个"刚好"的位置上：任务本身是重复出现的、流程相对稳定的、且 Claude 单独凭默认行为做不好的。

举个例子，我写"数学建模"Skill（热词里有人搜这个，我猜是理工科学生在用），是因为 Claude 默认响应下，它给出的建模步骤经常跳跃，直接从题目跳到微分方程，中间的假设分析、变量定义、量纲检查全被跳过了。Skill 的作用就是把"建模题的完整套路"固化成固定步骤，让 Claude 每次都能按标准流程走一遍。反过来，如果你只是让 Claude"写一段 Python"，那不需要 Skill，它默认就干得很好。

判断的方法很简单：把你要做的事，不带任何 Skill 让 Claude 直接做三遍。如果三遍输出质量都很稳定、都达到预期，那这个任务不需要 Skill；如果三遍输出忽好忽坏，或者每次都漏掉同一个关键环节，那这个任务就值得做一个 Skill。

2.2 Skill 的边界在哪里

一定要想清楚：哪些事交给 Skill 里的指令流程，哪些事留给 Claude 自己临场发挥。

我一开始特别喜欢把"所有可能性"都塞进 Skill 里，比如写文档类 Skill 时，把"如果用户要 PDF 格式就怎么处理，如果用户要 Word 格式就怎么处理"这种分支全部写进去。结果是 SKILL.md 越来越长，Claude 的策略空间反而被压缩了。它花大量精力去匹配各种分支条件，而不是专注在任务本身的质量上。

后来我采用的策略是：Skill 只定义流程骨架和输出规格，具体的内容生成、方案选择、术语处理，全部留给 Claude 自己判断。Skill 负责解决"该走哪条路"，Claude 负责解决"路上该怎么走"，两者配合才是最佳状态。

2.3 用什么粒度来拆任务

一个 Skill 覆盖的任务，如果超出"一次会话能完成的工作量"，基本就该拆成多个 Skill 了。

比如"后端开发"这个标题，如果你做成一个 Skill，那它几乎没意义，因为范围太宽了。但如果你按"新模块脚手架搭建""REST API 设计评审""数据库迁移脚本生成""接口联调自测清单"这几个粒度来分别做 Skill，每个 Skill 的流程就会非常清晰，Claude 的执行质量也会高得多。

这里给一个我实测比较好用的粒度参考：

这个表格不是绝对标准，但它能帮你快速判断自己脑海里的想法是不是过大了。我前 30 个 Skill 里至少有 8 个，就是死在这种"任务粒度太大"上。

3. SKILL.md 的正确写法：结构与内容分配

等你把"做什么、边界、粒度"想明白了，再进入 SKILL.md 的写作环节。这个文件的质量，直接决定了 Claude 的执行效果。

3.1 开头不要写"你是谁"，直接写"你要做什么"

我见过很多 Skill 的开头是这么写的：

"你是一个专业的软件工程师，拥有多年的开发经验，擅长各种编程语言和技术栈……"

这段对 Claude 来说毫无意义。Claude 本身就是大模型，它不需要角色设定，需要的是任务指令。真正有效的开头应该直接说明这个 Skill 在什么场景下触发使用，以及核心目标是什么。

我推荐的开头结构只有两块：触发场景 + 目标陈述。比如我这个"数学建模"Skill 的开头是这样写的：

当用户提出数学建模类题目（通常含"建模""拟合""预测""优化"等关键词）时，使用本 Skill。目标：输出一份完整、符合数学建模竞赛格式的建模报告，涵盖问题分析、假设建立、模型构建、求解验证四大部分。

短短两句话，Claude 一看就知道需要在什么时候启动这个流程、要交付什么结果。不需要任何铺垫。

3.2 主体部分用"步骤 + 判断 + 输出"三段式

SKILL.md 的主体，是整套 Skill 的核心价值所在。我强烈建议用"步骤 + 判断 + 输出"的结构来组织：

• 步骤：明确写出"第一步做什么、第二步做什么"。
• 判断：写出每一步里"什么情况算做完了、什么情况需要提前结束"。
• 输出：写出每一步"最终应该产出什么形态的结果"。

拿"单元测试生成"Skill 举例，它的主体部分是这么组织的：

1. 读取目标源码文件，列出所有导出的函数和类方法（含私有辅助函数）。
2. 对每个函数，先生成"输入参数边界表"，包括：正常值、空值、极端值、类型异常值。
3. 根据边界表逐个写测试用例，每个用例必须包含：测试名称、输入构造、预期输出。
4. 如果一个函数依赖外部 IO 或网络请求，必须先用 mock 隔离，不允许直接访问真实资源。
5. 所有用例写完后，汇总成一个测试文件，并执行一次运行，把所有失败项整理成报告。

这段描述不算长，但 Claude 每次执行都能稳定产出结构一致的测试代码。原因就在于：每一步的输出要求都写清楚了，Claude 知道每一步该交付什么。

3.3 把"陷阱"写进 Skill，而不是把"知识"写进 Skill

前 30 个 Skill 里，我最大的败笔是试图把"知识"写进 Skill。比如写"React 组件开发"Skill 时，我恨不得把 React 的所有 API 文档都塞进去。这完全搞错了方向。

Claude 的训练数据里已经有大量 React 知识，它不需要你再教一遍。"知识"层面的东西，它比你记得还全。Skill 真正要提供的，是"这个任务里常见的坑和应对方式"。

举个例子，"单元测试生成"Skill 里，我最关键的一段不是测试怎么写，而是下面这条：

注意：如果目标函数内部有随机数生成、当前时间读取、外部 API 调用这三类操作，测试用例必须在输入中注入可预测的种子或 mock，否则测试就是不可重复的，失败的用例优先检查是否由不可控因素导致。

这一段对 Claude 来说是真正的增量信息。它知道要 mock 外部依赖，但"优先考虑不可控因素"这一层的判断，是它默认行为里不会主动做的。所以我现在的所有 Skill，都会专门设一个"注意事项"小节，把这类经验写进去，效果比堆知识好得多。

3.4 后置条件和终止条件一定要写

这是 50 个 Skill 里，我后期才意识到的一个关键点。SKILL.md 的主体部分，必须明确写出"做到什么程度算彻底完成"。

比如"文档生成"Skill，如果只写"生成一份用户手册"，Claude 可能写到一半就停了，因为它觉得自己已经写完了。但如果写成"生成一份用户手册，内容需覆盖：产品概述、安装步骤、使用说明、故障排查、FAQ 五个章节，且每个章节都不允许为空"，Claude 就会自我检查一遍再收尾。

终止条件同样重要。我见过的典型情况是：Claude 在分析任务时，如果发现信息不足，它会强行输出一个假设性的结论。对此，我建议在 SKILL.md 里写明一条终止规则：

如果执行过程中发现输入信息不足，无法满足输出要求，请立即停止并列出缺失信息清单，向用户求证，不要自行假设。

这条规则写进去之后，我后来的 Skill 在执行时，遇到模糊需求的次数直线下降。

3.5 用 YAML front matter 做元信息

如果你用过 Claude Code 的 Skill，应该知道它在读取 SKILL.md 的时候，会优先解析文件开头的 YAML 元信息。我的做法是，每个 SKILL.md 顶部都加一段 front matter，内容包括：

• name：Skill 名称，简短可理解。
• description：给 Claude 判断触发条件用的描述，要包含触发关键词和任务目标。
• 可选参数：比如输出格式、语言偏好。

描述这部分特别关键，因为 Claude Code 是把 description 当作 Skill 的"索引"来用的。写得太抽象，Claude 该触发的时候不触发；写得太具体，又会把应用场景锁死。我现在的写法是"场景 + 动作"式：

description: 当用户要求撰写或优化博客文章，且期望输出结构清晰、逻辑严谨、无 AI 痕迹的文本时使用本 Skill。

这种写法既给了触发信号（博客文章、优化文本），又给了目标（结构清晰、无 AI 痕迹），Claude 判断起来非常准确。

4. 实操过程：从零写一个实际能用的 Skill

这一节我完整走一遍流程，从需求到成品，演示一个"代码评审"Skill 是怎么落地的。

4.1 第一步：确定触发场景和交付物

我做这个 Skill 的背景是：团队每次代码合并前都要做 Code Review，但 Claude 默认给出的评审意见往往很泛泛，什么"代码风格良好""建议增加注释"这类车轱辘话，看了等于没看。

于是我把触发场景定为："当用户要求对代码进行评审 / review 时，使用本 Skill。"交付物明确为三份内容：

• 问题清单（按严重程度排序）
• 改进建议（按改动量从小到大排序）
• 一份带修改方案的样例（对排名第一的问题）

这三份交付物写进 front matter 的 description 之后，整个 Skill 的边界一下子清晰了。

4.2 第二步：设计评审流程

评审流程我拆成了五个节点：

1. 通读代码，整理出函数 / 模块调用关系。
2. 按"正确性 — 可读性 — 可维护性 — 性能 — 安全"五个维度逐项检查。
3. 对每个发现的问题，标记严重程度（阻断 / 主要 / 次要）。
4. 对每个阻断和主要问题，给出具体修改方案，不要只描述问题。
5. 汇总输出，要求所有结论必须有代码行号或函数名作为引用依据。

这五个节点的作用，是强制 Claude 按专业评审的标准走，而不是凭直觉给出模糊意见。尤其第四步，是之前 Claude 默认行为里最容易偷懒的地方——它擅长指出问题，但不擅长给方案。这条写进去之后，输出质量明显上了一个台阶。

4.3 第三步：写注意事项和禁忌

SKILL.md 里最不能被省略的，是"不要做什么"这个部分。我这里写的几条，全是实际测试中总结出来的：

禁止输出没有代码依据的泛泛评价，例如"函数逻辑清晰""风格良好"等无引用结论。 禁止直接修改原始代码文件，评审输出应统一放在 review 报告中。 如果评审的代码超过 500 行，优先评估核心路径和公共接口，不要陷入逐行检查。

第一条解决的是"废话评审"问题，第二条解决的是"Claude 擅自改代码"问题，第三条解决的是"上下文被撑爆"问题。每一条都是踩过坑才写下来的。

4.4 第四步：完整 SKILL.md 参考

把上面所有内容组装起来，一个完整可用的 SKILL.md 大概长这样：

--- name: code-review description: 当用户要求对代码进行评审或 review，且期望输出问题清单、改进建议和修改方案时使用本 Skill。 --- # 代码评审 目标：输出一份结构清晰、依据充分的代码评审报告。 ## 执行流程 1. 通读目标代码，绘制函数 / 模块调用关系（用文字说明即可）。 2. 按"正确性 — 可读性 — 可维护性 — 性能 — 安全"五个维度逐项检查。 3. 对每个发现的问题，标记严重程度：阻断 / 主要 / 次要。 4. 对引发该问题的最小代码片段，给出具体修改建议，并说明理由。 5. 汇总输出，格式为：问题描述 / 代码定位 / 严重程度 / 修改方案。 ## 注意事项 禁止输出没有代码依据的泛泛评价，结论必须引用具体行号或函数名。 禁止直接修改原始代码文件，所有改动建议写入 review 报告。 如果代码超过 500 行，优先评估核心路径和公共接口，不要逐行深挖。

这个版本我用过很多次，Claude 的输出质量和稳定性，比我最初写的那个几千字的"代码规范大全"版本好太多。结构短、指令清、边界明，才是 SKILL.md 该有的样子。

4.5 第五步：联调测试并迭代

Skill 写完之后，不要直接投入使用。拿一个标准样例测试三遍，每次关注三个点：

• 触发是否准确：是不是在你说"review 这段代码"时自动启用，而不是你自己手动喊它。
• 流程是否完整：五个节点有没有跳步，输出是不是每次都覆盖全了。
• 注意事项是否生效：有没有出现违规行为（比如改了原文件）。

三遍测试里如果出现同一类问题，优先修 SKILL.md，不要怀疑是 Claude 的问题——绝大多数情况下，是 Skill 的描述不够清楚。

5. 常用工具与配置细节

Skill 的使用效果，不只取决于 SKILL.md 本身，还跟你的环境配置有强关系。这里挑几个高频问题展开讲。

5.1 Skill 文件放哪里

Claude Code 对 Skill 目录的支持是明确的，通常放在项目内的.claude/skills/目录下，每个 Skill 单独一个文件夹，里面放 SKILL.md 以及可选辅助文件。结构大概是这样：

.claude/ └── skills/ ├── code-review/ │ └── SKILL.md ├── blog-writing/ │ └── SKILL.md └── math-modeling/ └── SKILL.md

如果你的多个项目都要用同一套 Skill，可以考虑放在用户级的配置目录里，这样所有项目都能共享。具体路径取决于你的安装方式和操作系统，常见做法是放在 Claude Code 的用户配置目录下的 skills 文件夹中。

5.2 不同客户端的差异

我注意到有人在搜"vscode 配置 claude code"和"claude code 桌面版"。这两个使用场景下，Skill 的加载机制略有差别。

VSCode 插件形态下，Claude Code 会优先读取当前工作区里的.claude/skills/目录，所以项目内共享 Skill 很方便。桌面版则更偏向于读取全局配置目录，如果你的工作习惯是"很多小项目各自独立"，桌面版更省心；如果你是"一个大项目里多个子模块共用 Skill"，VSCode 形态更直观。

有一点需要提醒：无论哪种形态，修改 SKILL.md 之后，最好重启会话或重新加载一次会话元数据，否则 Claude 可能还停留在旧版本的内容上。这个细节特别容易踩，我之前有好几次改完 Skill 没重启，然后反复怀疑是自己写错了，折腾半天才发现是没刷新。

5.3 本地模型和 API 模型的 Skill 兼容性

热词里有人在问"claude code 调用 lmstudio 的本地模型"以及"claude code 接入 deepseek"。如果你用的不是 Claude 官方模型，Skill 依然可用，但效果会有起伏。

我的经验是：Skill 的文件结构和触发机制，在第三方模型上基本是通用的，因为 Claude Code 的平台层会处理这些解析。但 SKILL.md 里那些需要"高级推理"的指令，在参数量较小的本地模型上执行效果会打折扣。比如"推断函数意图并自动补全测试"这种模糊指令，小模型经常完不成；但"按边界表逐项生成测试用例"这种明确指令，小模型完成度反而不错。

所以如果你打算跑本地模型，Skill 的设计就要更"程序化"：步骤要更细、判断标准要更明确、输出格式要更固定。把模糊空间压缩到最小，小模型才能稳定执行。

6. 这 50 次迭代里总结出的关键经验

前 30 个 Skill 白写，后 20 个之所以活下来，核心差异其实就三条，值得单独拎出来讲清楚。

第一，Skill 是流程说明书，不是知识库。知识类的信息，Claude 天生就有；流程类的信息，它默认不会主动按固定顺序执行。写 SKILL.md 的时候，你的职责是把"操作流程"写清楚，而不是把"行业知识"抄进去。一旦方向搞反，文件越长越没用。

第二，边界越清晰，执行越靠谱。包括任务边界、输出边界、终止边界。任务边界决定了这个 Skill 管什么、不管什么；输出边界决定了交付物长什么样；终止边界决定了做到哪一步算完。这三条边界，是判断一个 SKILL.md 是"小学生作文"还是"实操手册"的分水岭。

第三，迭代比创作更重要。没有一个 Skill 是一次写成的，都是通过实际使用、观察 Claude 的输出、反推修改指令，一点点打磨出来的。我保留的 20 个 Skill，平均每个都改了七八轮。别指望一个晚上写出一套完美 Skill，把它当成一个渐进优化的对象，心态会稳很多。

第四条，算是我个人最想强调的一点：少写，多删。我每隔一段时间会做一次"Skill 瘦身"，把不用的、效果差的、跟其他 Skill 功能重叠的全部删掉。删除的效果不是单纯减负，而是让 Claude 在匹配 Skill 时减少歧义。Skill 之间的描述越清晰、越不重叠，Claude 的触发准确率就越高。如果你发现自己写了大量 Skill，但觉得 Claude 越来越"笨"，先别怪模型，去看看你的 Skill 目录是不是已经堆积成一座无人维护的迷宫了。

7. Skill 写作常用模板参考

最后留一套我常用的 SKILL.md 模板。你直接拿它填空，比从零开始写要省不少事：

--- name: 技能名称 description: 当用户请求【触发场景】时使用本 Skill，目标是【交付目标】。 --- # 技能名称 目标：一次性描述清楚这个 Skill 要交付什么。 ## 执行流程 1. 第一步：明确要做的事。 2. 第二步：按什么方式做。 3. 第三步：这一步输出什么。 4. 第四步：检查标准 / 完成判定。 ## 注意事项 - 禁忌事项 1：不要做什么，原因是什么。 - 禁忌事项 2：遇到什么情况要停止。 - 如果信息不足，必须怎么办。 ## 完成条件 输出必须包含哪些要素，缺一不可。

这个模板熟练之后，我的一个 Skill 从想到写完大概 20 分钟。但记住，写完不算完，用三次、改三次，它才真正是你的 Skill。

我自己现在最深的感受是：写 Skill 这个动作本身，逼着我把平时凭感觉做的任务，硬生生拆成了一个个可复制的流程。哪怕不为了 Claude，这套拆解思路用在带新人、做项目管理上，同样值回票价。如果你刚开始写 Skill，别急着冲数量，先挑一个你重复度最高的任务，按上面的框架认真做一个，跑顺了再扩展。50 个的前 30 个我已经替你踩过坑了，希望你能直接绕过去。