企业官网建设流程全解析

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

如果你最近在开发者社区、AI 工具圈或者技术群聊里频繁看到“skills”这个词，不用怀疑，它已经从一个普通英文单词变成了一个具有特定技术含义的专有概念。简单来说，Agent Skills（智能体技能）是一套让 AI 编程助手具备可复用、可组合、可版本管理的能力模块的机制。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张卡定义了一类特定任务的执行逻辑、工具调用方式和上下文约束。

这个概念的爆发和 Claude Code 的普及有直接关系。Claude Code 是 Anthropic 推出的命令行 AI 编程工具，它本身已经能读写文件、执行命令、搜索代码，但面对复杂项目时，光靠通用能力是不够的。于是 Skills 机制应运而生：你可以在项目里放一个SKILL.md文件，告诉 Claude Code 在特定场景下该怎么做、该调用什么工具、该遵循什么规范。这就像给一个新入职的工程师发了一本《项目操作手册》，他不用每次从头摸索。

那为什么 skills 会突然成为热搜词？我观察下来有几个原因。第一，AI 编程工具从“能写代码”进入到了“能按规范写代码”的阶段，通用能力已经不够用了，大家需要定制化。第二，Skills 的门槛足够低，本质上就是写 Markdown 文件，不需要学新语言、不需要编译打包，前端开发者、数据科学家、甚至非技术背景的产品经理都能上手。第三，社区效应，GitHub 上出现了大量开源的 skills 仓库，从数学建模到前端开发、从 STM32 嵌入式到 AI 漫剧生成，各种场景的 skills 层出不穷，形成了一种“技能库”生态。

这篇文章面向的读者很明确：如果你已经在用 Claude Code、Codex、OpenCode 这类 AI 编程工具，但总觉得“它不够懂我的项目”，那 skills 就是你要找的答案。如果你还没开始用这些工具，也没关系，我会从最基础的概念讲起，把 skills 的设计思路、编写方法、安装配置、常见坑点全部拆开讲清楚。全文基于我自己的实操经验和社区常见实践，不堆砌官方文档的套话，只讲能直接抄作业的东西。

2. Skills 的核心设计思路：为什么是 Markdown，而不是代码

2.1 用自然语言定义能力，降低编写门槛

传统上，要给 AI 助手扩展能力，你得写代码、定义函数签名、注册工具调用接口。这套流程对工程师来说不算难，但把大量非核心开发者挡在了门外。Skills 的设计哲学完全不同：它用自然语言描述能力，用 Markdown 组织内容，用文件系统做版本管理。你不需要写一行 Python 或 TypeScript，只需要在SKILL.md里用清晰的结构化文字告诉 AI：“当用户要求做 X 的时候，你应该按 Y 步骤执行，注意 Z 事项。”

这个选择背后有很实际的考量。AI 模型本身已经具备了强大的自然语言理解能力，你用自然语言给它下指令，它完全能听懂。与其费劲定义一套形式化的工具接口，不如直接把领域知识写成文档，让模型自己去理解和执行。这就像你给一个新员工写操作手册，你不会用伪代码写，而是用他能看懂的语言写清楚步骤和注意事项。

当然，这并不意味着 skills 就是随便写写。好的 skills 需要精确的触发条件、清晰的步骤拆解、明确的边界约束和可验证的输出标准。我见过太多人写 skills 时犯的一个错误：写得太泛，比如“帮我优化代码”，这种 skill 等于没写，因为 AI 不知道什么时候该触发、优化到什么程度算完成。正确的做法是写具体场景，比如“当检测到 React 组件中存在未处理的异步状态更新时，按以下步骤重构为 useReducer 模式”。

2.2 文件系统即技能库，天然支持组合与继承

Skills 的另一个巧妙设计是用目录结构来组织技能。一个典型的 skills 目录长这样：

.claude/skills/ frontend-review/ SKILL.md examples/ bad-example.tsx good-example.tsx math-modeling/ SKILL.md templates/ paper-template.md stm32-debug/ SKILL.md reference/ register-map.md

这种结构的好处是显而易见的。首先，技能可以带附件，比如示例代码、模板文件、参考文档，AI 在执行 skill 时可以读取这些附件作为上下文。其次，技能可以嵌套和组合，一个高层 skill 可以引用底层 skill，形成技能树。第三，版本管理天然友好，你把 skills 目录提交到 Git，团队成员拉下来就能用，更新技能就是提交一个 commit。

我自己的项目里就用了这种结构。比如我有一个code-review技能，它下面又引用了security-check和performance-check两个子技能。当 Claude Code 执行代码审查时，它会先跑安全检查和性能检查，再汇总成完整的审查报告。这种组合能力是纯代码方案很难做到的，因为代码方案的组合需要显式调用和参数传递，而 skills 的组合就是文件引用和自然语言描述，灵活得多。

2.3 触发机制：让 AI 知道“什么时候该用这个技能”

Skills 最核心也最容易出问题的地方是触发机制。你写了一个技能，但 AI 怎么知道什么时候该用它？目前主流的做法是在SKILL.md的头部用 YAML frontmatter 定义触发条件，类似这样：

--- name: react-async-refactor description: 当 React 组件中存在未处理的异步状态更新、竞态条件或内存泄漏风险时触发 triggers: - "异步状态" - "race condition" - "useEffect 清理" - "组件卸载后 setState" ---

这里的description和triggers就是给 AI 看的“触发信号”。当用户的请求或代码上下文匹配到这些信号时，AI 就会加载对应的 skill。实测下来，触发条件写得越具体，误触发和漏触发的概率越低。我建议 triggers 里至少包含三类信息：问题特征（如“竞态条件”）、代码模式（如“useEffect 中没有 cleanup”）、用户可能的表述（如“这个组件好像有内存泄漏”）。

还有一个经验：不要在一个 skill 里塞太多触发条件。我见过有人写了一个“万能前端技能”，triggers 列了二十几条，结果 AI 每次都在纠结要不要触发，反而降低了效率。正确的做法是按场景拆分，一个 skill 只解决一类问题，触发条件控制在 3 到 5 条。

3. 手把手写一个可用的 SKILL.md：从零到能跑

3.1 最小可用结构：五段式模板

写SKILL.md不需要复杂的格式，但有几个关键段落是必须的。我总结了一个五段式模板，经过多个项目验证，基本能覆盖大部分场景：

--- name: skill-name description: 一句话说明这个技能解决什么问题 triggers: - "触发词1" - "触发词2" --- ## 适用场景 描述什么情况下应该使用这个技能，什么情况下不应该使用。 ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 第三步做什么 ## 注意事项 - 注意点1 - 注意点2 ## 输出要求 描述执行完成后应该输出什么格式的结果。

这个模板看起来简单，但每一段都有讲究。“适用场景”决定了 AI 的触发边界，“执行步骤”是核心逻辑，“注意事项”是避坑指南，“输出要求”保证结果可验证。我建议新手先从这五段开始写，写熟了再根据具体需求扩展。

3.2 触发条件怎么写才精准：三个实操技巧

触发条件是 skills 的“开关”，写不好就会出现两种情况：要么 AI 该用的时候不用，要么不该用的时候乱用。我踩过的坑包括：触发词太泛（比如只写“优化”），导致 AI 在任何优化场景都触发；触发词太窄（比如写了一个特定函数名），换个项目就失效。

第一个技巧是用“问题特征 + 代码模式”组合触发。比如不要只写“性能问题”，而是写“检测到列表渲染超过 100 项且没有虚拟化”加上“用户提到卡顿”。这样 AI 需要同时满足两个条件才触发，精准度大幅提升。

第二个技巧是在 description 里写清楚“不适用场景”。比如“这个技能不适用于服务端渲染场景”，这样 AI 在判断时会主动排除。很多人只写适用场景，不写排除场景，结果 AI 在边缘情况下乱触发。

第三个技巧是用 examples 目录做负样本。在 skill 目录下放一个examples/not-applicable/文件夹，里面放一些不应该触发这个技能的代码示例。AI 在判断时会参考这些负样本，效果比纯文字描述好得多。这个技巧是我从社区里学来的，实测下来误触发率降低了大概一半。

3.3 执行步骤的颗粒度：太粗没用，太细累赘

执行步骤是 skill 的主体，但颗粒度很难把握。写得太粗，比如“重构代码使其更健壮”，等于没说；写得太细，比如“在第 3 行和第 4 行之间插入一个空行”，又太死板，换个项目就废了。

我的经验是按“决策点”来拆分步骤。每个步骤应该是一个需要 AI 做判断的节点，而不是一个机械操作。比如：

## 执行步骤 1. 扫描目标文件中所有的 useEffect 调用，识别出没有 cleanup 函数的那些。 2. 对每个有问题的 useEffect，判断它是否涉及异步操作。如果是，进入步骤 3；如果不是，进入步骤 4。 3. 对于涉及异步操作的 useEffect，检查是否存在竞态条件风险。如果存在，添加 AbortController 或取消标志。 4. 对于不涉及异步操作的 useEffect，检查是否有事件监听器或定时器需要清理。如果有，添加对应的 cleanup 函数。 5. 运行类型检查和 lint，确认修改没有引入新错误。

这种写法既给了 AI 明确的执行路径，又保留了判断空间。AI 不需要你告诉它每一行代码怎么改，它只需要知道“在什么情况下做什么决策”。这才是 skills 的正确用法。

4. 安装与配置：Claude Code、VS Code 和常见环境问题

4.1 Claude Code 的安装与 skills 目录配置

Claude Code 目前主要通过 npm 安装，命令是npm install -g @anthropic-ai/claude-code。安装完成后，在项目根目录运行claude就能启动。Skills 的默认加载路径是项目根目录下的.claude/skills/，你也可以通过环境变量CLAUDE_SKILLS_PATH指定其他路径。

这里有一个很多人会踩的坑：Windows 环境下需要启用虚拟机平台。如果你在 Windows 上运行 Claude Code 时看到“requires the virtual machine platform”的提示，需要去“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”，然后重启。这个提示和 skills 本身没关系，是 Claude Code 的运行时依赖，但很多新手会卡在这里。

另一个常见问题是PowerShell 里提示“无法将‘claude’项识别为 cmdlet”。这通常是 npm 全局安装路径没有加到 PATH 里。你可以用npm config get prefix查看全局安装路径，然后把这个路径加到系统环境变量里。如果用的是 nvm 管理 Node 版本，每次切换版本后可能需要重新确认 PATH。

4.2 VS Code 集成：让 skills 在编辑器里生效

VS Code 里用 Claude Code 有两种方式。一种是直接用集成终端运行claude，这种方式最简单，skills 的加载和命令行完全一致。另一种是安装 Claude Code 的 VS Code 扩展，在编辑器内直接调用。扩展方式的好处是可以在编辑器里直接看到 AI 的修改建议，不用来回切换窗口。

配置扩展时需要注意：skills 目录必须在工作区根目录下。如果你用的是多根工作区（multi-root workspace），每个根目录下的.claude/skills/会被分别加载。这个设计有利有弊：好处是不同项目的技能互不干扰，坏处是如果你想共享一套通用技能，需要在每个项目里都放一份。我的做法是把通用技能放在一个单独的仓库里，然后用符号链接（symlink）链接到各个项目，这样更新一处就能全局生效。

4.3 从 GitHub 手动安装社区 skills

社区里有很多高质量的 skills 仓库，比如typesafe-ai/skills、superpower-skills等。手动安装的步骤一般是：

# 克隆仓库到临时目录 git clone https://github.com/example/skills-repo.git /tmp/skills-repo # 复制需要的技能到项目目录 cp -r /tmp/skills-repo/skills/frontend-review .claude/skills/ # 清理临时目录 rm -rf /tmp/skills-repo

这里有个细节：复制之前先看一下 skill 的依赖。有些 skill 依赖特定的工具或环境变量，比如需要安装eslint或者设置OPENAI_API_KEY。直接复制过来但不配置依赖，运行时就会报错。我建议在复制之前先读一遍SKILL.md的“前置条件”部分（如果有的话），确认环境满足再安装。

还有一个经验：不要一次性安装太多 skills。我刚开始用的时候，从社区里一口气装了二十多个 skills，结果 AI 每次启动都要加载所有技能描述，响应速度明显变慢，而且触发冲突的概率大增。后来我精简到只保留项目真正需要的五六个，体验好了很多。建议按需安装，用完就删。

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

5.1 前端开发：组件审查与性能优化

前端是 skills 应用最成熟的领域之一。我自己的 React 项目里有一个component-review技能，专门用来审查组件代码。它的触发条件是“用户要求审查组件”或者“检测到组件文件被修改”。执行步骤包括：检查 props 类型定义、检查 useEffect 依赖数组、检查是否有不必要的重渲染、检查事件处理函数是否用了 useCallback。

这个技能最实用的地方是它带了一套示例代码。在examples/目录下，我放了bad-patterns.tsx和good-patterns.tsx两个文件，里面覆盖了十几种常见的前端反模式。AI 在审查时会参考这些示例，判断当前代码是否匹配反模式。实测下来，这种“示例驱动”的方式比纯文字描述准确得多，尤其是对于“什么样的代码算坏味道”这种主观判断。

另一个前端场景是样式规范检查。我写了一个style-guard技能，规定项目里必须用 CSS Modules 而不是全局样式，必须用设计系统的颜色变量而不是硬编码色值。这个技能会在 AI 生成新组件时自动触发，确保新代码符合规范。这比人工 review 效率高多了，而且不会漏。

5.2 数学建模：从选题到论文的流程化技能

数学建模比赛是 skills 的一个意外热门场景。我帮几个参加华为杯的朋友搭过一套建模 skills，效果出乎意料地好。核心思路是把建模流程拆成几个阶段，每个阶段一个 skill：

• problem-analysis：读题、提取关键信息、判断题型（优化、预测、评价等）
• model-selection：根据题型推荐模型库，比如优化问题推荐线性规划、遗传算法、模拟退火
• code-implementation：按选定模型生成 Python 代码，包含数据预处理、模型训练、结果可视化
• paper-writing：按竞赛论文格式生成摘要、问题重述、模型假设、符号说明、模型建立与求解

这套 skills 的关键在于阶段之间的衔接。每个 skill 的输出格式都定义得很清楚，下一个 skill 能直接读取上一个的输出。比如problem-analysis的输出是一个结构化的 JSON，包含题型、约束条件、目标函数；model-selection读取这个 JSON 后推荐模型。这种流水线式的设计让整个建模过程变得可管理，不会出现“写到一半不知道下一步干什么”的情况。

5.3 嵌入式开发：STM32 调试与寄存器配置

嵌入式场景对 skills 的要求更高，因为涉及硬件寄存器和时序。我做过一个stm32-gpio-config技能，用来生成 GPIO 初始化代码。它的核心是一张寄存器映射表，放在reference/register-map.md里。AI 在生成代码时会查这张表，确保寄存器地址和位定义正确。

这个技能的一个关键设计是强制检查时钟使能。STM32 的 GPIO 配置必须先使能对应端口的时钟，否则配置不生效。很多新手会忘记这一步，导致调试半天找不到问题。我在 skill 里加了一条硬性规则：“生成任何 GPIO 配置代码前，必须先输出时钟使能代码，并确认 RCC 寄存器地址正确。”这条规则帮我省了很多调试时间。

另一个嵌入式场景是中断优先级配置。我写了一个nvic-priority技能，根据 Cortex-M 的优先级分组规则，自动计算 NVIC 优先级值。这个技能里包含了一个优先级分组表，AI 会根据用户选择的分组模式（如 Group 2）自动计算抢占优先级和子优先级的位分配。这种计算如果手动做很容易出错，交给 skill 处理就稳多了。

5.4 AI 漫剧与内容生成：创意类 skills 的写法

AI 漫剧是最近兴起的一个方向，用 AI 生成漫画风格的连续剧集。这个场景的 skills 和编程类完全不同，它更侧重风格一致性和叙事连贯性。我试过写一个comic-panel技能，用来生成分镜描述。它的触发条件是“用户要求生成漫剧分镜”，执行步骤包括：读取角色设定文件、读取上一集剧情摘要、生成当前分镜的文本描述和画面提示词。

这个技能的核心是角色一致性检查。在reference/characters.md里定义每个角色的外貌特征、服装、性格关键词。AI 在生成分镜时会检查每个角色的描述是否和设定一致，如果发现偏差就自动修正。这个检查步骤是必须的，因为 AI 生成内容时很容易“忘记”之前的设定，导致角色形象前后不一致。

创意类 skills 的另一个经验是用“情绪曲线”控制叙事节奏。我在 skill 里定义了一个简单的情绪值范围（1 到 10），要求 AI 在生成每一集时标注情绪值，并确保整季的情绪曲线有起伏。这个技巧是从编剧理论里借来的，用在 AI 内容生成上效果很好，能避免剧情平淡。

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

6.1 技能不触发或误触发：排查清单

技能不触发是最常见的问题。我整理了一个排查清单，按优先级排序：

还有一个隐蔽的问题：文件编码。我有一次在 Windows 上写 SKILL.md，保存成了 GBK 编码，结果 Claude Code 读取时乱码，技能完全不触发。后来统一用 UTF-8 编码就好了。这个坑很隐蔽，因为文件在编辑器里看起来是正常的，只有 AI 读取时才出问题。

6.2 技能执行结果不符合预期：三个调整方向

技能触发了，但执行结果不对，通常有三个调整方向。第一是步骤不够具体，AI 不知道具体怎么做。比如“优化代码”改成“将嵌套的 if-else 重构为早返回模式”。第二是缺少示例，AI 对“好”的标准理解不一致。在 examples 目录里放正反示例，效果立竿见影。第三是输出格式没定义，AI 输出的结果没法用。在 SKILL.md 里明确输出格式，比如“输出一个 JSON，包含 filename、line、issue、suggestion 四个字段”。

我自己的经验是，大部分执行问题都可以通过加示例解决。文字描述有歧义，但示例代码没有歧义。如果一个 skill 执行结果不稳定，第一件事就是去加示例，通常加两三个正例和两三个反例，问题就解决了。

6.3 性能问题：skills 太多导致响应变慢

Skills 太多会拖慢 AI 的响应速度，因为每次请求都要加载和匹配所有技能描述。我的实测数据是：5 个 skills 以内基本无感，10 个以上开始有可感知的延迟，20 个以上延迟明显。所以控制 skills 数量是性能优化的第一要务。

具体做法是：按项目阶段拆分 skills，比如开发阶段只加载开发相关的，部署阶段只加载部署相关的。Claude Code 支持通过命令行参数指定 skills 路径，你可以为不同阶段准备不同的 skills 目录。另一个做法是合并相似技能，把三个小的代码审查技能合并成一个大的，用内部条件分支来处理不同情况。

还有一个技巧是用description字段做懒加载。Claude Code 会先读取所有 skill 的 description，只有当 description 匹配当前上下文时才加载完整的 SKILL.md。所以 description 要写得精准但简短，既能被匹配到，又不会占用太多上下文窗口。

6.4 跨平台兼容性：Windows、macOS 和 Linux 的差异

Skills 本身是纯文本文件，跨平台没问题，但执行环境有差异。Windows 上路径分隔符是反斜杠，macOS 和 Linux 是正斜杠。如果你的 skill 里包含路径操作，建议用相对路径或者让 AI 自己处理路径分隔符。我在 skill 里写路径时统一用正斜杠，Claude Code 在 Windows 上也能正确识别。

另一个差异是命令行工具。有些 skill 依赖grep、sed、awk这些 Unix 工具，在 Windows 上默认没有。如果你的团队有 Windows 用户，要么在 skill 里注明依赖，要么改用跨平台的工具（比如用 Node.js 脚本代替 shell 命令）。我自己的做法是尽量不依赖外部命令，能用 AI 自身能力完成的就不调工具。

7. 进阶技巧：让 skills 真正成为团队资产

7.1 版本管理与团队协作

Skills 最大的价值在于可复用和可传承。一个人写好的 skill，全团队都能用，而且随着使用不断迭代优化。我建议把 skills 目录纳入 Git 管理，和代码一起提交。每次修改 skill 都走正常的 code review 流程，确保质量。

团队协作时有一个经验：给每个 skill 指定一个 owner。Owner 负责维护这个 skill 的准确性和时效性，其他人发现问题时找 owner 反馈。没有 owner 的 skill 很容易腐烂，因为没人对它的质量负责。我们团队的做法是在 SKILL.md 的 frontmatter 里加一个owner字段，写明负责人。

另一个做法是建立 skill 的测试用例。在 skill 目录下放一个tests/文件夹，里面放一些输入输出对。每次修改 skill 后，手动跑一遍测试用例，确认行为没有退化。这个做法看起来麻烦，但对于核心 skill 来说非常值得，能避免“改了一个地方，坏了另一个地方”的问题。

7.2 技能组合与流水线设计

单个 skill 的能力有限，真正的威力在于组合。我设计过一条完整的代码审查流水线：security-check→performance-check→style-check→summary-report。每个 skill 负责一个维度，最后一个 skill 汇总所有发现，生成统一的审查报告。

组合的关键是定义清楚 skill 之间的接口。每个 skill 的输出格式要统一，下一个 skill 才能正确读取。我通常用 JSON 作为中间格式，因为结构清晰、易于解析。比如security-check输出一个 JSON 数组，每个元素包含file、line、severity、description；summary-report读取这个数组，按严重程度分组，生成 Markdown 报告。

流水线设计还有一个好处是可以并行执行。security-check和performance-check互不依赖，可以同时跑，最后汇总。Claude Code 目前不支持真正的并行执行，但你可以通过分步调用来模拟：先跑安全检查，再跑性能检查，最后汇总。虽然串行执行慢一点，但结果是一样的。

7.3 从社区 skills 中学习设计模式

社区里的开源 skills 是很好的学习材料。我分析过几十个热门 skills，总结出几个常见的设计模式。模板模式：skill 里包含一个输出模板，AI 按模板填充内容，适合报告生成类场景。检查清单模式：skill 里列出一系列检查项，AI 逐项检查并标记通过或失败，适合代码审查类场景。决策树模式：skill 里定义一系列判断条件，AI 根据条件走不同分支，适合问题诊断类场景。

学习这些模式的最好方式是读别人的 SKILL.md，然后自己改写一遍。不要直接复制，因为每个项目的需求不同。我通常会把社区 skill 下载下来，读一遍，理解它的设计思路，然后根据自己的项目特点重写。这个过程本身就是很好的学习，写几个之后就能形成自己的风格。

8. 我踩过的坑和最后分享的几个技巧

先说几个我踩过的坑。第一个是在 skill 里写死具体路径，比如/Users/xxx/project/src/，结果换台机器就失效了。后来改成相对路径或者用环境变量，问题解决。第二个是skill 的触发条件写得太“聪明”，用了一些复杂的正则表达式，结果 AI 理解不了，反而不触发。后来改成简单的关键词匹配，效果好多了。第三个是一次性改太多，一个 skill 里塞了十几个步骤，AI 执行到一半就乱了。后来拆成多个小 skill，每个只做一件事，稳定性大幅提升。

再分享几个实用技巧。技巧一：用examples/目录做“少样本学习”。在 skill 目录下放几个输入输出示例，AI 会参考这些示例来理解你的意图。这个技巧对格式要求高的 skill 特别有效，比如报告生成、代码重构。技巧二：在 SKILL.md 里加一个“常见错误”段落，列出这个 skill 容易犯的错误和避免方法。AI 读到这些会主动规避，效果比事后纠正要好。技巧三：定期清理不再使用的 skills。我每个月会 review 一次 skills 目录，把三个月没用过的删掉或者归档。保持 skills 库的精简，对性能和可维护性都有好处。

最后说一个我个人的体会：skills 的价值不在于数量，而在于质量。一个精心设计的 skill，能顶十个随便写的。我见过有人收集了几百个 skills，但真正用的就那几个。与其追求“技能库”的规模，不如把常用的几个场景做深做透。我现在项目里只保留了六个 skills，但每一个都经过多次迭代，触发精准、执行稳定、输出可靠。这比什么都强。