企业官网建设流程全解析

1. 从零理解 Skill：它到底解决了什么问题

很多人第一次听到 Skill 这个词，脑子里浮现的是游戏里的技能树，或者是某种插件系统。但在 Claude Code 和 Codex 这类 AI 编程助手的语境下，Skill 的含义要具体得多——它是一套用 Markdown 写的、可复用的指令集，用来告诉 AI 在特定场景下应该怎么做。

你可以把它理解成给 AI 写的一份“岗位操作手册”。比如你经常需要让 AI 帮你做代码审查，每次都要重复输入“请检查命名规范、检查边界条件、检查错误处理、检查性能问题……”这些要求。写一次两次还行，写十次二十次就是纯粹的浪费时间。Skill 的作用就是把这套要求固化成一个文件，下次直接调用就行。

1.1 Skill 和 Agent 的区别到底在哪

这是被问得最多的问题之一。我刚开始接触的时候也混淆过，后来用多了才理清楚。

Agent 是一个完整的执行单元，它有自己的人设、工具集、决策逻辑，能独立完成一个复杂任务。你可以把 Agent 想象成一个员工——你给他一个目标，他自己想办法完成。

Skill 则更像是一份 SOP（标准作业流程）。它不独立执行任务，而是挂载在某个 Agent 或对话上下文中，当触发条件满足时，AI 会按照 Skill 里定义的步骤和规则来行动。Skill 是“怎么做”的知识，Agent 是“谁来做”的主体。

打个比方：Agent 是厨师，Skill 是菜谱。你可以让同一个厨师做川菜、做粤菜、做甜点，靠的就是切换不同的菜谱。Claude Code 本身就是一个 Agent，而 Skill 是你喂给它的菜谱。

这个区别在实际使用中非常关键。如果你需要的是一个能自主决策、多步骤执行的系统，那应该关注 Agent 的配置。如果你需要的是让 AI 在特定场景下遵循特定规范，那 Skill 就是正确的工具。

1.2 为什么 Markdown 是 Skill 的最佳载体

几乎所有主流 AI 编程工具的 Skill 系统都选择 Markdown 作为编写格式，这不是偶然的。

Markdown 的核心优势在于：它是纯文本，AI 模型对纯文本的理解能力最强。你写一段 JSON 或 YAML，AI 需要先解析结构再理解语义；你写 Markdown，AI 直接就能理解层级关系和自然语言描述。而且 Markdown 的标题层级天然适合表达“主流程-子步骤-注意事项”这种树状结构。

另一个容易被忽略的点是：Markdown 对人类也友好。你写完一个 Skill，自己回头看得懂，同事看得懂，不需要额外的工具就能阅读和修改。这在团队协作场景下非常重要。

1.3 一个 Skill 文件的基本骨架

一个标准的 SKILL.md 文件通常包含这几个部分：

# Skill 名称 ## 触发条件 描述什么情况下应该使用这个 Skill ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. ... ## 输出格式 描述期望的输出结构 ## 注意事项 - 边界情况处理 - 常见错误规避

这个骨架看起来简单，但实际写起来有很多讲究。触发条件写得太宽泛，AI 会在不该用的时候乱用；写得太窄，又会在该用的时候不触发。执行步骤写得太粗，AI 会自由发挥；写得太细，又失去了灵活性。

2. 环境搭建：Node.js 安装与 Claude Code 部署

Skill 的使用离不开运行环境。目前主流的 AI 编程助手大多基于 Node.js 生态，所以第一步是把 Node.js 装好。

2.1 Node.js 版本选择的坑

网上搜“Node.js 安装教程”能出来一大堆，但很多人不会告诉你版本选择的重要性。

Claude Code 和大多数现代 AI 编程工具要求Node.js 18 及以上版本。我建议直接上 Node.js 20 LTS 或 22 LTS，这两个版本目前兼容性最好。Node.js 18 虽然还能用，但已经进入维护期，部分新包可能不再支持。

如果你在安装过程中遇到类似node.js 18 the requested module 'node:util' does not provide an export named这样的报错，基本可以确定是版本不匹配导致的。解决办法很简单：升级到 Node.js 20 或更高版本。

还有一个常见问题是node.js v24.21.0 is not yet released or is not available这类提示。这通常出现在你用了 nvm 或 fnm 这类版本管理器，但指定的版本号不存在。检查一下官方发布页面，确认版本号拼写正确。

安装步骤本身不复杂：

1. 去 Node.js 官网下载 LTS 版本的安装包
2. Windows 用户直接运行 .msi 安装，macOS 用户可以用 .pkg 或 Homebrew
3. 安装完成后打开终端，运行node -v和npm -v确认版本
4. 如果公司网络需要配置镜像源，运行npm config set registry指向内部源

注意：不要混用多个 Node.js 版本管理器。如果你已经装了 nvm，就不要再装 fnm 或 volta，否则环境变量会打架，出现“明明装了却找不到”的诡异问题。

2.2 Claude Code 的安装方式对比

Claude Code 目前有几种使用形态：命令行版本、桌面版、以及通过 VS Code 插件使用。不同形态的安装方式不同，适用场景也不同。

命令行版本最适合喜欢在终端里工作的开发者。安装命令通常是：

npm install -g @anthropic-ai/claude-code

安装完成后，在项目目录下运行claude就能启动。

VS Code 插件版本适合习惯图形界面的用户。在 VS Code 扩展市场搜索 Claude Code 安装即可。装完之后需要在设置里配置 API Key 或者登录账号。

桌面版则是独立的应用程序，适合不想折腾命令行的用户。不过桌面版的功能更新通常比命令行版慢一些，如果你追求最新特性，还是建议用命令行版。

2.3 安装后的首次配置

装好之后别急着用，先做几件事：

第一，确认 API Key 或登录状态正常。大多数工具首次运行会引导你完成认证。

第二，设置好工作目录。Claude Code 默认会读取当前目录下的文件作为上下文，所以建议在具体项目目录下启动，而不是在用户根目录下启动。

第三，检查 Skill 的存放路径。不同工具对 Skill 文件的存放位置要求不同。Claude Code 通常会在项目根目录下寻找.claude/skills/目录，或者用户配置目录下的 skills 文件夹。具体路径建议查阅对应版本的官方文档，因为不同版本可能有调整。

3. 编写第一个 SKILL.md：从模仿到创造

环境搭好之后，最重要的就是动手写一个自己的 Skill。我的建议是：不要从零开始写，先找一个现成的 Skill 改。

3.1 找到一个好的参考模板

GitHub 上有很多开源的 Skill 集合，覆盖了代码审查、文档生成、测试编写、重构建议等常见场景。找一个和你需求最接近的，下载下来，先跑通，再修改。

比如你想做一个“自动生成单元测试”的 Skill，就找一个测试相关的现成 Skill，看看它是怎么定义触发条件的、怎么描述步骤的、怎么处理边界情况的。然后基于你的具体需求做调整。

这一步的核心目的是建立手感。你看十篇教程，不如自己改一个文件来得实在。

3.2 触发条件的写法技巧

触发条件是 Skill 的入口，写得好不好直接决定了 Skill 能不能在正确的时机被调用。

差的写法：

## 触发条件 当用户需要代码审查时

这种写法太模糊。“需要代码审查”是一个主观判断，AI 不知道什么算“需要”。

好的写法：

## 触发条件 当用户提出以下类型的请求时触发： - 要求检查代码质量 - 要求审查 PR 或 diff - 要求找出代码中的潜在问题 - 提到“review”“审查”“检查”等关键词

这种写法给出了具体的触发场景和关键词，AI 更容易判断。

还有一个技巧是加入“排除条件”。比如：

## 不触发的情况 - 用户只是要求解释代码功能 - 用户要求的是格式化代码而非审查逻辑

排除条件能有效减少误触发。

3.3 执行步骤的粒度控制

执行步骤写多细？这是一个需要反复调试的问题。

太粗的步骤等于没写：

## 执行步骤 1. 阅读代码 2. 找出问题 3. 给出建议

AI 看到这种步骤，基本等于自由发挥。

太细的步骤又会让 Skill 变得僵化：

## 执行步骤 1. 打开文件 2. 读取第 1 行到第 10 行 3. 检查第 1 行是否有分号 ...

这种写法只适用于极其固定的场景，稍微换个项目就废了。

我的经验是：步骤应该描述“做什么”和“为什么做”，而不是“怎么做”的每一个细节。比如：

## 执行步骤 1. 通读目标代码，理解其业务逻辑和上下文 2. 按照以下维度逐一检查： - 命名规范：变量、函数、类名是否清晰表达意图 - 边界条件：空值、越界、并发等情况是否处理 - 错误处理：异常是否被捕获并有意义的处理 - 性能隐患：是否存在不必要的循环、重复计算 3. 对每个发现的问题，给出具体的修改建议和示例代码 4. 按照严重程度对问题排序，优先展示高优先级问题

这种粒度既给了 AI 明确的方向，又保留了根据具体情况灵活处理的空间。

3.4 输出格式的约束

如果你对输出有特定要求，一定要在 Skill 里写清楚。比如你希望输出是表格形式：

## 输出格式 使用 Markdown 表格输出审查结果，包含以下列： | 问题类型 | 严重程度 | 位置 | 问题描述 | 修改建议 |

或者你希望输出是分级的：

## 输出格式 按照以下结构输出： ### 严重问题（必须修改） ### 一般问题（建议修改） ### 优化建议（可选）

不写输出格式的后果就是：每次输出的结构都不一样，你没法做后续的自动化处理。

4. 进阶技巧：让 Skill 真正好用

写完第一个能跑的 Skill 只是起点。真正让 Skill 产生价值的是下面这些进阶技巧。

4.1 用变量和参数让 Skill 可配置

硬编码的 Skill 只能用于一个项目。如果你想让同一个 Skill 在不同项目中复用，就需要引入变量。

比如一个代码审查 Skill，不同项目的审查重点不同。你可以这样设计：

## 配置项 - `focus_areas`: 审查重点，默认为“命名规范,边界条件,错误处理” - `severity_threshold`: 最低报告级别，默认为“一般” - `language`: 目标语言，默认为自动检测

然后在执行步骤中引用这些配置项。这样同一个 Skill 文件，通过修改配置就能适配不同项目。

4.2 Skill 的嵌套与组合

复杂的任务往往需要多个 Skill 配合。比如一个完整的“代码提交前检查”流程可能包含：

1. 代码审查 Skill
2. 单元测试生成 Skill
3. 提交信息生成 Skill

你可以写一个“主 Skill”来编排这些子 Skill 的调用顺序：

## 执行步骤 1. 调用 code-review Skill 检查代码质量 2. 如果审查通过，调用 test-generator Skill 生成缺失的测试 3. 调用 commit-message Skill 生成规范的提交信息 4. 汇总所有结果，输出最终报告

这种组合方式能让你的 Skill 体系变得非常强大。

4.3 版本管理与迭代

Skill 文件应该纳入版本控制。每次修改都提交一次，写清楚改了什么、为什么改。

我自己的习惯是在 Skill 文件头部加一个变更记录：

## 变更记录 - v1.2 (2025-01-15): 增加对 TypeScript 泛型的检查规则 - v1.1 (2025-01-10): 优化触发条件，减少误触发 - v1.0 (2025-01-05): 初始版本

这样做的好处是，当你发现某个 Skill 突然不好用了，可以快速定位到是哪次修改引入的问题。

4.4 调试 Skill 的实用方法

Skill 不生效或者效果不好时，按这个顺序排查：

第一，检查文件路径是否正确。很多工具对 Skill 文件的存放位置有严格要求，放错了目录就不会被加载。

第二，检查 Markdown 语法。特别是标题层级，如果你把##写成了####，AI 可能无法正确解析结构。Markdown 换行也是一个常见坑——有些工具要求段落之间必须有空行，有些则不需要。建议统一使用空行分隔。

第三，检查触发条件是否过于严格。临时把触发条件放宽，看看 Skill 是否能被调用。如果能调用，说明是触发条件的问题；如果不能，说明是文件加载的问题。

第四，查看日志。大多数工具都会输出 Skill 加载和调用的日志，仔细看日志能发现很多线索。

5. 实战场景：Skill 在不同领域的落地案例

Skill 不是只能用于代码审查。任何有固定流程、需要重复执行的任务，都可以用 Skill 来固化。

5.1 数学建模中的 Skill 应用

数学建模比赛的时间压力很大，很多队伍在论文写作和代码实现上浪费了大量时间。用 Skill 可以把这些环节标准化。

比如一个“建模论文摘要生成”Skill：

# 建模论文摘要生成 ## 触发条件 当用户提供了问题描述、模型假设和求解结果，要求生成论文摘要时 ## 执行步骤 1. 提取问题背景，用 2-3 句话概括 2. 说明采用的模型方法及其选择理由 3. 简述求解过程，突出关键步骤 4. 给出主要结论和数值结果 5. 总结模型优缺点和改进方向 ## 输出格式 - 总字数控制在 300-500 字 - 不分段，连续行文 - 避免公式，用文字描述方法

这种 Skill 能保证每次生成的摘要结构一致、要素齐全，不会因为紧张而漏掉关键部分。

5.2 文档工作流中的 Skill 组合

很多人需要把 Markdown 转成 Word 或者把表格转成 Excel。这些操作虽然不复杂，但每次都要重复配置。

一个“Markdown 转 Word”Skill 可以这样写：

# Markdown 转 Word 工作流 ## 触发条件 当用户要求将 Markdown 文档转换为 Word 格式时 ## 执行步骤 1. 检查 Markdown 文件中的图片路径，确保使用相对路径 2. 检查表格语法是否正确，Markdown 表格转 Word 时容易出问题 3. 调用转换工具（如 pandoc）执行转换 4. 验证输出文件，检查图片是否正常显示、表格是否错位 5. 如有问题，输出具体的修复建议 ## 注意事项 - 图片路径不要用绝对路径，否则转换后图片会丢失 - 复杂表格建议先转成 HTML 再转 Word - 数学公式需要额外的转换配置

5.3 内容创作中的 Skill 实践

如果你经常写技术博客或文档，可以做一个“技术文章结构化”Skill：

# 技术文章结构化 ## 触发条件 当用户提供了一篇技术文章的草稿，要求优化结构时 ## 执行步骤 1. 通读全文，识别核心主题和关键论点 2. 检查是否有明确的引言、主体、结论 3. 检查每个段落是否围绕一个中心思想 4. 检查技术术语是否一致 5. 检查代码示例是否完整可运行 6. 给出结构优化建议，按优先级排序 ## 输出格式 ### 整体评价 ### 结构问题 ### 内容问题 ### 语言问题 ### 修改建议

这种 Skill 相当于一个不知疲倦的编辑，每次都能按照同样的标准帮你检查文章。

6. 常见问题与排查手册

在使用 Skill 的过程中，会遇到各种奇怪的问题。这里整理了一些高频问题和排查思路。

6.1 Skill 不生效的排查链路

现象：写了 SKILL.md 文件，但 AI 完全不按 Skill 里的步骤执行。

排查步骤：

第一步，确认文件是否被加载。在对话中直接问 AI：“你现在加载了哪些 Skill？”如果 AI 说没有加载任何 Skill，说明文件路径有问题。

第二步，确认文件格式是否正确。把 SKILL.md 的内容复制出来，检查 Markdown 语法。特别注意标题层级是否连续、代码块是否正确闭合。

第三步，确认触发条件是否匹配。临时把触发条件改成“任何情况下都触发”，测试 Skill 是否能被调用。如果能，说明是触发条件写得太窄。

第四步，检查是否有多个 Skill 冲突。如果你同时加载了多个功能相似的 Skill，AI 可能不知道该用哪个。尝试只保留一个 Skill 进行测试。

6.2 Markdown 语法导致的解析问题

Markdown 看起来简单，但在 Skill 文件中，一些细节会直接影响 AI 的解析结果。

换行问题：在标准 Markdown 中，单个换行不会产生新段落，需要空行才能分段。但有些 AI 工具会把单个换行也当作分段。建议统一使用空行分隔段落，避免歧义。

列表嵌套：嵌套列表的缩进在不同 Markdown 解析器下表现不同。建议嵌套层级不超过三层，且使用一致的缩进（2 个或 4 个空格）。

代码块：代码块必须标注语言类型，否则 AI 可能无法正确识别代码内容。比如用```python而不是```。

表格：Markdown 表格的列对齐方式容易出错。建议在表格前后各加一个空行，避免和正文混在一起。

6.3 性能问题的优化思路

Skill 文件太大会导致加载慢、消耗上下文窗口。优化思路：

• 把不常用的 Skill 拆分成独立文件，按需加载
• 把详细的参考文档放在单独的文件中，Skill 里只保留核心步骤和引用链接
• 定期清理不再使用的 Skill
• 合并功能重叠的 Skill

一个 Skill 文件控制在 200 行以内是比较合理的。超过 500 行就需要考虑拆分了。

6.4 团队协作中的 Skill 管理

团队使用 Skill 时，需要建立一些规范：

• 统一存放路径，比如项目根目录下的.skills/文件夹
• 统一命名规范，比如功能-场景.md的格式
• 建立审查机制，新 Skill 或修改需要至少一人 review
• 维护一个 Skill 索引文件，说明每个 Skill 的用途和负责人

这些规范看起来繁琐，但能避免“这个 Skill 是谁写的”“为什么改了之后不好用了”这类问题。

7. 从能用 to 好用：我的个人经验

写了这么多 Skill，踩过的坑比写过的 Skill 还多。分享几条我觉得最有价值的经验。

第一条：先跑通再优化。不要一开始就追求完美的 Skill 设计。先写一个能用的版本，在实际使用中发现问题，再迭代改进。我见过太多人花了一周设计“完美”的 Skill 架构，结果发现根本用不起来。

第二条：触发条件宁窄勿宽。触发条件写宽了，AI 会在各种不相关的场景下调用 Skill，产生大量噪音。写窄了最多是不触发，手动调用一下就行。所以宁可写窄一点。

第三条：输出格式要固定。如果你需要对 Skill 的输出做后续处理，一定要把输出格式固定下来。用表格就用表格，用 JSON 就用 JSON，不要这次表格下次列表。

第四条：定期回顾和清理。Skill 会越写越多，但很多写完之后就再也没用过。每隔一段时间回顾一下，把没用的删掉，把常用的优化一下。

第五条：不要试图用 Skill 解决所有问题。有些任务就是不适合用 Skill，比如需要大量创造性思考的任务、需要实时交互的任务。Skill 适合的是流程固定、重复性高的任务。认清这个边界，能省很多无用功。

最后说一个我自己的习惯：每次写新 Skill 之前，先问自己一个问题——“这个任务我做过至少三次了吗？”如果没做过三次，说明流程还没稳定，这时候写 Skill 大概率要返工。做过三次以上，流程基本固定了，写出来的 Skill 才真正能用得住。