企业官网建设流程全解析

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

第一次看到"skills"这个标题，很多人会懵——这词太泛了，技能、能力、插件、扩展，什么都能套。但结合热搜词里高频出现的 Claude Code、Codex、plugin、agents 这几个词，方向其实很明确：这里说的 skills，指的是围绕 AI 编程助手（尤其是 Claude Code 和 Codex 这类终端/编辑器内的智能体工具）构建的可复用能力单元。

你可以把它理解成给 AI 助手装的"技能包"。原生模型再强，它也不知道你团队内部的代码规范、你们私有 API 的调用方式、你们部署流程里的那些约定俗成的步骤。skills 就是把这些"隐性知识"显性化、模块化，让 AI 在需要的时候自动加载、按你的方式干活。

我接触这块是从 Claude Code 开始的。当时最大的痛点不是模型不够聪明，而是每次都要重复交代同样的背景："我们项目用 pnpm 不用 npm""提交信息要遵循 Conventional Commits""测试文件放在tests目录下"。说一次两次还行，天天说就是折磨。后来发现 skills 机制能把这些固化下来，才算真正把 AI 助手用顺手了。

这篇文章适合三类人看：一是刚装上 Claude Code 或 Codex、还在摸索怎么让它"懂自己"的新手；二是已经用了一阵、但每次都要重复提示词、想提效的中级用户；三是想自己写 skills、做团队内部分享的进阶玩家。我会从概念讲到实操，再讲我踩过的坑，尽量让你少走弯路。

需要先说明一点：skills 这个概念在不同工具里叫法不完全一样。Claude Code 里叫 skills，Codex 生态里有时叫 plugin 或 agent 配置，社区里还有 superpower skills 这种说法。名字不同，本质是一回事——把可复用的指令、脚本、上下文打包，让 AI 按需调用。下面我主要围绕 Claude Code 的 skills 展开，因为它的机制最清晰、文档最全，其他工具的玩法可以类比迁移。

2. skills 的底层逻辑：为什么它比"写长提示词"更靠谱

2.1 提示词工程的瓶颈在哪里

大多数人用 AI 编程助手，第一反应是"把要求写详细点"。于是提示词越写越长，从一句话变成一段话，再变成一个小文档。这招在单次任务里有效，但放到日常开发里问题就来了。

首先是上下文浪费。你每次对话都塞一大段背景说明，这些 token 是要占窗口的。窗口就那么大，背景占多了，真正要处理的代码就没地方放了。其次是一致性差。今天你记得写"用 pnpm"，明天忘了，AI 就给你 npm install，你还得改。最后是无法沉淀。你写的提示词只存在于这次对话里，换个会话、换台机器就没了，团队里其他人更用不上。

我见过有人把提示词存成 txt 文件，每次手动粘贴。这算是土办法里的最优解了，但依然很笨——你得记得粘，得找对文件，还得祈祷内容没过时。

2.2 skills 解决的三个核心问题

skills 机制本质上是把"提示词"升级成了"可管理的资产"。它解决的核心问题有三个：

按需加载，不浪费上下文。skills 平时不占用对话窗口，只有当 AI 判断当前任务和某个 skill 相关时，才会把它的内容读进来。这就像你电脑里的软件，不用的时候不占内存，点了才启动。

版本化、可共享。skills 是文件，可以放进 Git 仓库，可以 review，可以迭代。团队里一个人写好，其他人 clone 下来就能用。这比在群里发"记得让 AI 用 xxx"靠谱一万倍。

结构化，能带脚本。一个 skill 不只是一段文字说明，它还可以包含可执行脚本、模板文件、参考文档。AI 需要跑个命令时，直接调用 skill 里的脚本，比它自己现编要稳得多。

提示：skills 不是万能的。它擅长的是"流程性、重复性、有明确规范"的任务。如果你的需求每次都不一样、高度依赖临场判断，那写 skill 的收益不大，老老实实对话就行。

2.3 一个类比：skills 就像给新同事的入职手册

我习惯用这个类比跟团队解释：AI 助手是个能力很强但完全不了解你公司的新同事。你不给它手册，它就只能按通用最佳实践干活，经常和你们的实际情况对不上。skills 就是那本入职手册——里面写着"我们代码怎么组织""提交怎么做""遇到某类问题找谁"。

区别在于，这本手册是"活"的。新同事（AI）会在遇到具体问题时，自动翻到对应的那一页，而不是从头读到尾。这就是按需加载的价值。

理解了这层逻辑，后面讲怎么装、怎么写、怎么用，就都是水到渠成的事了。

3. 环境准备：Claude Code 与 Codex 的安装路径差异

3.1 Claude Code 的安装与验证

Claude Code 的安装方式这几年变过几次，现在主流是通过 npm 全局安装。前提是你机器上有 Node.js，版本建议 18 以上。

npm install -g @anthropic-ai/claude-code

装完之后，在终端敲claude应该能进交互界面。第一次用会走登录流程，按提示操作即可。Windows 用户注意，官方对 Windows 的原生支持是逐步完善的，如果你在 Windows 上遇到路径或权限问题，可以考虑在 WSL 里跑，体验会顺很多。

验证安装是否成功，除了能进界面，还可以看版本：

claude --version

我踩过的一个坑是：全局装完之后，在某些 shell 配置里claude命令找不到。这通常是 PATH 没刷新，重开终端或者手动 source 一下配置文件就好。别急着重装，先排查 PATH。

3.2 Codex 的安装与常见报错

Codex 这边情况稍微复杂点，因为它有多个"化身"——有 OpenAI 官方的 CLI 工具，也有社区基于 API 做的各种封装。热搜词里出现的"codex安装教程""codex安装包""codex官网下载"说明很多人卡在第一步。

官方 CLI 一般也是 npm 或 pip 安装。装完之后常见的报错有两类：

一类是认证相关。比如提示组织设置问题、订阅访问被禁用之类。这类基本是账号权限或配置没弄对，检查你的 API key、组织配置，确认账号有对应权限。

另一类是网络请求失败。热搜里那个 "cc switch local proxy failed while handling codex endpoint /responses" 就是典型。这种报错通常出现在你配置了某种本地转发或代理设置、但配置本身有问题的时候。排查思路是：先确认你的网络配置是否必要，如果不需要就走直连；如果确实需要，检查端口、地址、协议是否匹配。

注意：涉及网络配置的部分，我建议优先用官方推荐的方式，不要随意套用网上来路不明的配置。配置错了轻则报错，重则把简单问题搞复杂。

3.3 编辑器集成：VS Code 与 IDEA

很多人不满足于终端，想把 AI 助手接进编辑器。VS Code 这边，Claude Code 有对应的扩展，装完之后可以在编辑器内直接调用。IDEA 用户则更多是通过插件市场找相关插件。

这里有个高频坑：插件仓库地址配置。热搜里"idea设置plugin中插件仓库地址"就是这个。如果你在公司内网，默认的插件市场可能访问不了，需要配内部镜像地址。配置位置在 Settings 里的 Plugins 相关选项，具体路径各版本略有差异，找不到就搜"plugin repository"。

VS Code 配置 Claude Code 时，另一个常见需求是接本地模型。热搜里"claude code 调用lmstudio的本地模型"就是这个场景。思路是把 Claude Code 的请求指向本地 LM Studio 暴露的接口。这需要改配置里的 base URL 和模型名。本地模型的好处是数据不出机器、不花钱，代价是能力通常不如云端大模型，复杂任务上差距明显。

4. skills 的目录结构与加载机制

4.1 一个 skill 长什么样

Claude Code 的 skills 通常放在特定目录下，每个 skill 一个文件夹，里面至少有一个描述文件（一般是 markdown 格式，带 frontmatter 元数据），还可以带脚本、模板、参考文档。

一个典型的 skill 目录大概是这样：

my-skill/ SKILL.md # 主描述文件，含元数据和指令 scripts/ helper.sh # 可执行脚本 templates/ commit.txt # 模板文件 reference.md # 补充参考

SKILL.md开头的 frontmatter 一般包含 name、description 这类字段。description 特别关键——AI 就是靠它判断"当前任务要不要加载这个 skill"。写得太模糊，AI 该用的时候不用；写得太宽泛，不该用的时候乱用。

4.2 加载是怎么触发的

这是很多人搞不清的地方。skills 不是全部一次性读进上下文的，那样窗口早爆了。它的机制是：AI 先看到所有 skills 的 name 和 description（这部分很轻量），然后根据当前对话内容判断哪些相关，再把相关的 skill 完整内容读进来。

所以 description 的写法直接决定了 skill 的"命中率"。我的经验是：description 里要包含触发场景的关键词。比如一个处理数据库迁移的 skill，description 里就该出现"migration""schema change""数据库变更"这类词，这样用户一提到相关任务，AI 就能对上号。

4.3 全局 skills 与项目 skills

skills 一般分两个层级：全局的和项目级的。全局的放在用户目录下，所有项目都能用；项目级的放在项目仓库里，只对这个项目生效。

怎么选？我的原则是：通用规范放全局，项目特有逻辑放项目级。比如"提交信息格式"这种全公司统一的，放全局；"这个项目的 API 网关怎么调"这种只对本项目有意义的，放项目级。

项目级 skills 跟着代码走，好处是新人 clone 下来就自带，不用额外配置。这也是我推荐团队把 skills 纳入版本管理的原因。

5. 手写第一个 skill：从需求到落地

5.1 选一个值得做成 skill 的场景

别一上来就搞复杂的。选场景的标准是：重复出现、有明确规范、你每次都要交代。我第一个 skill 做的是"提交信息规范"，因为团队要求 Conventional Commits，而我每次让 AI 提交都要提醒一遍。

判断一个场景值不值得做成 skill，问自己三个问题：这事我一周要交代几次？交代的内容是不是基本固定？做错了会不会有实际影响？三个都是"是"，那就值得。

5.2 写 description 的门道

前面说了 description 决定命中率。具体怎么写？我的模板是："当用户需要做 X 时使用本 skill，本 skill 会按 Y 规范完成 Z"。

举个例子，提交信息 skill 的 description 可以写成："当用户需要提交代码、生成 commit message 或执行 git commit 时使用。本 skill 会按 Conventional Commits 规范生成提交信息，包含 type、scope、description 三部分。"

这样写，用户一说"帮我提交"，AI 就能匹配上。如果只写"提交相关"，太模糊，可能匹配不上也可能乱匹配。

5.3 正文指令的写法

description 之后是正文，也就是 AI 加载 skill 后要遵循的具体指令。这部分要写得具体、可执行、有例子。

还是拿提交信息举例，正文里我会写清楚：type 有哪些可选值（feat、fix、docs、refactor 等），scope 怎么填，description 用什么语气，正文和 footer 什么情况下需要。最好再给两三个正例和反例。

反例特别有用。AI 看到"不要写成这样"的具体例子，比看十条抽象规则都管用。我一般会放一个"错误示范"和一个"正确示范"对照。

5.4 给 skill 加脚本

纯文字指令能解决大部分问题，但有些任务需要确定性——比如格式化、校验、生成文件。这时候给 skill 配脚本就很有价值。

脚本可以是 shell、Python、Node，看你的技术栈。关键是脚本要幂等、有清晰输出、出错有提示。AI 调用脚本后，会根据输出决定下一步。如果脚本静默失败，AI 就懵了。

我有个 skill 里放了个校验脚本，检查提交信息格式。AI 生成信息后先跑脚本，不通过就自己改，改到通过为止。这比让 AI"自己检查"可靠多了。

6. 实测中那些文档没写的坑

6.1 description 写太宽，skill 被乱触发

我早期有个 skill 的 description 写得太泛，结果 AI 在很多不相关的任务里都把它加载进来，白白占上下文，还偶尔干扰判断。后来把 description 收窄，明确写清"仅在 X 场景下使用"，问题就解决了。

教训是：宁可窄一点，也不要宽。窄了顶多是该用的时候没自动用，你手动提一句就行；宽了是到处乱用，反而添乱。

6.2 脚本路径用相对路径，换机器就挂

skill 里的脚本如果用了绝对路径，换台机器、换个用户目录就找不到。一定要用相对于 skill 目录的路径，或者用环境变量。这个坑我踩过一次，本地好好的，同事拉下来直接报错，排查半天才发现是路径写死了。

6.3 中文内容在部分环境下的编码问题

如果你的 skill 里有中文，在某些终端或编辑器里可能出现乱码。稳妥做法是确保文件用 UTF-8 编码保存，脚本里处理文本时显式指定编码。这个不是 skills 特有的问题，但确实容易在跨平台协作时冒出来。

6.4 更新 skill 后没生效

改完 skill 文件，有时候 AI 还是按老版本干活。这通常是缓存问题。多数工具会在新会话里重新读取，所以改完 skill 后开个新会话试试。如果还不行，检查是不是改错了文件位置——全局和项目级目录容易搞混。

6.5 别把 skill 当垃圾桶

见过有人把所有零碎要求都塞进一个 skill，结果这个 skill 又大又杂，加载慢、命中率还低。skill 应该单一职责，一个 skill 干好一件事。需要多个能力时，拆成多个 skill，让 AI 按需组合。

7. 进阶玩法：skills 与 agents 的配合

7.1 agent 和 skill 的分工

热搜里 agents 出现频率很高。简单说，agent 是"干活的角色"，skill 是"干活的方法"。一个 agent 可以调用多个 skill，就像一个人会多种技能。

比如你有个"代码审查 agent"，它可能调用"安全审查 skill""风格检查 skill""测试覆盖检查 skill"。每个 skill 专注一件事，agent 负责编排。

7.2 用 skills 给 agent 补能力

原生 agent 的能力是固定的，但通过挂载 skills，你可以给它扩展。这有点像给游戏角色装装备。同一个 agent，装了不同的 skills，就能适应不同项目。

我现在的做法是：维护一套通用 skills，然后针对不同项目组合出不同的 agent 配置。新项目来了，挑几个 skill 一挂，agent 就"懂"这个项目了。

7.3 团队协作中的 skills 管理

团队用 skills，最大的挑战不是技术，是维护。谁负责更新？什么时候 review？版本怎么管？

我的建议是：把 skills 当代码管。放 Git 仓库，走 PR 流程，有变更记录。指定一两个人做 maintainer，负责合并和发布。定期清理过时的 skill，别让仓库变成垃圾场。

另外，skills 的文档要跟上。每个 skill 除了给 AI 看的指令，最好还有给人看的说明——这个 skill 干什么、怎么用、有什么限制。不然新人看到一堆 skill 文件夹，完全不知道从哪下手。

8. 我个人的几条实操心得

用了一段时间 skills，有几个体会想分享。

先手动跑通，再固化成 skill。别一上来就写 skill，先手动把流程走几遍，确认稳定了、规范清晰了，再写成 skill。不然你固化的是一个还没想清楚的流程，后面改起来更麻烦。

skill 要短小精悍。我见过写了几千字的 skill，AI 加载后反而抓不住重点。好的 skill 应该像好的函数——短、职责单一、意图明确。细节可以放参考文档里，让 AI 需要时再读。

定期回顾命中率。用一阵子后，回头看看哪些 skill 经常被触发、哪些几乎没用过。没用的要么删掉，要么说明 description 写得不对。这个回顾很重要，不然 skills 越堆越多，实际有效的没几个。

别追求一步到位。skills 是迭代出来的。第一版能跑就行，用着用着发现哪里不顺再改。我现在的几个核心 skill 都改过七八版了，每版都是被实际问题逼出来的。

跨工具的思路可以迁移。Claude Code 的 skills 玩明白了，Codex 那边的 plugin、agent 配置理解起来就快。核心都是"把可复用能力模块化、按需加载"，具体 API 和目录结构不同而已。所以别纠结学哪个，先把一个吃透。

最后说个我最近在试的方向：把 skills 和项目的 CI 流程结合。比如提交前自动跑 skill 里的校验脚本，不通过就拦住。这样 skills 不只是"给 AI 看的"，还成了"给流程用的"，价值又大了一层。这个还在摸索，等跑顺了再细说。