企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底是什么，为什么突然人人都在聊

如果你最近在开发者社区、AI 工具圈或者技术群里频繁看到“skills”这个词，不用怀疑，它已经从一个普通英文单词变成了一个特定技术概念的代称。我最早注意到这个趋势是在一批 Claude Code 相关的讨论里，当时有人问“claude code 怎么手动装 github 上的 skills”，底下回复五花八门，有人说是插件，有人说是提示词模板，还有人说是某种配置文件。实际上这些说法都对了一半，但都不够准确。

先把结论放在前面：Agent Skills（通常简称为 skills）是一套让 AI 编程助手具备特定领域能力的结构化知识包。它的核心载体是一个叫SKILL.md的文件，配合若干辅助资源文件，放在约定的目录结构里，AI 工具在运行时按需加载。你可以把它理解成给 AI 助手写的“岗位操作手册”——不是泛泛的系统提示词，而是针对某个具体任务场景的、可复用、可分发的能力模块。

为什么它值得单独拿出来讲？因为在此之前，想让 AI 助手干好一件特定的事，你要么在对话里反复粘贴一大段上下文，要么写一个很长的系统提示，要么干脆自己动手。skills 的出现改变了这个局面：它把“怎么让 AI 做好某类任务”这件事本身变成了一个可版本管理、可分享、可组合的工程产物。你写一次，团队里所有人、所有项目都能用；别人写好的，你 clone 下来放进目录就能生效。

这篇文章适合谁看？如果你是刚接触 Claude Code 或者类似 AI 编程工具的新手，想搞清楚 skills 到底怎么装、怎么写、怎么用，那这篇就是给你准备的。如果你已经在用这类工具，但一直停留在“对话式提问”的阶段，没体验过 skills 带来的效率跃迁，那也值得往下读。我会从目录结构、SKILL.md 的写法、安装方式、常见坑、实战案例几个角度，把这件事讲透。

需要提前说明的是，skills 这个概念目前主要围绕 Claude 系列工具（Claude Code、Claude Desktop 等）以及部分兼容生态（如 OpenCode）展开，不同工具对 skills 的支持程度和加载机制略有差异。我会以最通用的实践为主线，遇到工具差异时单独标注。

2. skills 的整体设计思路：为什么是 SKILL.md，而不是别的形式

2.1 从“提示词工程”到“能力封装”的转变

早期大家用 AI 编程助手，基本是“一问一答”模式：你描述需求，AI 给代码，不对就继续追问。这种方式在简单任务上没问题，但一旦涉及多步骤、有固定流程、需要特定领域知识的任务，就暴露出两个问题：一是每次都要重新交代背景，二是 AI 的输出质量高度依赖你这次描述得够不够细。

有人尝试用超长系统提示词来解决，把所有规则、示例、注意事项都塞进去。这确实能提升效果，但带来了新问题：提示词越来越臃肿，维护成本高，而且不同任务之间互相干扰——你给 AI 灌了一堆前端规范，它在你写数据库迁移脚本时也可能被这些规范带偏。

skills 的设计思路正是针对这个痛点。它把“能力”拆成独立的模块，每个模块有自己的触发条件和适用范围。AI 在处理任务时，先判断当前任务属于哪个 skill 的覆盖范围，然后只加载那个 skill 的内容。这就像公司里不是让一个人背下所有岗位手册，而是按需查阅对应的那一本。

2.2 SKILL.md 的核心结构

一个标准的 skill 目录通常长这样：

my-skill/ ├── SKILL.md # 核心文件，必须存在 ├── examples/ # 可选，示例代码或输入输出 ├── references/ # 可选，参考资料 └── scripts/ # 可选，辅助脚本

SKILL.md是整个 skill 的入口和主体。它用 Markdown 编写，但有一些约定俗成的结构。最关键的几个部分包括：

• 元信息区：通常用 YAML front matter 的形式写在文件开头，声明 skill 的名称、描述、触发关键词等。这部分决定了 AI 什么时候会“想起”这个 skill。
• 能力描述：说明这个 skill 能做什么、不能做什么、适用场景是什么。
• 操作指南：具体的步骤、规则、注意事项，这是 skill 的干货所在。
• 示例：输入输出示例，帮助 AI 理解预期行为。

我见过不少人写 SKILL.md 时把它当成普通文档来写，结果 AI 加载后效果很差。问题往往出在元信息区——描述写得太模糊，AI 根本判断不出什么时候该用这个 skill。比如描述写“帮助处理数据”，那 AI 面对一个 CSV 文件时可能犹豫要不要加载；但如果写“处理 CSV 文件的清洗、格式转换和统计分析，适用于 pandas 和 polars 场景”，触发就精准得多。

2.3 为什么选择 Markdown 而不是 JSON 或代码

有人可能会问，为什么不用 JSON 或者直接写 Python 脚本来定义 skill？Markdown 的优势在于它对 AI 友好。大语言模型对自然语言和结构化文本的混合理解能力很强，Markdown 既能用标题、列表、表格表达结构，又能用自然语言描述复杂规则，这是纯 JSON 做不到的。而且 Markdown 对人类也可读可编辑，降低了创作门槛。

另一个原因是可组合性。多个 skill 可以放在同一个 skills 目录下，AI 根据任务需要选择加载。如果每个 skill 是一个代码模块，组合和调用的复杂度会高很多。Markdown 的轻量特性让“写一个 skill”这件事的门槛降到了几乎为零——你不需要会编程，只需要能把一件事的流程和规则讲清楚。

3. 核心细节解析：一个高质量 SKILL.md 应该包含什么

3.1 元信息区：决定 skill 能否被正确触发

元信息区通常放在 SKILL.md 的最顶部，用---包裹。不同工具支持的字段略有差异，但以下几个是通用的：

--- name: csv-cleaner description: 清洗和标准化 CSV 文件，处理缺失值、重复行、格式不一致等问题 trigger: 当用户需要处理 CSV 文件、数据清洗、表格标准化时使用 version: 1.0.0 ---

这里最关键的是description和trigger。description 要简洁但信息密度高，trigger 要覆盖用户可能的各种表述方式。我自己的经验是，trigger 里至少包含三类词：任务类型词（清洗、转换、分析）、对象词（CSV、表格、数据文件）、工具词（pandas、Excel、数据库导入）。

注意：不要把所有可能的词都塞进 trigger，那样会导致 skill 被过度触发。比如一个专门处理 CSV 的 skill，trigger 里写“数据处理”就太宽了，AI 可能在处理 JSON 时也加载它，反而干扰输出。

3.2 能力边界：明确说什么不做

很多人在写 skill 时只写“能做什么”，忽略了“不做什么”。这在实际使用中会造成很大问题。比如你写了一个“生成 React 组件”的 skill，但没有说明它不负责样式方案选型，AI 可能会在生成组件时自作主张引入 Tailwind 或者 styled-components，而你的项目可能用的是 CSS Modules。

明确边界还有一个好处：当 AI 发现当前任务超出 skill 范围时，它会知道应该回退到通用能力或者提示用户。这比硬套一个不合适的 skill 要靠谱得多。

3.3 操作指南：步骤要具体到可执行

这是 SKILL.md 的主体部分，也是最容易写砸的地方。常见的错误是写得太抽象，比如“对数据进行清洗”——什么叫清洗？去掉空行还是填充缺失值？两者差别很大。

好的操作指南应该像给一个新同事写的操作手册，具体到每一步做什么、用什么工具、遇到什么情况怎么处理。举个例子：

## 操作步骤 1. 读取 CSV 文件时，先用 `pd.read_csv(file, encoding='utf-8-sig')` 尝试， 如果报编码错误，改用 `gbk` 重试。 2. 检查列名是否有前后空格，如有则统一 strip。 3. 对每一列统计缺失率： - 缺失率 > 80% 的列，建议直接删除，并在输出中说明。 - 缺失率在 20%-80% 之间的列，根据数据类型选择填充策略： 数值列用中位数，分类列用众数。 - 缺失率 < 20% 的列，直接删除缺失行。 4. 检查重复行，保留第一条，删除后续重复。 5. 输出清洗报告，包含：原始行数、清洗后行数、删除的列、填充的列及策略。

这种程度的细节，AI 加载后基本能稳定复现。如果你只写“清洗数据”，那每次输出都可能不一样。

3.4 示例：给 AI 一个“标准答案”的锚点

示例部分不需要多，但要有代表性。最好包含一个正常情况的输入输出，和一个边界情况的处理。比如 CSV 清洗 skill 可以给一个包含缺失值和重复行的样例文件，展示清洗前后的对比。

示例的作用是给 AI 一个“锚点”。大语言模型在面对模糊指令时，会倾向于模仿示例中的模式。你给了一个规范的示例，它输出的规范概率就高很多。

3.5 辅助资源：scripts 和 references 的用法

如果一个 skill 需要执行一些确定性很强的操作，比如格式转换、文件校验，可以放一个脚本在scripts/目录下，在 SKILL.md 里引用。这样 AI 不需要“生成”这段逻辑，直接调用脚本就行，稳定性和效率都更高。

references/目录适合放一些查阅性质的资料，比如 API 文档摘要、字段对照表、常见错误码列表。AI 在需要时可以读取这些文件，而不需要你把所有内容都塞进 SKILL.md 主体。

4. 实操过程：从零开始写一个能用的 skill

4.1 环境准备与目录约定

不同工具对 skills 的存放位置要求不同。以 Claude Code 为例，通常有两个位置：

• 项目级：放在项目根目录下的.claude/skills/里，只对当前项目生效。
• 用户级：放在用户主目录下的.claude/skills/里，对所有项目生效。

我一般建议先在项目级目录里开发和测试，稳定后再考虑放到用户级。因为项目级的 skill 可以跟着代码仓库走，团队协作时大家用的是一套。

目录结构上，每个 skill 一个独立文件夹，文件夹名就是 skill 的标识符。不要用中文或空格，用短横线连接的小写英文，比如csv-cleaner、react-component-gen。

4.2 从需求到 SKILL.md 的转化过程

假设我要写一个“数学建模常用数据预处理”的 skill。这个需求来自热词里的“数学建模skills推荐”，说明有不少人在这个场景下有需求。

第一步，明确这个 skill 要覆盖哪些具体任务。数学建模的数据预处理通常包括：缺失值处理、异常值检测、数据标准化/归一化、类别编码、数据划分。这些任务有固定套路，适合封装。

第二步，确定触发条件。用户可能在什么时候需要这个 skill？描述里应该包含“数学建模”“数据预处理”“缺失值”“标准化”“特征工程”等词。

第三步，写操作指南。这里要结合数学建模的特点——比如标准化方法的选择，Z-score 适合正态分布数据，Min-Max 适合有明确边界的数据，Robust 适合有异常值的数据。这些判断规则要写清楚。

第四步，给示例。用一个经典的鸢尾花数据集或者泰坦尼克数据集做示例，展示预处理前后的对比。

4.3 一个完整的 SKILL.md 示例

下面是我实际在用的一个简化版数学建模数据预处理 skill 的核心内容：

--- name: math-modeling-preprocess description: 数学建模竞赛中的数据预处理，包括缺失值、异常值、标准化、编码、划分 trigger: 数学建模、数据预处理、缺失值处理、数据标准化、特征工程、竞赛数据 version: 1.2.0 --- ## 能力范围 本 skill 覆盖数学建模中常见的数据预处理任务： - 缺失值检测与填充 - 异常值检测与处理 - 数值特征标准化/归一化 - 类别特征编码 - 训练集/测试集划分 不覆盖：特征选择、降维、模型调参。 ## 操作步骤 ### 缺失值处理 1. 统计每列缺失率。 2. 缺失率 > 70%：建议删除该列，输出中说明理由。 3. 缺失率 30%-70%：数值列用中位数填充，类别列用众数填充。 4. 缺失率 < 30%：数值列用均值填充，类别列用众数填充。 5. 如果缺失值具有业务含义（如“未填写”本身是信息），考虑填充为特殊值而非统计量。 ### 异常值处理 1. 数值列用 IQR 方法检测：Q1 - 1.5*IQR 到 Q3 + 1.5*IQR 之外视为异常。 2. 异常值比例 < 5%：用边界值截断（Winsorize）。 3. 异常值比例 5%-15%：考虑用中位数替换。 4. 异常值比例 > 15%：检查是否为数据录入错误，必要时删除该列。 ### 标准化 1. 数据近似正态分布：用 Z-score 标准化。 2. 数据有明确上下界：用 Min-Max 归一化。 3. 数据含较多异常值：用 Robust 标准化（基于中位数和 IQR）。 4. 树模型：通常不需要标准化，但做了也无害。 ### 类别编码 1. 有序类别：用 Ordinal Encoding，顺序按业务含义确定。 2. 无序类别且类别数 < 10：用 One-Hot Encoding。 3. 无序类别且类别数 >= 10：用 Target Encoding 或 Frequency Encoding。 ### 数据划分 1. 默认按 7:3 划分训练集和测试集。 2. 类别不平衡时用分层抽样（stratify）。 3. 随机种子固定为 42，保证可复现。 ## 示例 输入：包含缺失值、异常值和类别特征的 CSV 文件。 输出：预处理后的训练集和测试集，以及一份预处理报告。

这个 skill 写完后，我在几个建模项目中测试，AI 加载后输出的预处理代码基本符合预期，不需要每次重新交代规则。

4.4 安装与加载：手动装 GitHub 上的 skills

热词里有人问“claude code 怎么手动装 github 上的 skills”，这里说下通用做法。

从 GitHub 上拿到一个 skill，通常是一个文件夹或者一个压缩包。手动安装的步骤：

1. 确认你的 skills 目录位置。项目级是.claude/skills/，用户级是~/.claude/skills/。
2. 把 skill 文件夹整个复制进去。注意文件夹名要和 SKILL.md 里的 name 字段一致，不一致可能导致加载失败。
3. 检查 SKILL.md 的元信息区格式是否正确，特别是---是否成对出现。
4. 重启 AI 工具或者重新加载会话，让 skill 生效。
5. 在对话中触发相关任务，观察 AI 是否加载了该 skill。有些工具会在输出中提示“正在使用 xxx skill”。

注意：如果 skill 依赖 scripts 目录下的脚本，要确认脚本有可执行权限，并且依赖的库已经安装。我遇到过 skill 加载了但脚本跑不起来的情况，排查半天发现是缺了一个 Python 包。

4.5 调试与迭代：怎么知道 skill 写得好不好

写完一个 skill 不代表结束，实际使用中大概率需要迭代。我的做法是：

• 记录触发情况：哪些任务触发了这个 skill，哪些没触发但应该触发。没触发的情况要回头改 trigger。
• 检查输出一致性：同一个任务跑多次，输出是否稳定。如果不稳定，说明操作指南还不够具体。
• 收集边界案例：遇到 skill 处理不好的情况，把案例补充到示例或操作指南里。
• 定期清理：不再使用的 skill 及时删除或归档，避免干扰。

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

5.1 skill 不生效的几种典型原因

这是被问得最多的问题。根据我的排查经验，按出现频率排序：

5.2 Windows 环境下的特殊问题

热词里有一条“claude's workspace requires the virtual machine platform on windows. enable”，说明不少 Windows 用户在配置时遇到了虚拟化平台相关的问题。这类问题通常和工具的运行环境有关，不是 skills 本身的问题。通用的排查思路是：

• 确认系统版本满足工具的最低要求。
• 检查相关系统功能是否已启用。
• 如果使用 WSL，确认 WSL 版本和配置正确。
• 查看工具日志，定位具体报错信息。

另一个常见问题是命令行工具找不到，报“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这通常是环境变量 PATH 没配好，把工具的安装路径加到 PATH 里，或者用完整路径调用。

5.3 skill 写得太长导致加载慢

SKILL.md 不是越长越好。我见过有人写了一个 2000 行的 skill，结果每次加载都明显变慢，而且 AI 的输出反而变差了——信息过载导致它抓不住重点。

我的建议是：单个 SKILL.md 控制在 300-500 行以内。如果内容确实多，拆成多个 skill，或者把详细资料放到 references 目录，SKILL.md 里只保留核心规则和引用路径。

5.4 团队协作中的 skill 管理

团队里多人维护 skills 时，容易出现的几个问题：

• 命名冲突：两个人写了功能相似的 skill，名字不同但触发条件重叠。解决方法是建立命名规范，比如按“领域-功能”格式命名。
• 版本混乱：有人改了 skill 没通知其他人。解决方法是把 skills 目录纳入版本控制，改动走正常的代码审查流程。
• 质量参差：有人写的 skill 很粗糙。解决方法是建立 review 机制，新 skill 合并前至少一个人试用过。

5.5 几个我踩过的坑

第一个坑：在 SKILL.md 里写了太多“背景介绍”，结果 AI 把背景当成了操作指令。后来我把背景信息压缩到两三句话，重点放在操作步骤上。

第二个坑：trigger 里用了太通用的词，导致 skill 在不相关的任务里被触发。比如一个“代码审查”skill 的 trigger 里写了“代码”，结果写新代码时也被触发。后来改成“代码审查、review、检查代码质量”就精准多了。

第三个坑：示例里的输入输出太简单，AI 学到的模式不够泛化。后来我特意在示例里加入了一些边界情况，比如空值、特殊字符、超长文本，效果明显改善。

6. 不同场景下的 skills 实践参考

6.1 前端开发场景

热词里出现了“前端开发skills”，这个方向确实很适合用 skill 来封装。前端开发的很多任务有固定套路：组件生成、样式规范、路由配置、状态管理、接口对接。每个都可以写成一个 skill。

比如一个“React 组件生成”skill，可以规定：组件用函数式写法、Props 用 TypeScript 接口定义、样式用 CSS Modules、导出用命名导出。这样 AI 生成的组件风格统一，不需要每次交代。

前端 skill 的一个特殊点是，它往往需要和项目现有的技术栈对齐。所以 trigger 里最好包含技术栈关键词，比如“React”“Vue”“TypeScript”，避免在纯 JavaScript 项目里触发 TypeScript 相关的 skill。

6.2 数学建模竞赛场景

热词里“数学建模skills推荐”和“华为杯建模比赛好用的codex skills”说明这个场景需求很集中。数学建模的特点是时间紧、任务重、流程相对固定。常见的 skill 可以覆盖：

• 数据预处理（前面已经举例）
• 常用模型模板（线性回归、决策树、神经网络、时间序列）
• 结果可视化（图表类型选择、配色、标注）
• 论文写作辅助（摘要生成、公式排版、参考文献格式）

数学建模的 skill 要特别注意可复现性。竞赛中经常需要反复调整参数重新跑，如果 skill 里固定了随机种子和参数范围，能省很多事。

6.3 AI 内容创作场景

热词里“ai漫剧常用skills”指向了内容创作方向。这类 skill 和编程类 skill 的写法有区别：编程 skill 强调确定性和可验证性，内容创作 skill 更强调风格一致性和创意引导。

一个漫剧脚本创作的 skill，可能需要规定：角色对话风格、分镜描述格式、情节节奏、常见桥段模板。这类 skill 的示例部分尤其重要，因为“风格”这种东西很难用规则描述清楚，但给几个示例，AI 就能模仿。

6.4 学习与技能提升场景

热词里“如何学习skills(技能)”和“skills技能库网址”反映了另一类需求：有人想把 skills 用在个人学习上。这完全可行。你可以写一个“读书笔记整理”skill，规定笔记的结构、摘录格式、思考问题的角度。也可以写一个“语言学习”skill，规定每日练习的流程和反馈方式。

这类 skill 的关键是可持续性。学习是一个长期过程，skill 要能适应不同阶段的需求。我的做法是每隔一段时间回顾一次，根据当前水平调整难度和侧重点。

7. 关于 skills 生态的一些观察和实用建议

7.1 skills 和传统插件的区别

有人会把 skills 和插件混为一谈，其实两者定位不同。插件通常是扩展工具本身的功能，比如增加一个命令、接入一个服务。skills 扩展的是 AI 的“知识和流程”，它不改变工具的能力边界，而是让 AI 在特定任务上表现更好。

这个区别决定了 skills 的创作门槛更低——你不需要懂工具的插件开发接口，只需要能把一件事讲清楚。但也决定了 skills 的效果更依赖内容质量，写得好和写得差差距很大。

7.2 怎么判断一个 skill 值不值得写

不是所有任务都适合封装成 skill。我的判断标准是：

• 重复性：这个任务你会反复做吗？一次性任务不值得写 skill。
• 流程性：这个任务有固定步骤吗？完全靠临场发挥的任务不适合。
• 可描述性：你能把规则和步骤写清楚吗？如果自己都说不清，AI 更学不会。
• 容错性：这个任务出错代价大吗？代价大的任务适合用 skill 来规范。

四个条件都满足，就值得写。满足两三个，可以考虑。只满足一个，建议再想想。

7.3 skill 的维护成本

写 skill 是一次性投入，维护是长期成本。我自己的经验是，一个活跃使用的 skill，大概每两个月需要小改一次，每半年需要大改一次。改动的原因通常是：工具版本更新、项目技术栈变化、发现了新的边界情况。

所以不要贪多。维护十个粗糙的 skill，不如维护三个精良的。我见过有人一口气写了二十多个 skill，结果大部分都处于“写了但没用过”的状态，纯属浪费时间。

7.4 从哪里获取现成的 skills

GitHub 上已经有不少开源的 skills 集合，搜索相关关键词能找到。另外一些技术社区也有分享。获取现成 skill 时要注意几点：

• 看更新时间，太久没维护的可能不兼容当前工具版本。
• 看 issue 和讨论，了解实际使用中的问题。
• 先在小项目里试用，确认没问题再引入正式项目。
• 不要直接复制粘贴，根据自己的需求调整。

7.5 一个容易被忽略的点：skill 的命名

命名看起来是小事，但影响很大。好的命名应该：见名知意、长度适中、避免歧义。我习惯用“领域-功能”的格式，比如frontend-component-gen、>