企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底是什么，为什么突然火了

最近半年，不管是在技术社区、开发者群聊，还是各种工具的使用讨论里，“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到，可能会以为它指的是某种通用能力，但在当前的技术语境下，它其实指向一个非常具体的东西：围绕 AI 编程助手（如 Claude Code、Codex 等）构建的可复用能力模块。你可以把它理解成给 AI 助手安装的“技能包”——装上之后，AI 就能按照预设的流程、规范和知识去完成特定任务，而不是每次都要你从头解释一遍。

我最早接触这个概念是在折腾 Claude Code 的时候。当时我一直在想一个问题：每次让 AI 帮我写代码、做代码审查、生成文档，都要重复交代一堆背景信息和格式要求，效率很低。后来发现社区里已经有人在用 skills 的方式把这些重复性的指令封装起来，做成一个个独立的模块，需要的时候直接调用就行。这个思路一下子就打动了我，因为它解决的不是“AI 能不能做”的问题，而是“AI 能不能稳定、可预期地做好”的问题。

skills 的核心价值在于把隐性的经验显性化。比如你团队里有一个资深工程师，他做代码审查有一套自己的检查清单和判断标准，这些东西以前只存在于他的脑子里。现在你可以把它写成一个 skill，让 AI 按照同样的标准去执行。这样一来，不管是新人还是老手，调用这个 skill 得到的输出质量都是一致的。对于前端开发、后端开发、测试、文档撰写这些场景，skills 都能派上用场。

这篇文章适合几类人看：一是已经在用 Claude Code 或 Codex 但还没接触过 skills 的开发者；二是想了解如何把团队经验沉淀成可复用资产的 tech lead；三是对 AI 辅助编程感兴趣、想知道怎么让 AI 更“听话”的任何人。我会从设计思路、核心细节、实操过程、常见问题几个维度展开，尽量把我知道的、踩过的坑都讲清楚。

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

2.1 为什么需要 skills：从“每次解释”到“一次定义”

在没有 skills 之前，我用 Claude Code 的典型流程是这样的：打开终端，输入一段很长的 prompt，里面包含项目背景、代码规范、输出格式要求，然后等它生成结果。如果结果不满意，再补充说明，再生成。这个过程的问题很明显——重复劳动太多。每次做类似的任务，都要把差不多的指令重新写一遍。而且 prompt 越长，AI 越容易遗漏其中的某些要求。

skills 的出现改变了这个局面。它的基本思路是：把一类任务的定义、流程、约束条件、输出格式全部写在一个独立的文件里，AI 在执行任务时会自动加载这个文件的内容，按照里面的规定来工作。这就像给 AI 发了一本操作手册，而不是每次口头交代。从工程角度看，这是把“提示词工程”升级成了“技能工程”。

我自己的体会是，skills 最大的好处不是让 AI 变聪明了，而是让 AI 变稳定了。以前同样的 prompt 跑两次可能得到风格不同的结果，现在有了 skill 的约束，输出的结构、语气、详细程度都趋于一致。对于需要批量处理的任务，这种稳定性比单次输出的质量更重要。

2.2 skills 的组成结构：一个 skill 里到底有什么

一个典型的 skill 通常包含以下几个部分。我用一个“代码审查 skill”作为例子来说明：

• 元信息：skill 的名称、描述、适用场景。这部分告诉 AI 什么时候该用这个 skill。比如名称叫code-review，描述写“对指定代码文件进行审查，检查潜在 bug、性能问题和风格违规”。
• 触发条件：什么情况下激活这个 skill。可以是用户显式调用，也可以是根据任务类型自动匹配。
• 执行步骤：具体的操作流程。比如第一步读取文件内容，第二步逐行分析，第三步按照严重程度分类问题，第四步输出报告。
• 约束规则：必须遵守的硬性规定。比如“不得修改原始代码”、“必须引用具体行号”、“每个问题都要给出修复建议”。
• 输出模板：最终结果的格式。可以是 Markdown 表格、JSON、纯文本列表等。

这五个部分组合起来，就形成了一个完整的 skill。你可以把它想象成一个函数：输入是代码文件，输出是审查报告，中间的逻辑全部封装在 skill 内部。调用者不需要知道内部怎么实现的，只需要知道它能做什么、怎么用。

2.3 不同工具对 skills 的支持方式

目前 skills 这个概念在不同的 AI 编程工具里有不同的实现方式。Claude Code 的 skills 通常以独立文件的形式存在，放在项目的特定目录下，AI 在执行任务时会自动扫描并加载。Codex 的 skills 则更多依赖于配置文件和插件机制，需要通过特定的命令来注册和调用。

我两个工具都试过，感受是：Claude Code 的 skills 更偏向“提示词封装”，适合处理需要灵活判断的任务，比如代码审查、文档生成、重构建议。Codex 的 skills 更偏向“工具集成”，适合处理需要调用外部命令或 API 的任务，比如运行测试、部署、数据抓取。两者不是互斥的，实际项目中可以搭配使用。

还有一个趋势值得注意：社区里已经有人在尝试把 skills 标准化，做成可以跨工具复用的格式。虽然目前还没有统一的标准，但这个方向是明确的。对于开发者来说，这意味着你写的一个 skill，未来可能不需要修改就能在多个工具里运行。

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

3.1 写一个好 skill 的关键：边界清晰、步骤具体

我见过很多写得不好的 skill，最常见的问题是边界模糊。比如一个 skill 的描述写“帮助处理代码相关的问题”，这就太宽泛了。AI 看到这样的描述，根本不知道什么时候该用它，也不知道用的时候该做什么。好的 skill 应该像一份清晰的工作说明书，让人一看就知道：这个 skill 负责什么、不负责什么、输入是什么、输出是什么。

具体来说，写 skill 的时候要注意以下几点：

• 任务范围要窄：一个 skill 只做一件事。不要试图写一个“万能 skill”来处理所有代码问题。宁可写十个专用 skill，也不要写一个什么都沾一点但什么都不精的 skill。
• 步骤要可执行：每一步都要是具体的动作，而不是抽象的描述。比如“分析代码质量”就不够具体，“检查是否存在未处理的异常、硬编码的密钥、超过 50 行的函数”就具体得多。
• 约束要明确：哪些事绝对不能做，要写清楚。比如“不得修改原始文件”、“不得删除任何代码”、“必须在输出中包含行号”。
• 输出格式要固定：最好给出一个模板或示例，让 AI 知道最终结果应该长什么样。

我自己的经验是，写 skill 的过程其实就是把隐性知识显性化的过程。你在写的时候会发现，很多你以为是“常识”的东西，其实需要明确写出来 AI 才能理解。这反过来也会帮助你梳理自己的思路。

3.2 参数与配置：让 skill 适应不同场景

一个 skill 写好后，往往需要在不同的项目、不同的场景下使用。这时候就需要一些可配置的参数。比如一个代码审查 skill，可能需要配置：

这些参数让同一个 skill 可以适应不同的使用场景。比如在 CI 流水线里跑的时候，可以把severity_threshold设为high，只关注严重问题；在本地开发时，可以设为low，把所有潜在问题都列出来。

配置参数的方式因工具而异。Claude Code 通常是在调用 skill 时通过自然语言指定，比如“用 code-review skill 审查这个文件，只报告 high 级别的问题”。Codex 则可能需要在配置文件里预先设定，或者通过命令行参数传入。

3.3 注意事项：这些坑我替你踩过了

在写和使用 skills 的过程中，我踩过不少坑，这里挑几个最有代表性的说一下。

注意：skill 的描述不要写得太“聪明”。有些人喜欢在描述里写“智能分析代码质量”，但“智能”这个词对 AI 来说没有任何指导意义。要写具体的检查项和判断标准。

第一个坑是过度依赖 skill 的自动触发。有些工具支持根据任务类型自动匹配 skill，但自动匹配的准确率并不总是很高。我的建议是，在关键任务上还是显式调用 skill，不要完全依赖自动匹配。比如你可以说“使用 code-review skill 来审查这个 PR”，而不是指望 AI 自己判断该不该用这个 skill。

第二个坑是skill 文件太长。我一开始写 skill 的时候，恨不得把所有知道的东西都塞进去，结果文件变得非常长，AI 加载后反而抓不住重点。后来我学乖了，一个 skill 文件控制在 200 行以内，只保留最核心的规则和步骤。如果内容确实多，就拆成多个 skill，通过组合来使用。

第三个坑是忽略版本管理。skills 是会迭代的，今天写的规则明天可能就不适用了。如果不做版本管理，很容易出现“同一个 skill 在不同时间跑出不同结果”的情况。我的做法是把 skill 文件纳入 Git 管理，每次修改都提交，并在文件头部记录版本号和修改日期。

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

4.1 从零开始创建一个代码审查 skill

下面我以创建一个代码审查 skill 为例，完整走一遍流程。这个 skill 的目标是：对指定的代码文件进行审查，找出潜在问题，并按照严重程度分类输出。

第一步：确定 skill 的存放位置。不同的工具对 skill 文件的存放位置有不同的约定。Claude Code 通常放在项目根目录的.claude/skills/目录下，Codex 则可能放在.codex/skills/或通过配置文件指定路径。我一般会在项目根目录建一个skills/文件夹，然后在工具配置里指向这个目录。

第二步：编写 skill 文件。文件名我习惯用code-review.md，内容如下：

--- name: code-review description: 对指定代码文件进行审查，检查潜在 bug、性能问题和风格违规 version: 1.2.0 --- # 代码审查 Skill ## 触发条件 当用户要求审查代码、检查代码质量、或提到 code review 时激活。 ## 执行步骤 1. 读取用户指定的代码文件内容。 2. 逐行分析，检查以下类别的问题： - 潜在 bug：未处理的异常、空指针引用、数组越界、资源未释放 - 性能问题：不必要的循环嵌套、重复计算、未使用索引 - 风格违规：命名不规范、函数过长、缺少注释 3. 对每个问题标注严重程度：high / medium / low 4. 按照严重程度从高到低排序输出。 ## 约束规则 - 不得修改原始代码文件。 - 每个问题必须引用具体行号。 - 必须给出修复建议。 - 如果文件超过 500 行，只审查前 500 行并说明。 ## 输出格式 | 行号 | 严重程度 | 问题描述 | 修复建议 | |------|----------|----------|----------| | 12 | high | 未处理异常 | 添加 try-catch |

第三步：测试 skill。写好后，我会用一个已知有问题的代码文件来测试。比如写一个故意包含空指针引用和硬编码密钥的 Python 文件，然后调用这个 skill，看它能不能准确识别出这些问题。如果识别不全或者误报太多，就回去调整检查项和判断标准。

第四步：迭代优化。测试通过后，在实际项目中使用一段时间，收集反馈。比如发现某类问题经常被漏掉，就在检查项里加上；发现某类误报太多，就调整判断条件。我一般每两周回顾一次 skill 的使用情况，做一次小迭代。

4.2 在 Claude Code 中调用 skill 的实际操作

在 Claude Code 中调用 skill 有两种方式。一种是显式调用，直接在对话里说“使用 code-review skill 审查 src/main.py”。另一种是隐式触发，当你的请求和 skill 的描述匹配时，Claude Code 会自动加载对应的 skill。

我实测下来，显式调用的成功率更高。隐式触发有时候会漏掉，尤其是当你的请求表述和 skill 描述不完全匹配的时候。所以对于重要任务，我建议还是显式调用。

调用之后，Claude Code 会读取 skill 文件的内容，按照里面的步骤执行。你可以在输出中看到它是否引用了 skill 的规则。如果发现它没有按照 skill 的要求来做，可以在对话里提醒它“请严格按照 code-review skill 的规则输出”。

还有一个技巧是组合调用多个 skill。比如你可以先说“使用 code-review skill 审查这个文件”，等它输出结果后，再说“使用 fix-suggestion skill 为每个 high 级别问题生成修复代码”。这样把审查和修复分开，每一步的输出都更可控。

4.3 在 Codex 中配置和使用 skill

Codex 的 skill 机制和 Claude Code 略有不同。Codex 更倾向于把 skill 作为插件的一部分来管理。你需要先在配置文件中注册 skill，然后通过命令来调用。

一个典型的 Codex skill 配置可能长这样：

{ "skills": [ { "name": "code-review", "path": "./skills/code-review.md", "auto_load": false, "triggers": ["review", "check code"] } ] }

配置好后，在 Codex 的对话中使用/skill code-review来调用。auto_load设为false表示不自动加载，需要手动调用。如果你希望 Codex 在检测到相关请求时自动使用这个 skill，可以设为true。

我自己的习惯是，对于审查类、生成类这种需要稳定输出的 skill，设为手动调用；对于格式化、简单检查这种低风险的 skill，设为自动加载。这样既能保证关键任务的输出质量，又能减少日常操作的繁琐程度。

4.4 一个完整的实操案例：用 skill 审查一个真实项目

前段时间我接手了一个 Python 项目，代码量不大，大概 2000 行左右，但风格比较混乱，而且有一些潜在的 bug。我用自己写的 code-review skill 做了一次全面审查。

具体操作流程是这样的：首先把项目克隆到本地，然后在 Claude Code 里逐个文件调用 skill。对于每个文件，我会说“使用 code-review skill 审查 path/to/file.py，severity_threshold 设为 medium”。Claude Code 会读取文件，按照 skill 的规则分析，然后输出一个表格。

审查结果让我有点意外——它找出了 17 个问题，其中 3 个 high 级别。最严重的一个是在一个循环里反复打开数据库连接，没有复用，这在数据量大的时候会导致性能急剧下降。还有一个是异常处理里直接pass，把错误吞掉了，导致出问题时很难排查。这些问题我自己看代码的时候都没注意到，因为代码逻辑本身是对的，只是写法有问题。

审查完之后，我把所有 high 和 medium 级别的问题整理成任务列表，逐个修复。修复完再跑一次 skill，确认问题已经解决。整个过程大概花了两个小时，比我手动审查快了很多，而且覆盖得更全面。

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

5.1 skill 不生效或效果不好怎么办

这是最常见的问题。你写了一个 skill，调用之后发现 AI 的输出和没调用时差不多，或者没有按照 skill 的规则来。可能的原因和排查方法如下：

我遇到最多的情况是描述太模糊。比如我写“检查代码中的安全问题”，AI 就不知道具体要检查什么。后来改成“检查是否存在硬编码的密码、API 密钥、数据库连接字符串”，效果就好多了。所以写 skill 的时候，一定要假设 AI 对你的领域一无所知，把所有需要它知道的东西都写出来。

5.2 多个 skill 冲突或互相干扰

当你同时使用多个 skill 时，可能会出现冲突。比如一个 skill 要求输出 Markdown 表格，另一个要求输出 JSON，AI 就不知道该听谁的。还有一种情况是两个 skill 的触发条件重叠，导致 AI 不知道该用哪个。

解决这个问题的办法是明确优先级。你可以在调用时指定“优先使用 A skill，如果 A 不适用再用 B”。或者在 skill 文件里写明“本 skill 优先级高于其他 skill”。另外，尽量避免让两个 skill 的触发条件重叠。如果确实需要同时使用多个 skill，可以考虑把它们合并成一个复合 skill，在内部按顺序执行。

我自己的做法是，把 skill 分成两类：基础 skill和扩展 skill。基础 skill 定义通用的规则和格式，扩展 skill 在基础 skill 之上添加特定领域的逻辑。调用时先加载基础 skill，再加载扩展 skill，这样就不会冲突了。

5.3 skill 的维护和更新策略

skills 不是写完就一劳永逸的。随着项目演进、工具升级、团队规范变化，skill 也需要更新。我见过一些团队，一开始兴致勃勃地写了很多 skill，但后来没人维护，慢慢就失效了。

我的维护策略是：

• 定期回顾：每个月花半小时回顾一下正在使用的 skill，看看有没有需要更新的地方。
• 版本记录：每个 skill 文件头部记录版本号和修改日期，方便追踪变化。
• 变更通知：如果修改了某个 skill 的核心规则，通知所有使用这个 skill 的人。
• 废弃标记：不再使用的 skill 不要直接删除，先标记为 deprecated，观察一段时间后再清理。

还有一个经验是，不要过度设计。我一开始写 skill 的时候，总想着把所有可能的情况都覆盖到，结果 skill 变得非常复杂，维护成本很高。后来我学乖了，只覆盖 80% 的常见情况，剩下的 20% 特殊情况让 AI 灵活处理。这样 skill 更简洁，也更容易维护。

5.4 关于 skills 的几个常见误解

最后说几个我经常听到的误解。第一个误解是“skills 可以替代人”。实际上 skills 只是把人的经验封装起来，让 AI 按照这个经验去执行。它不能创造新的经验，也不能处理 skill 里没有定义的情况。所以 skills 是辅助工具，不是替代方案。

第二个误解是“skill 写得越多越好”。我前面说过，skill 要窄而精，不要宽而泛。十个专用 skill 比一个万能 skill 更有用。而且 skill 太多也会增加维护负担，还会让 AI 在匹配时产生困惑。

第三个误解是“skills 只适合大团队”。其实个人开发者也可以用 skills 来提升效率。比如你可以写一个 skill 来规范自己的代码风格，或者写一个 skill 来生成项目文档。只要你有重复性的任务，就可以考虑用 skill 来封装。

6. 我个人的一些实操心得

写了这么多 skill，用了这么久，我最大的体会是：skill 的质量取决于你对任务的理解深度。如果你自己对一个任务的理解就是模糊的，写出来的 skill 也一定是模糊的。所以写 skill 的过程，其实也是逼着自己把问题想清楚的过程。

另外，不要追求一次写出完美的 skill。我最早的几个 skill 现在回头看都很粗糙，但正是通过不断使用和迭代，才慢慢变得好用。先写一个能用的版本，然后在实践中改进，比一开始就追求完美要有效得多。

还有一个技巧是多看别人写的 skill。社区里有很多开源的 skill 可以参考，看看别人是怎么定义任务、怎么组织步骤、怎么设计输出的。即使领域不同，思路也是可以借鉴的。我很多灵感都是从别人的 skill 里来的。

最后，如果你刚开始接触 skills，建议从最简单的任务开始。比如写一个“生成 commit message”的 skill，或者“格式化 JSON”的 skill。这些任务简单、边界清晰，容易写出效果。等熟悉了 skill 的写法之后，再尝试更复杂的任务。