企业官网建设流程全解析

1. 为什么"装技能"这件事值得单独写一篇指南

Skills 这个概念在 2025 年下半年开始密集出现在开发者视野里，但很多人第一次接触它的时候是懵的——它跟 Prompt 有什么区别？跟 MCP 是什么关系？为什么有人说它是"给 Agent 装外挂"，有人又说它只是"结构化的提示词"？

我自己从最早在 Claude Code 里手动往~/.claude/skills目录丢文件夹，到后来在 Cursor 里配置项目级技能，中间踩过的坑不算少。最典型的一次是：我写了一个自认为很完美的 SKILL.md，结果 Agent 死活不触发，排查了两个小时才发现是 frontmatter 里的description写得太抽象，模型判断"当前任务跟这个技能无关"。

所以这篇东西不是概念科普，而是一份实战导向的接入指南。我会先讲清楚 Skills 到底解决了什么问题、它的运行机制是什么，然后给出 8 类我认为真正值得装的技能（每一类都会说明适用场景和选择理由），最后把 Cursor 和 Claude Code 两条接入路径的完整流程拆开讲，包括目录结构、SKILL.md 的写法、触发条件调试、以及几个我实际踩过的坑。

适合谁看：已经在用 Cursor 或 Claude Code、但还没系统用过 Skills 的开发者；想给自己团队沉淀一套可复用 Agent 能力的 Tech Lead；以及那些看到"Agent Skills"这个词但一直没搞明白它跟普通 Prompt 差异的人。

前置知识要求不高，会基本的命令行操作、能看懂 YAML 和 Markdown 就够了。但如果你完全没用过任何 AI 编程工具，建议先去把 Cursor 或 Claude Code 跑起来，再回来看这篇。

2. Skills 的运行机制：它到底和 Prompt、MCP 差在哪

2.1 一句话说清楚 Skills 的本质

Skills 的本质是按需加载的结构化指令包。它不是一个常驻在上下文里的系统提示词，而是躺在磁盘上、等 Agent 判断"当前任务需要它"时才被读进来的一个 Markdown 文件（外加可选的脚本和资源）。

这个"按需"是关键。你想想，如果一个项目里有 30 个技能，全部塞进 system prompt，那上下文早就爆了，而且模型注意力会被稀释，反而什么都做不好。Skills 的设计思路是：元数据常驻，正文按需加载。

具体来说，Agent 启动时会扫描所有技能目录，只读取每个 SKILL.md 的 frontmatter（也就是name和description这两个字段），把它们拼成一个轻量的"技能清单"放进上下文。当你的请求进来，模型先看这个清单，判断哪个技能的描述跟当前任务匹配，匹配上了才去读那个技能的完整正文。

这就像你办公室里有一排工具箱，墙上贴着每个箱子的标签。你不需要记住每个箱子里有什么，只需要看标签，需要的时候再打开对应的箱子。

2.2 Skills 和 Prompt、MCP 的分工

很多人把这三个东西混为一谈，我用一个表格把它们的分工讲清楚：

打个比方：MCP 是给 Agent 装了一双手，让它能去够到外部世界；Skills 是给 Agent 装了一本操作手册，告诉它遇到某类活儿该怎么干；Prompt 则是你当场口头交代的一句话。

三者不冲突，反而经常配合使用。比如一个"数据库迁移"技能，它的正文里可能会指导 Agent 去调用某个 MCP 工具来执行 SQL，同时按照技能里定义的检查清单逐步验证。

2.3 SKILL.md 的目录结构长什么样

一个标准的技能就是一个文件夹，里面至少有一个SKILL.md，其他文件都是可选的：

my-skill/ ├── SKILL.md # 必需，技能主体 ├── scripts/ # 可选，可执行脚本 │ └── validate.py ├── references/ # 可选，参考文档 │ └── api-spec.md └── assets/ # 可选，模板、图片等资源 └── template.tsx

SKILL.md本身分两部分：frontmatter 和正文。

--- name: react-component-generator description: 按照团队规范生成 React 函数组件，包含 TypeScript 类型、样式方案和测试文件。当用户要求创建新的 React 组件时使用。 --- # React 组件生成规范 ## 组件结构 每个组件必须包含以下部分： 1. 类型定义（Props interface） 2. 组件函数本体 3. 默认导出 ## 命名约定 - 组件文件使用 PascalCase - 样式文件使用 kebab-case ...

frontmatter 里的description是整个技能最重要的字段，因为它决定了 Agent 会不会在正确的时机加载这个技能。写得太宽泛（比如"帮助写代码"），会导致误触发；写得太窄（比如"生成带 useMemo 的表格组件"），会导致该触发时不触发。

我的经验是：description里要同时包含能力描述和触发场景，用"当……时使用"这样的句式明确边界。上面那个例子里，"按照团队规范生成 React 函数组件"是能力，"当用户要求创建新的 React 组件时使用"是触发条件，两者缺一不可。

2.4 技能是怎么被"选中"的

理解触发机制对调试非常关键。整个流程大致是这样：

1. Agent 启动，扫描技能目录，把所有技能的name+description拼成清单放进上下文
2. 用户发出请求
3. 模型基于请求内容和技能清单，判断是否有技能匹配
4. 匹配成功则读取该技能的完整 SKILL.md 正文
5. 模型按照正文里的指令执行任务

第 3 步是黑盒，但你可以通过观察 Agent 的行为来反推。如果技能没被触发，八成是description的问题；如果触发了但执行结果不对，那是正文写得不够具体。

提示：调试技能触发时，可以在请求里显式提到技能名，比如"用 react-component-generator 技能帮我创建一个 Button 组件"。如果这样能触发，说明技能本身没问题，是description的匹配度不够。

3. 8 类真正值得装的技能，以及每类的选择逻辑

市面上的技能五花八门，但真正能长期留在你工具箱里的其实不多。我按"使用频率 × 价值密度"筛出了 8 类，每一类都会说清楚它解决什么问题、为什么值得装、以及挑选时该看什么。

3.1 代码规范类：把团队约定固化下来

这是优先级最高的一类。每个团队都有自己的代码规范，但规范文档写在那里没人看，Code Review 时又反复提同样的问题。把它做成技能，Agent 每次生成代码时自动遵守，省下的沟通成本非常可观。

典型技能包括：

• 特定框架的组件生成规范（React、Vue、Svelte 各一套）
• API 接口定义规范（RESTful 命名、错误码约定、响应结构）
• 数据库 Schema 设计规范（字段命名、索引策略、迁移文件格式）
• Git commit message 规范（Conventional Commits 的团队变体）

挑选这类技能时，重点看它的规范是否具体到可执行。一个合格的规范技能应该告诉你"变量名用 camelCase，常量用 UPPER_SNAKE_CASE，布尔值以 is/has/can 开头"，而不是泛泛地说"遵循良好的命名习惯"。

3.2 文档生成类：让 Agent 替你写那些不想写的文档

写文档是开发者的普遍痛点，但 Agent 写文档又容易写成流水账。文档生成类技能的价值在于，它把"好文档长什么样"这个隐性知识显性化了。

我常用的几个：

• README 生成器：按固定结构输出（项目简介、快速开始、API 说明、贡献指南），避免每次结构都不一样
• API 文档生成器：从代码注释或类型定义提取信息，输出 OpenAPI 或 Markdown 格式
• 变更日志生成器：读取 git log，按 Keep a Changelog 格式归类整理
• 架构决策记录（ADR）生成器：把一次技术选型的背景、选项、决策、后果结构化记录下来

这类技能的关键是模板要固定。如果每次生成的文档结构都不同，那还不如自己写。所以技能正文里应该包含一个明确的模板骨架，Agent 只负责填充内容。

3.3 测试编写类：覆盖率和可维护性兼顾

测试代码的质量往往被忽视，但它直接决定了重构时你敢不敢动手。测试编写类技能要做的是：让 Agent 生成的测试既覆盖到位，又不会因为过度 mock 而变得脆弱。

值得装的：

• 单元测试生成器：针对特定测试框架（Jest、Vitest、Pytest），按 AAA 模式（Arrange-Act-Assert）组织
• 集成测试生成器：处理数据库、外部服务的测试隔离
• 测试数据工厂：生成符合业务约束的测试数据，避免硬编码
• 边界条件检查清单：提醒 Agent 覆盖空值、极值、并发等容易漏掉的场景

这类技能里，我最看重的是边界条件清单。因为 Agent 默认生成的测试往往只覆盖 happy path，把"必须测试空数组、必须测试超长字符串、必须测试并发调用"这些写进技能，能显著提升测试质量。

3.4 重构与迁移类：处理那些"想想就头疼"的活儿

重构和迁移是典型的高价值、高重复、易出错的任务，特别适合做成技能。

• 框架升级助手：比如 React 17 升 18、Vue 2 升 3，把破坏性变更和迁移步骤写清楚
• 依赖替换助手：比如从 Moment.js 迁到 Day.js，从 Axios 迁到 Fetch
• 代码风格迁移：比如从 Class 组件迁到 Hooks，从 Options API 迁到 Composition API
• 死代码清理：识别未使用的导出、未引用的文件

这类技能的价值在于步骤化。迁移不是一步到位的，需要分阶段验证。技能正文里应该包含明确的阶段划分和每阶段的验证方法，而不是让 Agent 一把梭。

3.5 调试排查类：把排查思路沉淀成清单

调试是经验密集型工作，老手和新手的差距往往在于"知道该往哪看"。把排查思路做成技能，相当于给 Agent 装了一个老手的直觉。

• 性能问题排查：从前端到后端的完整排查链路（网络、渲染、内存、CPU、数据库）
• 内存泄漏排查：针对 Node.js 或浏览器的具体排查步骤
• 构建失败排查：常见构建错误的诊断树
• 线上问题应急：从告警到定位到止血的标准流程

这类技能要写成决策树的形式：如果 A 现象，检查 B；如果 B 正常，检查 C。而不是罗列一堆可能的原因让 Agent 自己猜。

3.6 数据处理类：让 Agent 处理那些琐碎的数据活儿

日常开发中总有一些数据处理的小活儿，写脚本嫌麻烦，手动做又费时间。

• CSV/JSON 转换器：处理格式转换、字段映射、数据清洗
• SQL 查询生成器：按业务需求生成查询，包含索引提示
• 数据迁移脚本生成器：生成可回滚的数据迁移脚本
• 日志分析助手：从日志中提取模式、统计频次、定位异常

这类技能的关键是输入输出格式明确。技能正文里要写清楚"输入是什么格式、输出是什么格式、中间做了哪些转换"，避免 Agent 自由发挥。

3.7 项目脚手架类：新项目不再从零开始

每次开新项目都要重复配置一堆东西，脚手架类技能能把这个过程压缩到几分钟。

• 项目初始化器：按技术栈生成完整的项目骨架（目录结构、配置文件、基础依赖）
• CI/CD 配置生成器：生成 GitHub Actions、GitLab CI 的配置文件
• Docker 配置生成器：生成 Dockerfile 和 docker-compose.yml
• 环境变量模板生成器：根据代码中的引用生成 .env.example

这类技能要包含可选项和默认值。比如项目初始化器应该问清楚"要不要 TypeScript、要不要 ESLint、要不要测试框架"，然后按选择生成不同的骨架。

3.8 领域知识类：把业务规则喂给 Agent

这类技能最容易被忽视，但价值可能最高。每个项目都有一些"只有老员工才知道"的业务规则，把这些写进技能，Agent 就不会再犯那些低级错误。

• 业务术语表：解释项目里的领域概念，避免 Agent 用错词
• 状态机说明：描述业务对象的状态流转规则
• 权限模型说明：说清楚角色、权限、资源的对应关系
• 第三方服务集成说明：记录对接外部服务时的注意事项和坑

这类技能不需要多复杂，但一定要准确。业务规则写错了，Agent 会一本正经地执行错误逻辑，比不写还糟糕。

4. 在 Claude Code 里接入 Skills 的完整流程

4.1 技能目录的层级与优先级

Claude Code 支持多个层级的技能目录，优先级从高到低：

项目级优先级最高，意味着如果同名技能同时存在于项目级和用户级，项目级的会覆盖用户级。这个设计很合理：项目专属的规范应该压过个人偏好。

我的建议是：通用技能放用户级，项目专属技能放项目级。比如"React 组件生成规范"如果每个项目都一样，就放用户级；如果这个项目有特殊的目录结构约定，就放项目级。

4.2 手动安装一个技能

从 GitHub 上拿到一个技能包后，安装步骤其实很简单：

# 假设技能包在 ~/Downloads/my-skill 目录 # 安装到用户级 mkdir -p ~/.claude/skills cp -r ~/Downloads/my-skill ~/.claude/skills/ # 或者安装到项目级 mkdir -p .claude/skills cp -r ~/Downloads/my-skill .claude/skills/

复制完之后，验证一下目录结构：

ls -la ~/.claude/skills/my-skill/ # 应该能看到 SKILL.md

然后重启 Claude Code（或者重新加载会话），技能就会被扫描到。

注意：有些技能包在 GitHub 上是压缩包形式，解压后可能多一层目录。确保SKILL.md直接位于技能文件夹的根目录下，而不是嵌套在子目录里。我见过有人解压后变成my-skill/my-skill-main/SKILL.md，这样是扫描不到的。

4.3 验证技能是否被正确加载

Claude Code 里没有直接的"列出所有技能"命令，但你可以通过一个技巧验证：在对话里问"你现在有哪些可用的技能？"，模型会基于上下文里的技能清单回答。

如果技能没出现在列表里，按这个顺序排查：

1. 目录路径对不对：确认是.claude/skills/而不是.claude/skill/（少个 s 是常见错误）
2. SKILL.md 位置对不对：确认在技能文件夹根目录，不是嵌套的
3. frontmatter 格式对不对：name和description必须存在，YAML 语法不能有错
4. 有没有重启：技能是启动时扫描的，改完要重启

4.4 触发测试与调试

技能加载成功不代表能正确触发。测试方法是：构造一个应该触发该技能的任务，看 Agent 的行为是否符合技能里的指令。

比如你装了一个"API 文档生成器"，就发一个"帮我给这个 controller 生成 API 文档"的请求，观察 Agent 是否按照技能里定义的模板输出。

如果没触发，按这个思路调：

• 显式点名：在请求里直接说"用 xxx 技能来做"，如果这样能触发，说明是description匹配度问题
• 改 description：把触发场景写得更具体，加入用户可能用的关键词
• 检查冲突：如果有多个技能描述相似，模型可能选错，需要把各自的边界写清楚

我踩过的一个坑是：两个技能都涉及"生成测试"，description都写了"生成测试代码"，结果模型经常选错。后来我把一个改成"生成单元测试（针对单个函数或类）"，另一个改成"生成集成测试（针对多个模块的协作）"，问题就解决了。

5. 在 Cursor 里接入 Skills 的完整流程

5.1 Cursor 对 Skills 的支持方式

Cursor 对 Skills 的支持跟 Claude Code 略有不同。它主要通过.cursor/rules/目录来管理类似的能力，但新版本也开始支持.cursor/skills/目录来兼容 SKILL.md 格式。

如果你用的是较新版本的 Cursor，可以直接把 Claude Code 的技能包复制到.cursor/skills/下，格式是兼容的。如果版本较老，可能需要转换成 Cursor Rules 的格式（.mdc文件）。

两者的核心差异：

5.2 项目级技能的配置步骤

在 Cursor 里配置项目级技能：

# 创建技能目录 mkdir -p .cursor/skills # 复制技能包 cp -r ~/Downloads/my-skill .cursor/skills/

如果 Cursor 版本不支持 skills 目录，就转成 rules 格式。一个.mdc文件长这样：

--- description: 按照团队规范生成 React 函数组件 globs: ["src/components/**/*.tsx"] alwaysApply: false --- # React 组件生成规范 （正文内容跟 SKILL.md 一样）

globs字段指定了规则生效的文件范围，alwaysApply控制是否常驻。对于代码规范类技能，我建议用globs限定范围 +alwaysApply: false，这样只在编辑相关文件时才加载，节省上下文。

5.3 用户级技能的配置

Cursor 的用户级规则放在~/.cursor/rules/下，对所有项目生效。适合放那些跨项目通用的规范，比如个人偏好的代码风格、常用的调试思路等。

配置方式跟项目级一样，只是路径不同：

mkdir -p ~/.cursor/rules cp my-rule.mdc ~/.cursor/rules/

5.4 Cursor 里调试技能触发

Cursor 的调试比 Claude Code 稍微直观一些，因为它会在侧边栏显示当前激活的规则。如果规则没生效，检查：

1. globs 是否匹配当前文件：比如规则限定src/components/**/*.tsx，但你在编辑src/utils/helper.ts，那规则不会生效
2. alwaysApply 设置：如果设为 false 且 globs 没匹配上，规则就不会加载
3. 规则冲突：多条规则同时匹配时，Cursor 会全部加载，可能产生冲突

提示：Cursor 的规则调试可以在设置里打开"Show Rules in Context"，这样每次请求时能看到实际加载了哪些规则，对排查非常有用。

6. 写一个高质量 SKILL.md 的实战要点

6.1 description 的写法：决定触发率的关键

description是技能的门面，它要同时回答两个问题：这个技能能做什么、什么时候该用它。

我总结了一个模板：

[能力描述]，[具体产出]。当[触发场景1]、[触发场景2]时使用。

举个例子：

生成符合团队规范的 React 函数组件，包含 TypeScript 类型定义、样式文件和单元测试。当用户要求创建新的 React 组件、重构现有组件、或需要组件模板时使用。

对比一下反例：

帮助写 React 代码。

后者的问题很明显：太宽泛，任何跟 React 相关的任务都可能触发，导致误加载；同时"帮助写代码"没有说明产出是什么，模型无法判断是否匹配。

6.2 正文结构：从"能看懂"到"能执行"

正文的目标是让 Agent 读完就知道具体怎么做。我习惯用这个结构：

1. 概述：一两句话说明这个技能的核心目标
2. 前置条件：执行前需要确认什么（比如"确认项目使用 TypeScript"）
3. 执行步骤：分步骤写清楚，每步都有明确的输入输出
4. 检查清单：完成后要验证哪些点
5. 示例：给一个完整的输入输出示例

其中检查清单是最容易被忽略但最有价值的部分。Agent 执行完任务后，会按照检查清单逐项验证，能显著降低出错率。

6.3 脚本和资源的引用方式

如果技能需要执行脚本，在正文里明确写出调用方式：

## 验证步骤 执行以下命令验证生成的组件： ```bash python scripts/validate.py --component src/components/Button.tsx

脚本会检查：

• Props 类型是否完整
• 是否有默认导出
• 测试文件是否存在

引用参考文档时，用相对路径： ```markdown 详细的 API 规范见 [references/api-spec.md](references/api-spec.md)。

Agent 会按需读取这些文件，不需要你手动加载。

6.4 我踩过的三个坑

坑一：description 里用了太多同义词。我一开始写"生成/创建/新建 React 组件"，以为覆盖更多关键词能提高触发率，结果反而让模型困惑。后来精简成"创建新的 React 组件"，触发反而更准。

坑二：正文写成了教程。我第一版 SKILL.md 写了 2000 多字，从 React 基础讲到 Hooks 原理。结果 Agent 读完抓不住重点。后来压缩到 500 字以内，只保留"做什么、怎么做、怎么验证"，效果好很多。

坑三：忘了写边界条件。技能里没说明"如果项目没用 TypeScript 怎么办"，Agent 遇到这种情况就自由发挥了。后来我在前置条件里加了一句"如果项目未使用 TypeScript，先生成 JavaScript 版本并提示用户"，问题解决。

7. 技能组合与进阶玩法

7.1 技能之间的协作

单个技能的能力有限，但多个技能组合起来能完成复杂任务。比如"新功能开发"这个场景，可能涉及：

1. project-scaffold技能生成目录结构
2. api-design技能定义接口
3. react-component-generator技能生成前端组件
4. test-generator技能生成测试
5. doc-generator技能生成文档

这些技能不需要显式编排，Agent 会根据任务进展自动切换。但前提是每个技能的description边界清晰，不会互相干扰。

7.2 技能的版本管理

技能是代码资产，应该纳入版本管理。我的做法是：

• 项目级技能跟项目代码一起提交到 Git
• 用户级技能单独建一个仓库管理
• 每个技能文件夹里放一个CHANGELOG.md记录变更

这样团队协作时，技能能随代码库同步更新，不会出现"你用的技能跟我用的不一样"的问题。

7.3 从社区获取技能的注意事项

社区上的技能包质量参差不齐，安装前建议检查：

• SKILL.md 是否完整：有没有 frontmatter，正文是否具体
• 有没有脚本：如果有脚本，读一遍确认没有危险操作
• 更新频率：长期不更新的技能可能已经过时
• 来源可信度：优先选择有明确作者和维护记录的项目

注意：安装第三方技能前，务必通读 SKILL.md 和所有脚本。技能本质上是给 Agent 的指令，恶意技能可能诱导 Agent 执行危险操作。这不是危言耸听，社区里已经出现过类似案例。

7.4 技能的效果评估

装了技能之后，怎么知道它有没有用？我的评估方法是：

• 触发率：在应该触发的任务里，实际触发了几次
• 准确率：触发后，产出是否符合预期
• 节省时间：相比手动做，节省了多少时间
• 维护成本：技能本身需要多久更新一次

如果某个技能触发率低、维护成本高，就该考虑删掉或者重写。技能不是越多越好，能稳定用起来的才是好技能。

8. 一些实战中的零散经验

最后分享几个我在实际使用中攒下来的零散经验，不成体系但都挺实用。

关于目录命名：技能文件夹名建议用 kebab-case，跟name字段保持一致。我见过有人文件夹叫MySkill，name写my-skill，虽然能用但容易混淆。

关于中文技能：SKILL.md 完全可以用中文写，Agent 理解没问题。但如果技能要分享给国际团队，建议用英文，或者中英双语。

关于技能粒度：一个技能只做一件事。我一开始把"生成组件 + 生成测试 + 生成文档"塞进一个技能，结果 Agent 经常只做第一步就停了。拆成三个技能后，每个都能完整执行。

关于调试日志：Claude Code 和 Cursor 都有日志功能，调试技能触发问题时打开日志，能看到模型实际加载了哪些技能、为什么选择某个技能。这比盲猜高效得多。

关于技能更新：技能不是写完就完事了。项目规范变了、框架升级了、团队约定调整了，技能都要跟着更新。我建议每个季度 review 一次所有技能，把过时的删掉或重写。

关于分享：如果你写了一个好用的技能，不妨分享出来。社区里的优质技能越多，大家的效率都越高。分享时记得写清楚适用场景和依赖条件，方便别人判断是否适合自己。

技能这个东西，本质上是在把"隐性知识显性化"。你脑子里那些"遇到这种情况应该这么办"的经验，写成 SKILL.md 之后，就变成了 Agent 能复用的能力。这个过程本身也是对自己经验的一次梳理，写技能的过程中经常会有"原来我是这么想的"这种顿悟。

从最简单的代码规范技能开始，先跑通一个，感受一下 Agent 按你的规范干活是什么体验。跑通之后，你自然会知道下一个该写什么技能。