企业官网建设流程全解析

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

如果你最近在开发者社区、技术群或者社交平台上频繁刷到“skills”这个词，大概率不是指传统意义上的“技能”泛称，而是特指围绕Claude Code、Codex、Agents等智能编程助手构建的一套可插拔能力扩展机制。简单来说，skills 就是让 AI 编程助手从“只会聊天”变成“能按你的规矩干活”的那一层配置与脚本集合。它可能是一个封装好的提示词模板，也可能是一段带上下文注入的自动化流程，甚至是一组针对特定项目结构的操作指令集。

我最早接触这个概念是在给团队搭建内部编码助手的时候。当时大家用 Claude Code 或者 Codex 做代码补全、写单元测试、生成文档，效率确实有提升，但问题也很明显：每次都要重复交代项目背景、代码规范、目录结构，模型给的答案时好时坏，风格完全不统一。后来发现社区里已经有人在用“skills”的思路来解决这个问题——把项目约定、常用操作、领域知识打包成可复用的模块，让助手在特定场景下自动加载。这一下就把“每次重新调教”变成了“一次配置，长期复用”。

这篇文章适合三类人看：第一类是完全没接触过 Claude Code 或 Codex，但想搞清楚“skills”到底能干什么的开发者；第二类是已经在用这些工具，但还在靠手动复制粘贴提示词的进阶用户；第三类是想把 AI 助手接入团队工作流，需要一套可维护、可共享配置方案的技术负责人。我会从设计思路、核心细节、实操过程到常见问题，把 skills 这套东西拆开讲透，尽量让你看完就能动手配一套自己的。

2. 内容整体设计与思路拆解：为什么是 skills，而不是别的方案

2.1 从“提示词工程”到“能力封装”的必然演进

早期大家用 AI 编程助手，基本停留在“对话式提示词”阶段。比如你想让模型帮你写一个 React 组件，可能会输入：“你是一个资深前端，请按照 Airbnb 规范写一个带 TypeScript 的按钮组件，支持 loading 状态和 disabled 状态。” 这种方式的问题在于，每次都要重新描述一遍上下文，而且不同人写的提示词质量参差不齐，导致输出结果极不稳定。

skills 的核心思路就是把这类重复性的上下文描述、操作流程、约束条件从“每次输入”变成“一次定义、按需加载”。你可以把它理解成给 AI 助手装了一个“项目知识包”：当助手检测到你在处理某个特定任务时，自动把相关的规范、示例、甚至可调用的脚本注入到上下文中。这比单纯堆提示词要高效得多，因为它是结构化的、可版本管理的、可组合的。

我试过两种极端方案：一种是把所有规范写成一个超长提示词，每次对话都粘贴一遍；另一种是把规范拆成多个 skills，按场景加载。实测下来，后者在 token 消耗、响应速度和输出一致性上都明显更优。尤其是当项目变大、规范变多的时候，长提示词会迅速吃掉上下文窗口，而 skills 可以做到“用什么加载什么”。

2.2 为什么 Claude Code 和 Codex 成了 skills 的主要载体

Claude Code 和 Codex 这类工具跟普通聊天窗口最大的区别在于，它们直接运行在终端或 IDE 里，能读取项目文件、执行命令、查看 git 状态。这意味着 skills 不只是文本提示词，还可以包含“读取某个配置文件”“运行某个脚本”“检查某个目录结构”这样的动作。比如你可以定义一个 skill，让助手在生成数据库迁移文件之前，先自动读取schema.prisma并检查命名规范。

另一个原因是这些工具通常支持插件或扩展机制。虽然不同平台的叫法不一样，有的叫 plugin，有的叫 agent，但底层逻辑是一致的：允许用户把自定义能力挂载到助手的工作流里。skills 就是挂载内容的一种组织形式。社区里已经有人把常用的 skills 打包成市场或仓库，比如“前端开发 skills”“写论文的 skills”“安卓逆向 skills”等等，覆盖场景非常广。

2.3 方案选型：自己写还是用现成的

如果你刚开始接触，我建议先别急着从零写 skills。社区里已经有大量现成的配置可以参考，比如针对 React、Vue、Python 后端、数据科学等场景的 skills 包。你可以先拿一个现成的跑起来，看看它加载了哪些文件、注入了什么上下文、触发了什么动作，然后再根据自己的项目改。

自己写 skills 的成本主要在两个方面：一是要搞清楚目标工具的加载机制和配置格式，二是要把项目里的隐性知识显性化。前者是技术问题，后者是工程问题。我的经验是，先从最痛的一个点开始，比如“每次生成 API 接口都要手动补参数校验”，把这个场景做成一个 skill，跑通之后再逐步扩展。不要一上来就想着做一个大而全的 skills 库，那样很容易半途而废。

3. 核心细节解析与实操要点：skills 到底怎么写、怎么加载

3.1 skills 的基本结构：元数据、触发条件、上下文内容

虽然不同工具的 skills 格式有差异，但核心结构基本一致。一个典型的 skill 通常包含三部分：

• 元数据：名称、描述、版本、作者、适用场景。这部分决定了 skill 在列表里怎么展示、被搜索时能不能命中。
• 触发条件：什么情况下加载这个 skill。可以是文件类型匹配（比如.tsx文件）、目录匹配（比如src/components/）、命令匹配（比如用户输入了“生成组件”），也可以是手动指定。
• 上下文内容：真正注入给模型的内容。可以是纯文本规范、代码示例、检查清单，也可以是对外部文件的引用路径。

我自己的习惯是把每个 skill 写成一个独立目录，里面放一个skill.md或skill.json作为入口，再按需放一些辅助文件。这样版本管理方便，也容易分享给同事。

3.2 触发条件的设计：精准比宽泛更重要

触发条件是 skills 里最容易踩坑的地方。我见过有人把触发条件写得太宽，结果助手在任何场景下都加载一堆无关规范，反而干扰了正常输出。比如你写了一个“前端组件规范”的 skill，触发条件设成“所有.ts文件”，那后端代码也会被误伤。

比较稳妥的做法是按目录或按文件后缀组合匹配。比如：

{ "trigger": { "include": ["src/components/**/*.tsx", "src/components/**/*.vue"], "exclude": ["**/*.test.tsx", "**/*.stories.tsx"] } }

这样只有组件目录下的源文件才会触发，测试文件和故事文件不受影响。另外，触发条件最好支持手动覆盖，比如用户可以通过命令强制加载或跳过某个 skill，避免自动化逻辑在特殊情况下帮倒忙。

3.3 上下文内容的组织：分层注入，避免信息过载

上下文内容不是越多越好。模型能处理的上下文窗口有限，而且无关信息会稀释关键指令的权重。我的做法是把上下文分成三层：

• 第一层：硬性约束。比如“必须使用 TypeScript 严格模式”“禁止使用any”“组件必须导出为命名导出”。这些是每次都要强调的。
• 第二层：风格指南。比如命名规范、目录结构、注释要求。这些可以按需加载，不一定每次都要全量注入。
• 第三层：示例代码。给一两个正例和反例，让模型有参照物。示例不要太多，否则会占用大量 token。

实测下来，三层结构比一股脑全塞进去效果要好很多。尤其是当项目规范很多的时候，分层加载能让模型更聚焦在当前任务上。

注意：不要在 skill 里写与项目无关的通用知识，比如“什么是 React”这种。模型本身已经知道这些，写进去只会浪费上下文。

3.4 与 plugin、agent 的关系：别被名词绕晕

社区里经常混用 skills、plugin、agent 这几个词，其实它们描述的是不同层次的东西。plugin 通常是工具层面的扩展，比如给 IDE 装一个插件来支持某种语言；agent 是行为层面的抽象，比如一个专门负责代码审查的智能体；skills 则是能力层面的封装，是 agent 或助手可以调用的具体技能模块。

你可以这样理解：一个 agent 可能拥有多个 skills，而 plugin 是让 agent 能在特定环境里运行的底层支持。比如你有一个“代码审查 agent”，它可能加载了“安全审查 skill”“性能审查 skill”“风格审查 skill”，而这些 skill 又依赖某个 IDE plugin 来读取文件。搞清楚这层关系，配置的时候就不会乱。

4. 实操过程与核心环节实现：从零搭一套可用的 skills

4.1 环境准备：确认工具版本和配置目录

不同版本的 Claude Code 或 Codex 对 skills 的支持程度不一样。我建议先确认你用的工具版本，然后找到它的配置目录。以类 Unix 系统为例，常见路径是~/.config/下的某个子目录，Windows 则通常在%APPDATA%里。你可以通过工具的帮助命令或官方文档确认具体位置。

找到配置目录后，一般会有一个skills或plugins子目录。如果没有，手动创建一个即可。接下来就是往里面放你的 skill 定义文件。有些工具支持热加载，改完立即生效；有些需要重启会话。我建议第一次配置时重启一下，确保加载逻辑没有问题。

4.2 写第一个 skill：以“API 接口生成规范”为例

假设我们有一个 Node.js 后端项目，每次生成 API 接口都要遵循一套固定规范：使用 Express 路由、参数必须用 Joi 校验、返回值统一包装成{ code, data, message }格式。我们可以把这个规范写成一个 skill。

首先创建目录结构：

mkdir -p ~/.config/codex/skills/api-generator cd ~/.config/codex/skills/api-generator touch skill.json context.md examples.md

然后编辑skill.json：

{ "name": "api-generator", "description": "生成符合项目规范的 Express API 接口", "version": "1.0.0", "trigger": { "include": ["src/routes/**/*.ts"], "manual": true }, "context": ["context.md", "examples.md"] }

context.md里写硬性约束和风格指南：

# API 生成规范 - 使用 Express Router，不要用 app.get 直接挂载 - 每个接口必须定义 Joi schema，放在同目录的 `schemas/` 下 - 返回值统一为 `{ code: number, data: any, message: string }` - 错误处理使用项目已有的 `AppError` 类 - 异步接口必须用 `asyncHandler` 包装

examples.md里放一个正例：

import { Router } from 'express'; import Joi from 'joi'; import { asyncHandler } from '../utils/asyncHandler'; import { AppError } from '../utils/AppError'; const router = Router(); const createUserSchema = Joi.object({ name: Joi.string().required(), email: Joi.string().email().required(), }); router.post('/users', asyncHandler(async (req, res) => { const { error, value } = createUserSchema.validate(req.body); if (error) { throw new AppError(400, error.message); } const user = await userService.create(value); res.json({ code: 0, data: user, message: 'success' }); })); export default router;

配置完成后，在会话里手动加载这个 skill，然后让助手生成一个新接口，看看输出是否符合规范。如果不符合，就调整context.md里的措辞，或者补充更多示例。

4.3 参数计算与选择：token 预算怎么分配

skills 的上下文内容会占用模型的 token 预算。以常见的 128k 上下文窗口为例，如果项目代码本身已经占用了 60k，那留给 skills 的空间大概只有 60k 左右。我的经验是单个 skill 的上下文控制在 2k 到 5k token 之间，超过这个范围就要考虑拆分。

具体怎么估算？一个英文单词大约 1.3 个 token，一个中文字大约 1.5 到 2 个 token。你可以把context.md和examples.md的内容复制到 token 计算工具里跑一下。如果发现某个 skill 太大，就把它拆成多个小 skill，按更细的场景触发。比如“API 生成规范”可以拆成“路由规范”“校验规范”“返回值规范”三个独立 skill，按需组合。

4.4 实操现场记录：一次完整的 skill 加载与调试

我第一次配置 skills 的时候，遇到一个很典型的问题：skill 加载了，但助手好像“看不见”里面的约束。排查了半天，发现是触发条件写错了——我把include写成了src/routes/*.ts，但实际文件在src/routes/v1/*.ts，通配符没匹配上。改成src/routes/**/*.ts之后就正常了。

另一次是上下文内容太长，导致助手在生成代码时“忘记”了前面的约束。后来我把context.md精简到 1.5k token 以内，只保留最关键的几条，问题就解决了。这让我意识到，skills 的效果不取决于你写了多少，而取决于模型能记住多少。与其堆砌规范，不如把最重要的几条放在最前面，并用加粗或列表突出。

还有一个坑是编码问题。有些工具对非 ASCII 字符支持不好，中文内容偶尔会出现乱码。我的做法是尽量用英文写 skill 的元数据和触发条件，上下文内容可以用中文，但保存时确保是 UTF-8 编码。

5. 常见问题与排查技巧实录：踩过的坑和解决方案

5.1 常见问题速查表

5.2 独家避坑技巧：从实际项目中总结的几条经验

第一条：不要把所有规范都塞进一个 skill。我见过有人把整个团队的编码规范写成一个 10k token 的 skill，结果模型根本记不住，输出质量反而下降。正确的做法是按场景拆分，每个 skill 只解决一个具体问题。

第二条：触发条件宁窄勿宽。宽泛的触发条件会导致 skill 在不该加载的时候加载，干扰正常输出。比如“所有 TypeScript 文件”这种条件，基本等于全局加载，效果很差。建议精确到目录或文件名模式。

第三条：定期清理不再使用的 skill。项目在演进，规范也在变。过时的 skill 不仅占用空间，还可能和新的规范冲突。我一般每个月检查一次，把半年没用的 skill 归档或删除。

第四条：用版本控制管理 skills。把 skills 目录纳入 git 管理，这样团队成员可以共享同一套配置，出了问题也能回滚。我还会在 commit message 里写清楚这次改了什么、为什么改，方便追溯。

第五条：不要依赖 skills 做代码审查。skills 是辅助生成的，不是替代审查的。模型生成的代码仍然需要人工检查，尤其是安全相关的逻辑。我见过有人完全信任 skill 生成的代码，结果引入了一个 SQL 注入漏洞。这个教训很深刻。

5.3 性能优化：让 skills 加载更快、更准

如果你配置了很多 skills，可能会发现助手启动变慢，或者响应时间变长。这通常是因为加载逻辑在每次会话开始时扫描了所有 skill 文件。优化方法有几个：一是把不常用的 skill 设为手动加载，不参与自动扫描；二是把 skill 文件放在 SSD 上，减少 IO 延迟；三是定期合并重复的 skill，减少文件数量。

另外，有些工具支持 skill 的懒加载，也就是只有在触发条件满足时才读取文件内容。如果你的工具支持这个特性，一定要打开。实测下来，懒加载能把启动时间缩短一半以上。

6. 进阶玩法：把 skills 接入团队工作流

6.1 团队共享：用 git 子模块或包管理器分发

一个人用 skills 和团队用 skills 是两回事。个人用的时候，配置放在本地就行；团队用的时候，需要一套分发机制。我试过两种方案：一种是 git 子模块，把 skills 仓库作为子模块挂到每个项目里；另一种是内部 npm 包，把 skills 打包发布，通过npm install安装。

git 子模块的好处是版本锁定明确，每个项目可以用不同版本的 skills；缺点是更新麻烦，需要手动拉取。npm 包的好处是安装和更新方便，缺点是所有项目共用同一版本，不够灵活。我们最后选了混合方案：通用规范做成 npm 包，项目特有的规范放在项目仓库的.skills/目录里。

6.2 与 CI/CD 结合：在流水线里校验 skills 输出

skills 生成的代码最终要进入代码库，所以可以在 CI 流水线里加一道校验。比如用 ESLint 检查生成代码的风格，用单元测试检查功能正确性，用安全扫描检查潜在漏洞。如果校验不通过，就阻止合并，并提示开发者检查 skills 配置。

我还在流水线里加了一个步骤：统计 skills 的触发次数和生成代码的通过率。如果某个 skill 的通过率持续偏低，就说明它的上下文内容需要优化。这个数据驱动的方法比凭感觉调整要靠谱得多。

6.3 未来扩展：skills 与多模型切换

现在很多团队不只用一种模型，可能会根据任务类型切换 Claude、GPT 或其他模型。skills 的设计最好能兼容多模型，也就是把上下文内容和模型调用解耦。我的做法是把 skill 定义成纯文本加元数据，不绑定具体模型；然后在加载层根据当前模型做适配，比如调整提示词格式或 token 预算。

这样做的另一个好处是，当新模型出现时，不需要重写 skills，只需要在加载层做兼容即可。我试过把同一套 skills 从 Claude 切到另一个模型上，只改了加载配置，上下文内容基本没动，效果也能接受。

7. 我个人在实际操作中的体会

折腾 skills 这套东西大概有大半年了，最大的感受是：它不是一个“配好就完事”的工具，而是一个需要持续迭代的工作流。项目在变，规范在变，模型也在变，skills 必须跟着变。我现在的习惯是每次项目复盘的时候，顺便看一眼 skills 的使用情况，把过时的删掉，把新出现的痛点补上。

另一个体会是，不要追求“全自动”。skills 能帮你省掉很多重复劳动，但它不能替代你的判断。该审查的代码还是要审查，该写的测试还是要写。把 skills 当成一个靠谱的助手，而不是一个全能的替身，心态会好很多。

最后分享一个小技巧：如果你不确定某个 skill 该怎么写，就去社区里找现成的，拆开看它的结构和措辞。我最早就是靠模仿别人的 skill 文件入门的，改着改着就摸清套路了。现在社区里针对前端、后端、数据、运维等场景的 skills 都很丰富，拿来改比从零写快得多。