企业官网建设流程全解析

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

第一次看到"skills"这个标题，很多人会懵——这词太泛了。但结合热搜词里的 Claude Code、Codex、plugin、agents 这些关键词，方向就很清楚了：这里说的 skills，指的是 AI 编程助手（尤其是 Claude Code 和 Codex 这类终端 Agent 工具）的技能扩展机制。简单说，就是给 AI 助手装"插件包"，让它从"能聊天"变成"能干活"。

我最早接触这个概念是在折腾 Claude Code 的时候。当时默认的 Claude Code 已经能读写文件、跑命令，但遇到特定任务——比如按团队规范生成代码、调用某个内部 API、执行一套固定的部署流程——它每次都要我重新解释一遍。后来发现 skills 机制就是解决这个问题的：把一套可复用的指令、脚本、资源打包成一个 skill，AI 在需要时自动加载。这跟传统 IDE 的插件思路类似，但载体是自然语言加脚本，而不是编译好的二进制。

为什么 skills 值得单独拿出来讲？因为它改变了 AI 助手的使用范式。没有 skills 的时候，你面对的是一个"通用助手"，能力上限取决于模型本身；有了 skills，你可以把领域知识、团队规范、私有工具链注入进去，让它变成"你的专属助手"。这个差别在实际项目里非常明显——我做过一个对比，同一个重构任务，裸用 Claude Code 花了 20 分钟反复沟通，配好 skill 之后 3 分钟一次过。

这篇文章面向三类人：一是刚装上 Claude Code 或 Codex、还在摸索怎么让它更好用的新手；二是想给团队搭建统一 AI 工作流的技术负责人；三是好奇 skills 底层机制、想自己开发 skill 的进阶用户。我会从概念、安装、配置、开发、排错几个层面展开，尽量把踩过的坑都写出来。

需要先说明一点：skills 这个概念在不同工具里叫法不完全一样。Claude Code 里叫 skills，Codex 里也有类似的扩展机制，社区里还有 agents、plugins 等相近说法。本文以 Claude Code 的 skills 为主线，因为它的机制最成熟、文档最全，其他工具的对应功能我会在相关章节做对比说明。

2. Claude Code 的 skills 机制拆解

2.1 skill 的本质：一个带元数据的文件夹

很多人以为 skill 是什么高深的东西，其实拆开看非常简单。一个 skill 就是一个文件夹，里面至少有一个SKILL.md文件，这个文件用 YAML frontmatter 声明元数据，用 Markdown 正文写指令。结构大概长这样：

my-skill/ ├── SKILL.md # 必需，技能定义 ├── scripts/ # 可选，辅助脚本 │ └── deploy.sh ├── references/ # 可选，参考文档 │ └── api-spec.md └── assets/ # 可选，模板资源 └── template.py

SKILL.md的头部大概是这样：

--- name: api-codegen description: 根据 OpenAPI 规范生成 TypeScript 客户端代码，遵循团队命名约定 --- # API 代码生成技能 当用户要求生成 API 客户端时，按以下步骤操作： 1. 读取项目根目录的 openapi.yaml 2. 运行 scripts/gen.sh 生成代码 3. 按 references/naming.md 的约定重命名 ...

关键点在于description字段。Claude Code 启动时会扫描所有已安装 skill 的 description，把它们拼进系统提示词。当你的请求和某个 description 语义匹配时，模型会主动加载那个 skill 的完整内容。这就是所谓的"渐进式披露"——平时只加载摘要，用到时才读全文，避免上下文爆炸。

2.2 为什么是 Markdown 而不是代码

这是 skills 设计里最聪明的地方。传统插件要用特定语言写、要编译、要处理版本兼容。skills 用 Markdown 写指令，本质上是"给 AI 看的文档"。这意味着：

• 零编译：改完直接生效，不用重启
• 零语言门槛：会写文档就能写 skill
• 可组合：skill 之间可以互相引用
• 可读性强：出问题直接看文件，不用调试

我一开始觉得这太"软"了，不够工程化。但用久了发现，AI 助手的核心能力本来就是理解自然语言，用自然语言给它下指令是最自然的。硬要用代码去描述"当用户说 X 时做 Y"，反而绕远了。

2.3 skill 和 plugin、agent 的区别

热搜词里 plugin、agents 和 skills 经常一起出现，容易混。我按自己的理解理一下：

简单类比：skill 是"技能手册"，plugin 是"新工具"，agent 是"实习生"。skill 告诉 AI 怎么做某件事，plugin 给 AI 一把新工具，agent 是让 AI 自己规划着做一整套事。三者可以叠加使用——一个 agent 可以调用多个 skill，skill 里可以调用 plugin 提供的工具。

2.4 官方市场和本地安装的取舍

Claude Code 有官方 skill 市场，社区也有一堆第三方 skill 仓库。我的建议是：核心流程用官方或自己写的，尝鲜用社区的。原因很简单，skill 本质上是给 AI 下指令，第三方 skill 的指令质量参差不齐，有的会覆盖你的项目规范，有的会引入不必要的步骤。

我踩过一次坑：装了个社区很火的"全栈开发"skill，结果它默认用 Jest 做测试，而我项目用的是 Vitest，每次生成测试都要手动改。后来我把那个 skill 的SKILL.md打开，删掉测试相关段落，改成引用项目自己的测试规范，问题就解决了。所以第三方 skill 不是不能用，而是要审一遍再装。

3. 安装与配置：从零跑通第一个 skill

3.1 环境准备里最容易忽略的两件事

安装 Claude Code 本身不复杂，官方文档写得很清楚。但有两个细节新手经常卡住：

第一，Node 版本。Claude Code 对 Node 版本有要求，太老的版本会报奇怪的错。我建议直接用 nvm 装最新的 LTS：

nvm install --lts nvm use --lts node -v # 确认版本

第二，终端编码。在 Windows 上，如果终端不是 UTF-8，skill 里的中文描述会乱码，导致匹配失败。PowerShell 里执行：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

或者在 Windows Terminal 的设置里把默认编码改成 UTF-8。这个坑我调了半天才定位到，因为报错信息完全不提编码。

3.2 skill 的存放位置与加载顺序

Claude Code 会从几个位置扫描 skill，优先级从高到低：

1. 项目根目录的.claude/skills/—— 项目级，只对当前项目生效
2. 用户目录的~/.claude/skills/—— 用户级，对所有项目生效
3. 官方市场安装的 —— 全局，但优先级最低

这个顺序很重要。如果你在项目里放了一个和用户级同名的 skill，项目级的会覆盖用户级的。我利用这个特性做了一件事：把通用的代码规范放在用户级，把项目特有的规范放在项目级，同名覆盖，切换项目时自动切换规范。

安装一个 skill 最直接的方式就是手动放文件夹：

# 项目级 mkdir -p .claude/skills/my-skill vim .claude/skills/my-skill/SKILL.md # 用户级 mkdir -p ~/.claude/skills/my-skill

放好之后不用重启，Claude Code 下次启动时会自动扫描。如果没生效，检查一下文件夹名和name字段是否一致——不一致会导致加载失败，而且不报错，只是静默忽略。

3.3 验证 skill 是否被正确加载

装完 skill 第一件事是验证。Claude Code 里有个命令可以列出当前加载的所有 skill：

/skills

如果列表里没有你的 skill，按这个顺序排查：

• 文件夹路径对不对（.claude/skills/不是.claude/skill/）
• SKILL.md文件名大小写对不对（必须全大写）
• frontmatter 格式对不对（---开头结尾，YAML 语法正确）
• description字段有没有写（没写 description 的 skill 不会被匹配）

我遇到过一次 skill 死活不加载，最后发现是SKILL.md里 frontmatter 的---后面多了一个空格，YAML 解析失败。这种问题没有报错，只能靠肉眼检查。

3.4 让 skill 真正被触发的技巧

skill 加载了不等于会被触发。触发靠的是 description 和用户请求的语义匹配。这里有几个实操技巧：

description 要写"什么时候用"，不是"这是什么"。对比一下：

• 差：description: 一个代码生成工具
• 好：description: 当用户要求根据 API 规范生成客户端代码、或提到 openapi/swagger 时使用

后者明确写了触发场景，匹配率高很多。

description 里放关键词。模型匹配时对关键词敏感。如果你的 skill 和"部署"相关，description 里就要出现"部署""deploy""发布"这些词。

避免 description 太泛。我见过一个 skill 的 description 是"帮助处理各种编程任务"，结果它几乎每次都被触发，把其他 skill 都挤掉了。description 越具体，触发越精准。

4. 自己写一个 skill：从需求到落地

4.1 先想清楚：什么任务值得做成 skill

不是所有事都值得做成 skill。我的判断标准是三条：

• 重复性高：一周至少用一次
• 步骤固定：每次流程基本一样
• 有领域知识：需要项目特有的规范或私有工具

举个例子，"生成 React 组件"值得做成 skill，因为团队有固定的目录结构、命名规范、样式方案。"解释这段代码"不值得，因为每次情况都不一样，直接问就行。

我给自己项目做的第一个 skill 是"新增 API 端点"。流程固定：在routes/下建文件、在index.ts注册、写对应的测试、更新 API 文档。以前每次都要跟 AI 解释一遍，做成 skill 后一句话搞定。

4.2 SKILL.md 的结构设计

一个高质量的SKILL.md通常包含这几块：

--- name: add-api-endpoint description: 当用户要求新增 API 端点、添加路由、或提到 routes 目录时使用 --- # 新增 API 端点 ## 前置检查 - 确认项目使用 Express + TypeScript - 确认 routes 目录存在 ## 执行步骤 1. 在 `src/routes/` 下创建 `<name>.route.ts` 2. 按 `references/route-template.md` 的模板填充 3. 在 `src/routes/index.ts` 注册路由 4. 在 `tests/routes/<name>.test.ts` 创建测试 5. 更新 `docs/api.md` ## 命名约定 - 文件名用 kebab-case - 路由路径用复数形式 - 测试文件与被测文件同名 ## 常见错误 - 忘记在 index.ts 注册，导致 404 - 测试没 mock 数据库，导致 CI 失败

注意"常见错误"这一节。这是 skill 里最有价值的部分，因为它把踩过的坑固化下来了。AI 读到这节，就会主动避开这些错误。

4.3 用脚本增强 skill 的能力

纯 Markdown 的 skill 只能"指导"AI，不能"执行"具体操作。要执行操作，得配合脚本。比如上面那个 skill，我可以加一个scripts/scaffold.sh：

#!/bin/bash # 用法: ./scaffold.sh <endpoint-name> NAME=$1 mkdir -p src/routes tests/routes cat > "src/routes/${NAME}.route.ts" <<EOF import { Router } from 'express'; const router = Router(); // TODO: 实现 ${NAME} 路由 export default router; EOF echo "已创建 src/routes/${NAME}.route.ts"

然后在SKILL.md里写"运行scripts/scaffold.sh <name>创建骨架"。这样 AI 就不用一步步手动建文件，直接调脚本，又快又不容易出错。

脚本要注意两点：一是加执行权限（chmod +x），二是路径用相对路径，因为 skill 被调用时工作目录可能变。

4.4 测试 skill 是否按预期工作

写完 skill 一定要测。测试方法是构造几个典型请求，看 AI 是否触发正确的 skill、是否按步骤执行。我一般测三类：

• 正向测试：明确提到 skill 相关关键词，应该触发
• 边界测试：语义相近但不该触发的请求，不应该触发
• 异常测试：前置条件不满足时（比如文件不存在），skill 是否优雅处理

我测过一个 skill，正向测试全过，但边界测试发现它对"删除 API 端点"也会触发，因为 description 里写了"API 端点"这个宽泛词。后来改成"新增 API 端点"才解决。

5. 踩坑实录：那些文档不会告诉你的问题

5.1 skill 冲突：两个 skill 抢同一个任务

最常见的问题是两个 skill 的 description 语义重叠，导致 AI 随机选一个，行为不稳定。我遇到过"代码审查"和"代码质量检查"两个 skill，功能高度重合，每次触发哪个全看运气。

解决办法有两个：一是合并成一个 skill，二是把 description 写得更精确，划清边界。我选了后者，把"代码审查"限定为"审查 PR 变更"，把"代码质量检查"限定为"检查整个文件的规范问题"，冲突就消失了。

5.2 上下文爆炸：skill 太多导致响应变慢

每个 skill 的 description 都会进系统提示词。装了几十个 skill 之后，光 description 就占了几千 token，导致每次对话的上下文被挤占，响应变慢，甚至触发模型的上下文限制。

我的做法是按项目精简。用户级只放 3-5 个真正通用的 skill，项目级放项目特有的。不用的 skill 及时删掉或移到备份目录。实测下来，把 skill 从 30 个减到 8 个，响应速度明显提升。

5.3 路径问题：skill 里的相对路径失效

skill 里的脚本如果用相对路径，在不同工作目录下调用会失败。我踩过一次：脚本里写./scripts/gen.sh，在项目根目录调用没问题，但在子目录调用就找不到文件。

解决办法是用$CLAUDE_SKILL_DIR环境变量（Claude Code 会注入），或者用绝对路径。更稳妥的做法是在SKILL.md里明确写"在项目根目录执行"，让 AI 先cd再执行。

5.4 权限问题：脚本没有执行权限

从 Git 拉下来的 skill，脚本的执行权限可能丢失。表现是 AI 调用脚本时报"Permission denied"。修复很简单：

chmod +x .claude/skills/*/scripts/*.sh

但要在团队里避免这个问题，最好在仓库里加个postinstall钩子自动加权限，或者在SKILL.md里写"如果脚本无执行权限，先 chmod"。

5.5 中文乱码：description 匹配失败

前面提过编码问题，这里再强调一次。如果SKILL.md是 GBK 编码，中文 description 会乱码，导致匹配失败。统一用 UTF-8，并且在编辑器里确认保存编码。VS Code 右下角可以看到当前编码，点一下就能改。

6. 进阶玩法：把 skills 用出花来

6.1 用 skill 固化团队规范

这是 skills 最有价值的用法。团队里每个人对规范的理解不一样，新人尤其容易跑偏。把规范写成 skill，AI 生成代码时自动遵守，比写文档有效得多。

我帮一个团队做过这件事：把他们的代码规范、目录结构、命名约定、测试要求全部写成 skill，放在项目仓库的.claude/skills/里。新人 clone 下来，Claude Code 自动加载，生成的代码直接符合规范。他们的 code review 时间缩短了大概 40%。

6.2 skill 链：让多个 skill 协同工作

skill 之间可以互相引用。比如一个"发布新版本"的 skill，可以依次调用"更新 changelog""打 tag""构建产物""推送"几个子 skill。这样复杂流程被拆成小块，每块独立维护，组合起来完成大任务。

实现方式是在SKILL.md里写"依次执行 skill A、skill B、skill C"。AI 会按顺序加载和执行。注意子 skill 的 description 要写清楚，否则 AI 可能找不到。

6.3 跨工具复用：Claude Code 和 Codex 的 skill 互通

Claude Code 和 Codex 的 skill 格式不完全一样，但核心思路相同。我做过一次迁移：把 Claude Code 的 skill 稍作调整，放到 Codex 的对应目录，大部分能直接用。主要差异在 frontmatter 字段名和触发机制上。

如果你同时用两个工具，建议把 skill 内容（Markdown 正文）和元数据（frontmatter）分开维护，用脚本生成两个工具各自的格式。这样改一次内容，两边都更新。

6.4 用 skill 做本地模型适配

热搜词里有"claude code 调用 lmstudio 的本地模型"，这其实和 skill 关系不大，但可以结合。本地模型的能力通常弱于云端模型，对指令的理解没那么精准。这时候 skill 要写得更"啰嗦"——把每一步都拆细，把可能的歧义都排除。我试过用本地模型跑同一个 skill，把步骤从 5 步拆到 12 步之后，成功率从 60% 提到了 90%。

7. 排查 skill 不生效的完整链路

skill 不生效是最让人抓狂的问题，因为往往没有报错。我整理了一套排查流程，按顺序走基本能定位：

第一步，确认 skill 被加载。运行/skills，看列表里有没有。没有的话，检查路径、文件名、frontmatter 格式。

第二步，确认 description 被读取。如果列表里有但触发不了，多半是 description 的问题。把 description 临时改成一个非常具体的关键词，测试能否触发。

第三步，确认触发条件。构造一个明确包含 description 关键词的请求，看是否触发。如果明确请求都不触发，说明 description 写得太泛或太窄。

第四步，确认执行过程。触发了但没按步骤走，说明SKILL.md正文的指令不够清晰。检查步骤是否有歧义、是否有前置条件没写。

第五步，确认脚本执行。步骤走了但脚本报错，检查路径、权限、依赖。在终端手动跑一遍脚本，看是否正常。

第六步，确认上下文。如果 skill 之前能用突然不能用了，可能是上下文被其他 skill 挤占。临时禁用其他 skill 测试。

这套流程我用了很多次，基本能在 10 分钟内定位问题。关键是要一步步排除，不要跳步。

8. 一些零散但有用的经验

关于 skill 的命名，我建议用动词开头，比如add-api-endpoint、generate-client、deploy-staging。这样 description 和 name 语义一致，匹配更准。

关于 skill 的粒度，我的经验是一个 skill 做一件事。我见过一个"全栈开发"skill，包含建表、写 API、写前端、写测试、部署，结果每次触发都执行一大堆不相关的步骤。拆成 5 个独立 skill 之后，按需触发，效率高多了。

关于 skill 的版本管理，建议和项目代码一起进 Git。这样团队共享，改动能追溯。用户级的 skill 可以单独建个仓库管理，用软链接连到~/.claude/skills/。

关于 skill 的调试，可以在SKILL.md里临时加一行echo "skill triggered"之类的标记，确认是否真的被加载。调试完删掉。

关于 skill 的安全性，第三方 skill 要审。skill 里的脚本会以你的权限执行，恶意脚本能干任何事。装之前至少把scripts/目录看一遍。

关于 skill 的性能，脚本尽量轻量。我见过一个 skill 每次触发都跑npm install，慢得要命。能缓存的就缓存，能跳过的就跳过。

最后说一个我自己的习惯：每做完一个重复性任务，就问自己"这个值不值得做成 skill"。如果答案是肯定的，当场就写。拖久了就忘了，下次又要重新解释一遍。skills 的价值在于积累，用得越久，你的 AI 助手就越懂你。