企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底在解决什么问题

最近半年，不管是在技术社区还是各种开发者群组里，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到：claude code skills、codex skills、skills推荐、好用的skills、skills开发、agent skills测试……一大串。很多人第一次看到会懵——这跟传统意义上的“技能”是一回事吗？不完全是。

在当下这个语境里，skills 指的是一套可复用、可组合、可被 AI 编程助手或智能体直接调用的能力封装单元。你可以把它理解成给 AI 助手准备的“工具包”或者“操作手册”：一个 skill 可能封装了“如何正确初始化一个前端项目”“如何按照团队规范生成 commit message”“如何调用某个内部 API 完成数据校验”这类具体能力。它跟传统 plugin 的区别在于，plugin 更多是扩展宿主程序的功能，而 skills 更偏向于告诉 AI 在什么场景下该做什么、怎么做、按什么顺序做。

为什么突然火了？因为 Claude Code、Codex、Cursor 这类工具已经从“补全代码”进化到了“自主执行任务”的阶段。你给一个 agent 一堆 skills，它就能像新员工拿着 SOP 一样干活。没有 skills 的 agent 就像让一个新人自由发挥——结果往往不可控。所以 skills 本质上是把人的经验、团队的规范、项目的约束，翻译成 AI 能稳定执行的指令集。

这篇文章适合谁看？如果你是刚接触 Claude Code 或 Codex 的开发者，想搞清楚 skills 到底怎么装、怎么用、怎么自己写，那这篇就是给你准备的。如果你已经在用这些工具但总觉得“AI 不听使唤”，那问题很可能就出在 skills 的配置上。下面我会从整体设计思路、核心细节、实操过程到常见问题，一层层拆开讲。

2. 整体设计思路：为什么 skills 是当前 AI 编程工具的关键拼图

2.1 从“提示词工程”到“能力工程”的转变

早两年大家聊的是 prompt engineering——怎么把话说得让模型听懂。但很快人们发现，光靠提示词不够稳定。同一个 prompt，今天跑通明天就翻车。原因很简单：提示词是“一次性”的，而实际开发任务是“重复性”的。你每天都在建项目、写测试、提交代码，每次都重新描述一遍规范，既浪费 token 又容易遗漏。

skills 的出现就是把这个过程工程化了。它把“怎么说”固化下来，变成可版本管理、可分享、可测试的资产。你可以把 skills 提交到 git 仓库，团队成员拉下来就能用同一套标准。这跟当年从手写构建脚本进化到用 Makefile、再进化到用 CI 配置是一个道理——把重复的智力活动沉淀成可复用的基础设施。

从热搜词里也能看出这个趋势：claude agent skills: a first principles deep dive、skills开发、agent skills测试，说明大家已经不满足于“用”，开始往“开发和测试”走了。这是一个技术方向成熟的标志。

2.2 skills 与 plugin、agents 的关系到底是什么

很多人搞不清这三个概念。我用一个生活化的类比来解释：

• agent是“员工”——它负责干活，有自主决策能力。
• plugin是“工具”——员工手里的螺丝刀、扳手，扩展的是物理能力。
• skills是“操作手册”——告诉员工什么场景下用哪个工具、按什么步骤、注意什么。

三者配合起来才完整。一个 agent 如果没有 plugin，它只能动嘴不能动手；如果没有 skills，它动手时可能乱来。热搜词里plugin、agents、skills经常一起出现，就是因为实际使用中它们本来就是一套组合拳。

具体到 Claude Code 和 Codex，skills 通常以文件或目录的形式存在，里面包含自然语言描述、示例、约束条件，有些还带可执行脚本。Agent 在规划任务时会检索相关 skills，然后按照里面的指引调用 plugin 完成任务。这个流程听起来简单，但实际配置时坑非常多，后面会详细讲。

2.3 为什么现在必须关注 skills 的本地化与私有化

热搜词里有一类很显眼：claude code 调用lmstudio的本地模型、codex接入deepseek、ubuntu配置claude code、claude code windows。这说明大量开发者已经在做本地化部署和私有模型接入了。原因不外乎几个：数据不能出内网、成本要控制、响应速度要快。

但本地化之后，官方市场里的 skills 不一定能用——有些依赖云端服务，有些需要特定 API。所以你必须学会自己写 skills、自己管理 skills 仓库。热搜词里claude 国内安装skills 官方市场、idea设置plugin中插件仓库地址、dsh plugin --profile web add dshmarket这些，都是在解决“怎么把 skills 生态搬到自己的环境里”这个问题。

我的建议是：不管你用的是云端还是本地模型，都尽早建立自己的 skills 仓库。哪怕一开始只有三五个，也比完全依赖官方市场强。因为 skills 的价值在于贴合你的项目，通用 skills 只能解决通用问题。

3. 核心细节解析：skills 的组成、加载机制与编写要点

3.1 一个标准 skill 到底包含哪些部分

不同工具对 skill 的格式定义略有差异，但核心结构大同小异。以 Claude Code 和 Codex 的常见实践来看，一个完整的 skill 通常包含以下部分：

很多人写 skill 只写“执行步骤”，结果 agent 经常在不该用的时候用、该用的时候不用。问题就出在触发条件和约束与禁忌没写清楚。Agent 不是人，它需要显式边界。

3.2 skills 的加载与检索机制

Agent 在执行任务时，并不是把所有 skills 都读一遍——那样 token 消耗太大。实际机制通常是两阶段检索：

第一阶段是粗筛。Agent 根据当前任务描述，跟所有 skill 的名称和描述做匹配，选出 top-N 个候选。这一步靠的是语义相似度，所以 skill 的名称和描述写得准不准，直接决定它能不能被选中。

第二阶段是精读。Agent 把候选 skill 的完整内容加载进上下文，然后按照里面的步骤执行。如果 skill 太长，可能被截断；如果步骤有歧义，agent 可能理解偏。

这个机制解释了一个常见现象：你写了一个很好的 skill，但 agent 从来不用。大概率是名称和描述没写好，粗筛阶段就被过滤掉了。解决办法很简单——把 skill 名称写成“动词+对象+场景”的格式，描述里包含用户可能说的关键词。比如不要叫“前端规范”，要叫“初始化 React 项目时应用团队 ESLint 与 Prettier 配置”。

3.3 编写高质量 skill 的三条铁律

根据我自己的踩坑经验，写 skill 有三条铁律，违反任何一条都会导致 skill 不可用或者效果大打折扣。

第一条：步骤必须可执行、可验证。不要写“优化代码结构”这种模糊指令，要写“检查 src 目录下所有 .ts 文件，确保每个导出函数都有 JSDoc 注释，缺少的自动补全”。Agent 需要明确的动作和判断标准。

第二条：每个 skill 只做一件事。我见过有人把“建项目+装依赖+配 CI+写文档”塞进一个 skill，结果 agent 执行到一半就乱了。正确做法是拆成四个 skill，用的时候按顺序调用。这跟 Unix 哲学一样——每个工具只做好一件事。

第三条：必须包含失败处理。真实环境里命令会报错、文件会不存在、网络会超时。Skill 里要写清楚“如果 X 失败，则尝试 Y；如果 Y 也失败，则停止并报告”。没有失败处理的 skill 在生产环境里就是定时炸弹。

提示：写完 skill 后，一定要用agent skills测试的思路做验证。可以手动构造几个典型场景，看 agent 是否能正确加载并执行。热搜词里专门有agent skills测试这个词，说明这已经是公认的必要步骤了。

4. 实操过程：从零搭建一套可用的 skills 工作流

4.1 环境准备与工具安装

不管你用 Claude Code 还是 Codex，第一步都是把基础环境搭好。热搜词里claude code安装、codex安装教程、codex安装包、claude code下载这些词搜索量很高，说明安装环节就卡住了不少人。

以 Claude Code 为例，在 Ubuntu 或 Windows 上的安装流程大致如下。Windows 用户建议用 WSL2，因为很多 skill 里的脚本是 bash 写的，原生 Windows 环境跑起来会有路径和换行符问题。

# 以 Ubuntu 为例，先确保 Node.js 版本 >= 18 node -v # 如果版本不够，用 nvm 管理 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 # 安装 Claude Code（具体命令以官方文档为准） npm install -g @anthropic-ai/claude-code # 验证安装 claude --version

Codex 的安装类似，但要注意热搜词里提到的codex无法加载组织设置、codex is ignoring 1 unrecognized configuration setting这类问题。前者通常是账号权限或网络配置问题，后者一般是配置文件里有拼写错误。建议安装完后先跑一个最小配置，确认能正常对话再往下走。

如果你要用本地模型，比如通过 LM Studio 或接入 DeepSeek，还需要额外配置 endpoint。热搜词里cc switch local proxy failed while handling codex endpoint /responses就是典型的 endpoint 配置错误。检查三点：地址是否带协议头、端口是否对、模型名称是否匹配。

4.2 创建你的第一个 skill

假设我们要写一个 skill，功能是“按照团队规范生成 Git commit message”。步骤如下：

首先在项目根目录创建 skills 目录（具体路径取决于工具，Claude Code 通常在.claude/skills/，Codex 在.codex/skills/）：

mkdir -p .claude/skills/commit-message

然后创建 skill 文件，通常是一个 Markdown 文件加可选的脚本：

--- name: 生成符合团队规范的 Commit Message description: 当用户要求提交代码或生成 commit message 时使用。基于 staged 的变更内容，按照 Conventional Commits 规范生成消息。 trigger: 用户说“提交”“commit”“生成提交信息”时触发 --- ## 执行步骤 1. 运行 `git diff --cached --stat` 获取已暂存的文件列表。 2. 运行 `git diff --cached` 获取具体变更内容。 3. 分析变更类型： - 新增功能用 feat - 修复 bug 用 fix - 文档变更用 docs - 重构用 refactor - 测试相关用 test 4. 生成格式为 `<type>(<scope>): <subject>` 的消息。 5. subject 不超过 50 个字符，使用中文，不以句号结尾。 6. 如果变更涉及多个类型，以主要变更为准。 ## 示例 输入：新增了用户登录接口 输出：feat(auth): 新增用户登录接口 输入：修复了分页参数越界问题 输出：fix(pagination): 修复分页参数越界问题 ## 约束 - 不要自动执行 git commit，只生成消息并展示给用户确认。 - 如果 staged 内容为空，提示用户先暂存变更。 - 不要编造变更内容，必须基于实际 diff。

这个 skill 虽然简单，但包含了名称、描述、触发条件、步骤、示例和约束，是一个结构完整的样板。你可以照着这个模板扩展出几十个 skill。

4.3 把 skills 组织成可维护的仓库

当 skill 数量超过十个，就需要考虑组织方式了。我的做法是按领域分目录：

skills/ ├── frontend/ │ ├── init-react-project/ │ ├── eslint-config/ │ └── component-generator/ ├── backend/ │ ├── api-scaffold/ │ └── db-migration/ ├── devops/ │ ├── ci-pipeline/ │ └── deploy-check/ └── common/ ├── commit-message/ └── code-review/

每个目录下放对应的 skill 文件。然后用 git 管理，团队成员通过 submodule 或直接 clone 的方式引入。热搜词里idea设置plugin中插件仓库地址、dsh plugin --profile web add dshmarket反映的就是这种“私有仓库”的需求——把 skills 当成内部资产来管理。

注意：skills 仓库里不要放敏感信息，比如 API key、内部地址。如果 skill 需要这些，用环境变量引用，并在文档里说明需要配置哪些变量。

4.4 在 Claude Code 和 Codex 中加载自定义 skills

不同工具的加载方式不同。Claude Code 通常会自动扫描 skills 目录，但有些版本需要显式配置。Codex 则可能需要在配置文件里声明 skills 路径。

以 Claude Code 为例，在项目根目录的.claude/config.json里可以指定：

{ "skills": { "paths": [".claude/skills", "./shared-skills"], "autoLoad": true, "maxCandidates": 5 } }

maxCandidates控制粗筛阶段返回多少个候选 skill。设太小可能漏掉相关 skill，设太大浪费 token。根据我的经验，5 到 8 之间比较平衡。

Codex 的配置类似，但字段名可能不同。热搜词里codex is ignoring 1 unrecognized configuration setting就是配置字段写错导致的。建议对照官方文档逐字检查，不要凭记忆写。

加载完成后，你可以用find skills或类似命令查看当前可用的 skill 列表。如果某个 skill 没出现，检查文件路径、格式和配置。

5. 常见问题与排查技巧实录

5.1 skill 不被加载或不被触发

这是最高频的问题。排查顺序如下：

我踩过最坑的一次是 skill 名称用了英文缩写，结果 agent 在中文语境下根本匹配不到。改成中文全称后立刻正常了。所以名称和描述的语言要跟用户实际使用的语言一致。

5.2 本地模型接入后的 skills 兼容问题

热搜词里claude code 调用lmstudio的本地模型、codex接入deepseek说明很多人已经在用本地模型了。但本地模型跟云端模型比，指令遵循能力通常弱一些。同样的 skill，云端模型能准确执行，本地模型可能跑偏。

应对策略有三个：一是把 skill 步骤写得更细，减少模型自由发挥的空间；二是降低单次任务的复杂度，把大 skill 拆成小 skill；三是在 skill 里增加“如果不确定，先询问用户”的兜底指令。

另外，本地模型的上下文窗口可能更小，skill 不能写太长。我一般控制在 500 字以内，超过就拆分。

5.3 多工具共存时的配置冲突

很多人同时用 Claude Code、Codex、Cursor，热搜词里cursor 怎么设置初始化默认打开时 windows 而不是agents、vscode配置claude code、idea使用skills都反映了这种多工具场景。不同工具的 skills 目录、配置文件、环境变量可能冲突。

我的做法是按工具分目录，用软链接共享通用 skill：

# 通用 skill 放在 ~/shared-skills # Claude Code 引用 ln -s ~/shared-skills .claude/skills/shared # Codex 引用 ln -s ~/shared-skills .codex/skills/shared

这样改一处，两边都生效。但要注意软链接在某些 Windows 环境下不好使，可以用 git submodule 替代。

5.4 排查工具与日志查看

当 skill 行为异常时，第一步是看日志。Claude Code 和 Codex 通常都有 verbose 模式：

# Claude Code 查看详细日志 claude --verbose # Codex 查看 skill 加载情况 codex --debug skills

日志里会显示哪些 skill 被检索到、哪些被加载、执行到哪一步失败。根据这些信息定位问题比瞎猜快得多。

提示：如果日志里出现unrecognized configuration setting，说明配置文件里有工具不认识的字段。要么删掉，要么升级工具版本。不要忽略这个警告，它可能导致整个配置块被跳过。

5.5 独家避坑清单

最后分享几条我在实际使用中总结的避坑经验，都是文档里不会写的：

• skill 里的命令要加超时。有些命令会卡住，比如等待用户输入。加timeout 30防止 agent 无限等待。
• 不要依赖 skill 的执行顺序。Agent 可能并行加载多个 skill，如果你的 skill 之间有依赖，要在描述里显式声明“必须在 X 之后执行”。
• 定期清理不用的 skill。skill 越多，粗筛越容易选错。我每个月会 review 一次，删掉三个月没触发过的。
• 给 skill 加版本号。在描述里写上v1.2，方便追踪哪个版本出了问题。
• 测试 skill 时用真实项目。玩具项目测不出问题，真实项目的复杂变更才能暴露 skill 的边界缺陷。

6. 进阶方向：从单机 skills 到团队级能力平台

当你把基础流程跑通之后，可以考虑往团队级能力平台的方向走。热搜词里langchain deep agents、agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这些看起来偏研究，但背后的思路对工程实践有启发：skills 作为 agent 的知识库，其质量和安全性直接影响 agent 的行为。

一个可行的进阶路径是：把 skills 仓库接入 CI，每次提交自动跑测试用例，确保 skill 不会因为修改而失效。再进一步，可以给 skill 加使用统计，看哪些 skill 高频使用、哪些从不触发，用数据驱动优化。

另一个方向是跨工具标准化。目前 Claude Code、Codex、Cursor 的 skill 格式还不统一，但趋势是往开放标准走。你可以把 skill 的核心逻辑写成与工具无关的 Markdown，然后用适配层转换成各工具需要的格式。这样换工具时不用重写。

我个人在实际操作中的体会是，skills 的价值不在于数量，而在于精准覆盖你日常最高频的那几个场景。与其写五十个没人用的 skill，不如把五个核心 skill 打磨到 agent 每次都能正确执行。这个投入产出比是最高的。