企业官网建设流程全解析

1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个词作为项目标题，大部分人脑子里蹦出来的画面可能完全不一样。做前端的朋友会想到自己维护的那套组件库技能包，搞AI的会想到Agent的能力模块，做数学建模的会想到竞赛里那些能直接调用的解题套路。这个词太泛了，泛到如果不结合上下文，根本没法聊。

但把热搜词摊开一看，方向就清楚了：Claude、Agent Skills、SKILL.md、Claude Code这几个词反复出现，说明这里说的"skills"不是泛泛而谈的个人技能，而是围绕Claude生态构建的一套可复用能力单元。再往下看，"前端开发skills""数学建模skills""AI漫剧常用skills""codex nature skills"这些具体场景词，进一步印证了这一点——skills已经从一个抽象概念，变成了一个按领域切分、按文件组织、按需加载的工程化产物。

那它到底解决什么问题？简单说，大模型本身是个"通才"，什么都能聊两句，但落到具体任务上经常不够专业。你让它写个STM32的驱动代码，它可能给你一堆看起来对但引脚定义全错的示例；你让它做数学建模的灵敏度分析，它可能连Morris方法和Sobol指数的区别都说不清楚。Skills的本质，就是把领域专家的经验、流程、模板、检查清单，打包成模型能直接读取和执行的结构化文件，让通才模型在特定场景下瞬间变成"有经验的从业者"。

这套东西适合谁？三类人最该关注：一是日常用Claude Code写代码的开发者，skills能帮你把重复性的项目配置、代码规范、调试流程固化下来；二是做垂直领域AI应用的产品或研究者，skills提供了一种低成本注入领域知识的方式；三是任何想把自己工作经验"资产化"的人，你脑子里那些"遇到X情况就按Y步骤处理"的隐性知识，写成SKILL.md之后就能被反复调用。

我自己的体会是，skills这个概念最值钱的地方不在于技术多复杂，而在于它把"提示词工程"从一次性消耗品变成了可版本管理的工程资产。以前你写一段精心设计的prompt，用完就散了，下次还得重新想。现在你把它写成skill文件，放进项目目录，团队里谁都能用，改一版提交一次，跟管理代码没区别。

2. SKILL.md的文件结构：一个skill到底长什么样

2.1 核心字段拆解与最小可用模板

聊skills绕不开SKILL.md这个文件。它是skill的载体，也是模型读取能力的入口。很多人第一次写的时候容易把它当成普通的README来写，结果模型读完之后要么理解偏了，要么根本不知道什么时候该调用。问题出在没有按照模型能解析的结构来组织信息。

一个能跑起来的SKILL.md，核心字段其实就几个，但每个字段的写法都有讲究。我按实际使用中验证过的顺序来说：

--- name: stm32-driver-helper description: 当用户需要编写或调试STM32外设驱动代码时使用，覆盖GPIO、UART、SPI、I2C的初始化与中断处理 --- # STM32驱动开发助手 ## 适用场景 - 用户提到STM32、HAL库、标准外设库、寄存器配置 - 需要生成GPIO/UART/SPI/I2C的初始化代码 - 调试中断不触发、通信失败等问题 ## 核心流程 1. 先确认芯片型号和使用的库（HAL还是标准库） 2. 确认时钟树配置，特别是外设挂载的总线 3. 按"时钟使能→引脚配置→外设初始化→中断配置→使能"的顺序生成代码 4. 检查中断优先级分组是否与现有代码冲突 ## 常见坑 - 忘记使能AFIO时钟导致复用功能不生效 - UART中断里没清标志位导致反复进中断 - SPI的CPOL/CPHA模式与从机不匹配

这个模板里，frontmatter部分的name和description是给模型做路由用的，description写得越具体，模型越容易判断"当前任务该不该调用这个skill"。正文部分则是执行时的参考内容，流程和坑点要写得像给一个刚入行的同事看的操作手册，而不是像给领导看的汇报材料。

2.2 description字段为什么决定了skill的生死

我见过太多人花大力气写正文，结果description就写一句"帮助处理前端开发相关任务"。这种写法基本等于没写，因为模型在决定调用哪个skill时，主要依据就是description的语义匹配度。你写得太泛，模型要么不调用，要么在错误的场景下调用。

好的description应该包含三个要素：触发条件、覆盖范围、排除边界。举个例子对比一下：

最后那种写法，模型一看就知道什么时候该用、什么时候不该用。排除边界特别重要，因为很多skill的适用范围有重叠，不写清楚"不适用于什么"，模型就会在边界场景下乱调用。

2.3 正文内容的组织逻辑：给模型看的操作手册

正文部分我习惯按"场景→流程→坑点→示例"四段式来组织。场景部分帮模型确认当前任务是否真的匹配，流程部分给出可执行的步骤序列，坑点部分是经验注入的核心，示例部分提供输入输出的参照。

这里有个容易忽略的细节：流程步骤要写成"动作序列"而不是"知识陈述"。比如"UART初始化需要配置波特率"这是知识陈述，"先调用HAL_UART_Init设置波特率，再检查返回值是否为HAL_OK"这是动作序列。模型执行时更需要后者，因为它可以直接映射到代码生成或操作指导上。

坑点部分是我认为最有价值的地方。这些内容通常不会出现在官方文档里，都是实际调试中踩出来的。比如"STM32的SPI在DMA模式下，发送完成中断和DMA传输完成中断的触发时机不同，如果混用会导致数据错位"这种细节，写进去之后模型在生成相关代码时就会主动规避。

3. 从零写一个能用的skill：完整实操链路

3.1 先想清楚"这个skill解决什么重复问题"

动手写之前，先问自己一个问题：我是不是在反复做同一类事情，而且每次都要重新想一遍流程？如果是，那这件事就值得写成skill。如果不是，写了也是闲置。

我拿自己写"数学建模灵敏度分析"skill的经历来说。之前每次做建模题，到了灵敏度分析环节都要重新回忆：Morris筛选法适合什么情况、Sobol指数怎么算、结果怎么可视化。每次都要翻之前的代码，改改参数再用。这就是典型的"重复性认知劳动"，适合固化。

确定要写之后，先别急着打开编辑器。拿一张纸，把这类任务的完整流程默写一遍，包括你通常会打开哪些参考、检查哪些参数、在哪些地方容易出错。这一步是在提取隐性知识，写出来的东西就是skill正文的雏形。

3.2 目录放哪里、怎么被加载

Skill文件的存放位置决定了它能不能被模型发现。不同工具的加载机制不一样，但核心逻辑都是在特定目录下扫描SKILL.md文件。以Claude Code为例，常见的做法是在项目根目录下建一个.claude/skills/目录，每个skill一个子文件夹，里面放SKILL.md。

项目根目录/ ├── .claude/ │ └── skills/ │ ├── stm32-driver-helper/ │ │ └── SKILL.md │ ├── math-modeling-sensitivity/ │ │ └── SKILL.md │ └── frontend-component-review/ │ └── SKILL.md ├── src/ └── package.json

这种组织方式的好处是skill跟着项目走，团队里每个人拉下代码就自动获得了这套能力。如果是个人常用的通用skill，也可以放在用户级目录下，这样所有项目都能用。

注意：不同版本的工具对skill目录的识别规则可能有差异，建议先在一个测试项目里验证加载是否成功，再批量迁移。

3.3 写完之后怎么验证它真的被调用了

写完skill最怕的情况是：你以为它生效了，实际上模型根本没读。验证方法有几个层次：

第一层，看模型是否主动提及。当你提出一个匹配description的任务时，模型如果调用了skill，通常会在回复中体现出skill里定义的流程或坑点。比如你问"帮我写个STM32的UART初始化"，如果skill生效了，模型可能会先问"你用的是HAL库还是标准库"，因为skill流程里第一步就是确认这个。

第二层，故意触发坑点。在skill里写了一个明确的坑点，比如"不要忘记使能AFIO时钟"，然后提一个容易踩这个坑的任务，看模型是否主动提醒。如果提醒了，说明skill内容被读取了。

第三层，对比实验。把skill文件临时移走，用同样的prompt问一遍，对比两次输出的差异。差异明显说明skill在起作用，差异不明显说明要么skill写得不够具体，要么加载机制有问题。

我自己的经验是，description的匹配精度是决定skill是否被调用的首要因素，正文质量决定调用后的效果。很多人反过来，正文写得很用心，description随便写，结果skill从来没被触发过。

4. 不同领域的skill设计差异：前端、建模、AI漫剧各有什么讲究

4.1 前端开发skill：组件规范与代码审查的固化

前端领域的skill有个特点：规范类知识占比高，而且更新快。你今天定的组件命名规范，下个季度可能就因为引入新框架而调整。所以前端skill的设计重点是把规范写成可检查的清单，而不是写成教程。

比如一个"React组件审查"skill，正文可以这样组织：

## 审查清单 - [ ] 组件是否使用函数式写法，是否有多余的class组件残留 - [ ] hooks调用是否在顶层，有没有放在条件语句里 - [ ] useEffect依赖数组是否完整，有没有遗漏导致闭包陷阱 - [ ] 状态是否最小化，有没有可以从props推导的状态被单独存储 - [ ] 事件处理函数是否用useCallback包裹（在传递给子组件时） - [ ] 列表渲染的key是否稳定且唯一，有没有用index

这种清单式写法的好处是，模型可以逐条对照检查，输出结构化的审查结果。比写成大段文字描述有效得多。

前端skill还有一个特殊点：要跟项目实际使用的技术栈绑定。你项目用React 18加TypeScript，skill里就要明确写"本skill适用于React 18+和TypeScript 5+，不适用于React 17及以下"。否则模型可能按旧版本的写法生成代码，比如用componentDidMount而不是useEffect。

4.2 数学建模skill：方法选择与结果验证的决策树

数学建模的skill跟前端完全不同，它的核心不是规范，而是决策逻辑。同一个问题，用线性规划还是整数规划，用遗传算法还是粒子群，结果可能差很多。Skill要做的就是把"什么情况下选什么方法"这个决策过程写清楚。

我写过一个"灵敏度分析"skill，正文核心是一棵决策树：

## 方法选择 - 如果模型参数少于10个，且需要快速筛选：用Morris筛选法 - 如果参数在10-30个之间，需要定量分析：用Sobol指数法 - 如果模型是线性的，且参数独立：用局部灵敏度分析（偏导数法） - 如果计算资源有限，且只需要排序：用傅里叶振幅灵敏度测试 ## 结果验证 - 检查灵敏度指数之和是否接近1（Sobol法） - 检查筛选结果是否与领域知识矛盾 - 用不同的随机种子跑三次，看结果是否稳定

这种决策树式的写法，模型读完之后能直接根据当前问题的特征选择方法，而不是随机挑一个。数学建模skill的另一个关键是包含验证步骤，因为建模结果的可信度比代码能不能跑更重要。

4.3 AI漫剧skill：创意流程与风格一致性的平衡

AI漫剧这个场景比较新，但需求很明确：用AI生成漫画或短剧内容时，保持角色、画风、叙事节奏的一致性。这类skill的设计难点在于，它既要给模型创意空间，又要约束输出不跑偏。

我的做法是把skill分成"硬约束"和"软引导"两部分。硬约束是必须遵守的，比如"主角的发色和瞳色在所有分镜中必须一致""每页分镜不超过6格"；软引导是建议性的，比如"对话气泡放在画面右上角更符合阅读习惯""转场可以用空镜或特写过渡"。

## 硬约束（必须遵守） - 角色外观参数：主角[发色:银白, 瞳色:冰蓝, 服装:黑色风衣] - 分镜数量：每页4-6格 - 对话长度：每格不超过20字 ## 软引导（建议遵循） - 情绪高潮页可以用整页单格 - 战斗场景优先使用对角线构图 - 日常场景多用水平构图

这种分层的写法，模型在执行时知道哪些不能碰、哪些可以灵活处理，生成的内容既稳定又不死板。

5. 安装、加载与跨工具使用的那些坑

5.1 手动安装GitHub上的skill：路径与权限问题

从GitHub上clone一个skill仓库到本地，然后放到正确的目录下，听起来简单，但实际操作中经常卡在几个地方。

第一个坑是目录层级搞错。很多skill仓库的结构是repo-name/skills/skill-name/SKILL.md，你如果直接把整个repo文件夹拷进.claude/skills/，模型扫描时可能找不到SKILL.md，因为中间多了一层。正确的做法是把包含SKILL.md的那个文件夹直接放到skills目录下。

第二个坑是文件权限。在Linux或macOS上，如果clone下来的文件权限是600（只有所有者可读写），某些工具可能读不到。用chmod -R 644把SKILL.md的权限改成可读，目录改成755。

第三个坑是换行符。Windows上编辑的SKILL.md如果用了CRLF换行，在某些解析器里可能导致frontmatter解析失败。用dos2unix转一下，或者在编辑器里设置成LF。

# 检查目录结构 ls -la .claude/skills/ # 应该看到类似这样的结构 # drwxr-xr-x skill-name/ # -rw-r--r-- SKILL.md # 修复权限 chmod -R 755 .claude/skills/ chmod 644 .claude/skills/*/SKILL.md # 转换换行符 find .claude/skills -name "SKILL.md" -exec dos2unix {} \;

5.2 跨工具使用：Claude Code、Codex、OpenCode的兼容性

Skills这个概念现在不止Claude一家在用，Codex、OpenCode等工具也在往类似的方向走。但不同工具对SKILL.md的解析规则有差异，直接拿同一个文件跨工具用，可能会遇到字段不识别、加载失败等问题。

我实测下来，兼容性最好的做法是保持frontmatter字段最小化，只用name和description这两个最通用的字段。其他工具特有的字段（比如某些工具支持的version、author、tags）放在正文里用普通文本写，不要放在frontmatter里。这样即使换工具，核心的name和description也能被识别，skill至少能被加载和路由。

如果要在多个工具间共享skill，可以用软链接的方式，把同一份SKILL.md链接到不同工具的目录下。这样改一处，处处生效。

5.3 加载失败的排查顺序

Skill没生效，按这个顺序排查，基本能定位到问题：

1. 确认文件路径和文件名：必须是skills/xxx/SKILL.md，文件名大小写敏感，不能是skill.md或Skill.md。
2. 确认frontmatter格式：---开头和结尾，中间是YAML格式，冒号后面要有空格。
3. 确认description的匹配度：换一个更具体的prompt试试，看是不是description写得太泛导致没触发。
4. 确认工具版本：有些旧版本不支持skills功能，升级到最新版再试。
5. 看日志：大部分工具在加载skill失败时会输出日志，开verbose模式跑一次，看有没有报错信息。

提示：如果所有步骤都检查了还是不行，把SKILL.md的内容精简到只剩name和description，看能不能加载。能加载说明是正文格式问题，不能加载说明是路径或工具配置问题。

6. 让skill真正产生复利：维护、迭代与团队共享

6.1 什么时候该更新skill

Skill不是写完就完了，它需要跟着项目一起演进。我判断一个skill该不该更新的信号有三个：

信号一：同一个坑踩了两次。如果某个错误在skill生效的情况下还是出现了，说明skill里的坑点描述不够醒目，或者流程步骤有遗漏。这时候要把那个坑点提到更靠前的位置，或者加粗强调。

信号二：流程步骤跟实际做法不一致了。比如项目从HAL库换成了LL库，skill里还写着"HAL_UART_Init"，模型就会生成过时的代码。这种不一致一旦发现就要立刻改，否则skill会变成负资产。

信号三：description的触发场景不够用了。你发现有些任务明明该调用这个skill，但模型没调用，检查后发现是description没覆盖到这类场景。这时候要扩充description的触发条件。

更新的频率不用太高，每个月回顾一次就够了。回顾的时候把最近一个月踩过的坑、改过的流程过一遍，该补的补进去。

6.2 团队共享时的版本管理

Skill文件应该跟代码一样纳入版本管理。放在项目仓库里的skill，跟着项目分支走；通用的skill，单独建一个仓库管理。

团队共享时有个实际问题：不同人的skill版本可能不一致。A同事更新了skill里的流程，B同事本地还是旧版，两人用同一个skill得到的结果不一样。解决办法是在skill的frontmatter里加一个版本号，或者在正文开头写一个更新日志。

--- name: frontend-component-review description: 当用户需要审查React组件代码时使用 --- # React组件审查 > 版本：1.2.0 > 更新：2025-01-15 增加hooks依赖检查项 ## 更新日志 - 1.2.0：增加useEffect依赖数组完整性检查 - 1.1.0：增加useCallback使用场景判断 - 1.0.0：初始版本

这样每次更新都有记录，团队成员拉取最新代码后能清楚知道改了什么。

6.3 从个人skill到团队资产

一个人写skill，受益的是自己；一个团队维护skill，受益的是所有人。从个人到团队，关键的一步是建立skill的评审机制。

我的做法是：任何人想新增或修改skill，先提一个PR，PR描述里写清楚"这个skill解决什么问题""为什么现有的skill不够用""验证过哪些场景"。然后由至少一个熟悉该领域的同事review，确认流程正确、坑点真实、description准确之后才能合并。

这个机制看起来有点重，但实际跑下来，它保证了skill库的质量。没有评审的skill库，很快就会变成一堆没人维护的过期文档，模型读了反而产生误导。

另外，团队skill库最好有一个索引文件，列出所有skill的名称、用途、负责人。这样新人进来能快速了解团队积累了哪些能力，也方便发现覆盖盲区。

# 团队Skill索引 | Skill名称 | 用途 | 负责人 | 最后更新 | |-----------|------|--------|----------| | stm32-driver-helper | STM32驱动代码生成与调试 | 张三 | 2025-01-10 | | math-modeling-sensitivity | 数学建模灵敏度分析 | 李四 | 2025-01-12 | | frontend-component-review | React组件代码审查 | 王五 | 2025-01-15 |

这个索引不用手动维护，写个脚本扫描skills目录自动生成就行。关键是让每个人都能看到团队积累了哪些能力，避免重复造轮子。

6.4 我踩过的一个真实坑：skill之间的冲突

最后分享一个我实际踩过的坑。有段时间我同时启用了两个skill，一个是"代码审查通用规范"，一个是"React组件审查"。结果模型在执行React组件审查时，被通用规范里的"所有函数必须写JSDoc注释"这条规则带偏了，生成了一堆React组件根本不需要的注释。

问题出在两个skill的适用范围有重叠，但没有定义优先级。后来我在React组件审查的skill里加了一句"本skill的规则优先于通用代码审查规范，冲突时以本skill为准"，问题就解决了。

这件事给我的教训是：skill不是越多越好，而是要理清它们之间的关系。当你有多个skill覆盖相近领域时，要么合并成一个，要么在description或正文里明确优先级。否则模型在多个skill之间摇摆，输出质量反而不如不用skill。

现在我的做法是，每新增一个skill，先检查现有skill库里有没有功能重叠的。如果有，要么扩展原有的，要么在新skill里写明与旧skill的关系。这样整个skill库才能保持清晰，模型调用时也不会犯迷糊。