企业官网建设流程全解析

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

最近半年，不管是在技术社区还是开发者群聊里，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到：skills、Claude Code、Codex、plugin、agents、find skills、skills推荐、codex skills、claude agent skills……这些词扎堆出现，说明一件事：围绕 AI 编程助手的能力扩展，正在从“模型本身有多强”转向“怎么让模型按我的方式干活”。

我最早接触这个概念是在折腾 Claude Code 的时候。当时我的诉求特别朴素：每次让 AI 帮我写代码，它都要重新理解一遍我的项目结构、代码规范、提交习惯，烦得要命。后来发现 Claude Code 支持一种叫 skills 的机制，可以把这些“重复交代的上下文”固化下来，变成一个可复用的能力单元。再后来 Codex 也跟进了类似的设计，plugin、agents 这些词开始混在一起用，很多人就懵了——skills 到底是什么？它和 plugin、agent 有什么区别？为什么有人把它叫“superpower skills”？

用一句话说清楚：skills 是给 AI 编程助手用的“技能包”，把特定场景下的指令、工具调用、上下文约束打包成一个可被自动识别和加载的模块。你可以把它理解成给 AI 装的一个“插件”，但比传统插件更轻、更偏“行为指导”而不是“功能扩展”。它解决的问题是：让 AI 在特定任务上表现得更像“一个懂行的老手”，而不是“一个什么都知道一点但什么都不精的实习生”。

这篇文章适合谁看？如果你是刚接触 Claude Code 或 Codex 的新手，想搞清楚 skills 到底怎么装、怎么用、怎么自己写，那这篇就是给你准备的。如果你已经在用这些工具，但总觉得“AI 干活不够顺手”，那 skills 很可能就是你缺的那块拼图。下面我会从设计思路、核心机制、实操步骤、常见坑四个层面，把这件事讲透。

2. skills 的整体设计与思路拆解

2.1 为什么是“技能”而不是“插件”或“代理”

先厘清一个容易混淆的点。plugin（插件）通常指的是给宿主程序增加新功能的模块，比如给 IDE 加一个代码格式化按钮。agent（代理）通常指的是一个能自主规划、调用工具、完成多步任务的智能体。而 skills 的定位介于两者之间：它不增加新功能，也不自主规划，它做的是“在特定场景下，告诉 AI 应该怎么思考、怎么调用已有工具、遵守什么约束”。

这个定位非常关键。我见过不少人一上来就想用 skills 实现“自动帮我部署上线”，结果发现 skills 根本不做这种事——那是 agent 的活。skills 更像是一份“岗位说明书”：当用户提出某类需求时，AI 应该按照这份说明书里的流程、规范、注意事项来执行。比如一个“代码审查 skill”，它不会帮你改代码，但它会告诉 AI：审查时要先看命名规范，再看边界条件，最后看测试覆盖，输出格式必须是“问题-位置-建议”三段式。

为什么这样设计？因为大模型的能力已经足够强，缺的不是“能不能做”，而是“做得稳不稳、符不符合我的要求”。skills 通过约束输入和输出，把 AI 的行为收敛到一个可控范围内。这比训练一个专用模型便宜得多，也比写一堆 prompt 模板优雅得多。

2.2 skills 和 Claude Code、Codex 的关系

Claude Code 和 Codex 是两个不同的 AI 编程助手产品，但它们在 skills 这件事上的思路高度一致：都支持通过文件或配置定义技能，都支持在对话中自动或手动触发技能，都强调技能的可组合性。区别在于实现细节和生态成熟度。

Claude Code 的 skills 更偏向“项目级配置”，你可以在项目根目录放一个 skills 目录，里面按技能名组织文件，AI 在读取项目上下文时会自动加载。Codex 的 skills 则更偏向“会话级配置”，你可以在对话开始时指定启用哪些技能，或者通过 plugin 机制动态加载。热搜词里出现的codex skills、claude agent skills、find skills这些，本质上都是在问“怎么找到、怎么装、怎么用”。

还有一个热词叫superpower skills，这个说法我最早是在一些开发者分享里看到的。它指的其实不是某个官方功能，而是把多个基础 skill 组合成一个高阶 skill，让 AI 在复杂任务上表现出“超能力”。比如把“读代码”“写测试”“跑测试”“改代码”四个 skill 串起来，形成一个“自动修复测试失败”的 superpower skill。这个思路很实用，后面我会专门讲怎么组合。

2.3 方案选型：为什么用文件而不是数据库

如果你去看 Claude Code 或 Codex 的 skills 实现，会发现它们几乎都用文件系统来存储技能定义，而不是数据库或远程服务。这个选择背后有几个考量。

第一，可版本控制。技能定义是文本文件，可以跟着项目一起提交到 Git，团队成员拉下来就能用，变更历史一目了然。第二，可读可改。开发者可以直接用编辑器打开技能文件，改一行保存就生效，不需要重启服务或重新编译。第三，低耦合。技能文件不依赖特定运行时，换一个 AI 助手只要格式兼容就能复用。第四，便于分享。热搜词里skills推荐、find skills说明大家有分享和发现技能的需求，文件形式天然适合打包和分发。

我实测下来，这种设计在团队协作场景下优势特别明显。我们团队把代码规范、提交信息格式、review 清单都写成了 skill 文件，新同事入职第一天拉下代码，AI 助手就自动按团队规范干活，省掉了大量“口头交代”的成本。

3. 核心细节解析与实操要点

3.1 skill 文件的基本结构

不同工具的 skill 文件格式略有差异，但核心字段大同小异。以 Claude Code 为例，一个典型的 skill 文件通常包含以下几个部分：

• name：技能名称，用于触发和引用，建议用英文小写加连字符，比如code-review。
• description：技能描述，AI 用它来判断什么时候该加载这个技能，所以要写得具体，包含触发场景关键词。
• instructions：核心指令，告诉 AI 具体怎么做，可以包含步骤、约束、输出格式。
• tools：可选，声明这个技能会用到哪些工具，比如读文件、跑命令。
• examples：可选，给几个输入输出示例，帮助 AI 理解预期行为。

Codex 的格式更偏向 JSON 或 YAML 配置，字段名可能叫id、trigger、actions，但逻辑是一样的。我建议你先从官方文档给的模板改起，不要一上来就自己造格式，容易踩兼容性的坑。

注意：description 字段是触发准确率的关键。写得太宽泛，AI 会在不相关场景乱加载；写得太窄，该用的时候又不触发。我的经验是，description 里至少包含“什么时候用”和“解决什么问题”两个信息。

3.2 触发机制：自动还是手动

skills 的触发方式主要有两种：自动触发和手动触发。自动触发靠的是 AI 对用户输入和 description 的语义匹配，比如你说“帮我看看这段代码有没有问题”，AI 匹配到code-review技能的 description 里有“代码审查”“问题检查”等词，就会自动加载。手动触发则是用户显式指定，比如在 Claude Code 里输入/skill code-review，或者在 Codex 里用@skill语法。

两种方式各有适用场景。自动触发适合高频、通用的技能，比如代码格式化、命名规范检查。手动触发适合低频、需要明确意图的技能，比如“生成数据库迁移脚本”这种一旦误触发后果比较严重的。我个人的做法是：通用技能开自动，危险技能只开手动。这样既省事又安全。

还有一个细节：多个技能同时被触发时，加载顺序会影响结果。Claude Code 默认按技能名称字母序加载，Codex 默认按声明顺序加载。如果你有技能之间存在依赖，比如test-fix依赖run-test，那就要在配置里显式声明依赖关系，或者干脆合并成一个技能。

3.3 技能的组合与复用

单个技能能做的事有限，真正体现威力的是组合。热搜词里superpower skills说的就是这个。组合方式有两种：串行组合和并行组合。

串行组合是把多个技能按顺序执行，前一个的输出作为后一个的输入。比如“读代码 → 找问题 → 改代码 → 跑测试”就是典型的串行。并行组合是多个技能同时作用于同一个输入，比如“安全检查”和“性能检查”可以同时跑，最后合并结果。

实现组合的关键是定义清楚技能之间的接口。如果find-bug技能输出的是自然语言描述，而fix-bug技能期望的是结构化的问题列表，那组合就会失败。我的做法是：在技能定义里明确写出输入格式和输出格式，最好用 JSON schema 约束。这样组合起来就像搭积木，不会出现“插不上”的情况。

提示：组合技能时，建议先用小规模任务验证接口是否匹配，再放到大任务上跑。我踩过一次坑，两个技能单独跑都没问题，组合起来因为输出格式差了一个字段，导致整个流程卡死，排查了半天。

3.4 技能的市场与发现

热搜词里find skills、skills推荐、claude 国内安装skills 官方市场这些，反映的是大家对“去哪找现成技能”的需求。目前 Claude Code 和 Codex 都有官方的技能市场或示例库，社区也有不少人在分享自己写的技能。

找技能的渠道主要有几个：官方文档的示例库、GitHub 上的 awesome-skills 类仓库、技术社区里的分享帖。我建议优先用官方示例，因为格式和兼容性最有保障。社区技能质量参差不齐，用之前一定要看 description 和 instructions，确认没有奇怪的依赖或危险操作。

安装技能的方式通常是：下载技能文件，放到项目的 skills 目录，或者通过命令行工具安装。热搜词里dsh plugin --profile web add dshmarket这种命令，就是某种技能管理工具的安装指令。不同工具命令不同，但思路一样：把技能文件放到 AI 助手能读到的位置。

4. 实操过程与核心环节实现

4.1 环境准备：Claude Code 和 Codex 的安装

在折腾 skills 之前，得先把宿主工具装好。Claude Code 和 Codex 的安装方式不太一样，我分别说一下。

Claude Code 的安装，官方推荐用 npm 全局安装：

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

装完之后在项目目录下运行claude就能启动。如果你在 Windows 上，建议用 WSL 或者 Git Bash，原生 CMD 有时候会有路径问题。热搜词里claude code windows、claude code安装、ubuntu配置claude code这些，说明跨平台安装是大家常问的。我的经验是：Linux 和 macOS 最省心，Windows 用 WSL 最稳。

Codex 的安装，官方提供了安装包和命令行两种方式。命令行方式通常是：

npm install -g @openai/codex

或者从官网下载对应平台的安装包。热搜词里codex安装包、codex下载、codex官网下载、codex安装教程出现频率很高，说明很多人卡在第一步。这里提醒一句：一定要从官方渠道下载，第三方渠道的安装包有被篡改的风险。

装完之后需要登录。Claude Code 用 Anthropic 账号登录，Codex 用 OpenAI 账号登录。热搜词里codex登录、your organization has disabled claude subscription access这些，反映的是登录和权限问题。如果遇到组织禁用的情况，需要联系管理员开通，或者用个人账号。

4.2 创建第一个 skill：从代码审查开始

环境准备好之后，我们来创建一个最简单的 skill：代码审查。这个技能的目标是让 AI 在你说“审查代码”时，按照固定流程检查代码并输出结构化结果。

第一步，在项目根目录创建 skills 目录：

mkdir -p .claude/skills

不同工具的技能目录名可能不同，Claude Code 默认是.claude/skills，Codex 可能是.codex/skills，具体看官方文档。

第二步，创建技能文件code-review.md：

--- name: code-review description: 当用户要求审查代码、检查代码问题、review 代码时使用。适用于函数、类、模块级别的代码审查。 tools: - read_file - search_code --- # 代码审查流程 1. 先通读代码，理解整体意图。 2. 检查命名规范：变量、函数、类名是否清晰达意。 3. 检查边界条件：空值、越界、异常路径是否处理。 4. 检查错误处理：异常是否被捕获，错误信息是否有用。 5. 检查测试覆盖：关键路径是否有测试。 6. 按以下格式输出： - 问题：一句话描述 - 位置：文件:行号 - 建议：具体修改建议

第三步，保存文件，然后在对话里说“帮我审查一下这个文件”，AI 应该会自动加载这个技能并按流程执行。

这里有几个细节要注意。description 里要包含触发词，比如“审查”“检查”“review”，这样 AI 才能匹配到。instructions 要分步骤，不要写成一大段，AI 对有序列表的理解更准确。输出格式要明确，否则 AI 每次输出的结构都不一样，没法程序化处理。

4.3 参数计算与选择：技能粒度怎么定

技能粒度是个很容易踩坑的地方。粒度太粗，一个技能干太多事，AI 容易漏步骤；粒度太细，技能太多，触发和管理都麻烦。我的经验是：一个技能对应一个明确的、可独立验证的任务。

怎么判断“可独立验证”？就是你能用一句话说清楚“这个技能做完之后，怎么算成功”。比如“代码审查”技能，成功标准是“输出了结构化的问题列表”。“跑测试”技能，成功标准是“测试命令执行完毕并返回结果”。如果一个技能的成功标准说不清楚，那说明粒度不对，需要拆分或合并。

具体到数量，一个项目里 5 到 15 个技能是比较舒服的区间。少于 5 个，说明很多重复工作没被固化；多于 15 个，说明拆得太细，管理成本超过收益。当然这只是参考，具体看项目复杂度。

还有一个参数是技能加载的优先级。当多个技能同时匹配时，哪个先加载？Claude Code 支持在技能文件里设置priority字段，数字越小优先级越高。我一般把“安全相关”的技能设成最高优先级，确保不会被其他技能覆盖。

4.4 技能调试：怎么知道技能生效了

技能写完不是就完事了，得验证它真的生效。Claude Code 和 Codex 都提供了调试模式，可以看到当前加载了哪些技能、触发了哪些指令。

Claude Code 里可以用--debug参数启动，或者在对话里输入/debug查看当前技能状态。Codex 里通常有--verbose参数。如果看不到技能加载日志，说明技能没被识别，可能是文件路径不对、格式有误、或者 description 没匹配上。

我常用的排查步骤是：先确认文件在正确的目录下，再确认文件格式符合规范，然后手动触发一次看是否生效，最后检查 description 是否包含用户输入的关键词。这四步走下来，九成问题都能定位。

注意：技能文件修改后，有些工具需要重启会话才能生效，有些是热加载。Claude Code 默认是热加载，改完保存即可；Codex 有些版本需要重启。不确定的话，重启一次最保险。

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

5.1 技能不触发怎么办

这是最高频的问题。技能写好了，但 AI 就是不用。原因通常有三个：description 没匹配上、文件路径不对、格式有误。

description 没匹配上是最常见的。AI 判断是否加载技能，靠的是把你的输入和 description 做语义匹配。如果你说“帮我看看这段代码”，而 description 里只写了“代码审查”，那可能匹配不上。解决办法是在 description 里多写几个同义词和场景词，比如“审查、检查、review、看看代码、代码问题”。

文件路径不对也很常见。不同工具的技能目录不一样，Claude Code 是.claude/skills，Codex 可能是.codex/skills或skills。放错目录 AI 读不到。建议先用官方示例确认目录结构，再放自己的技能。

格式有误通常是 YAML frontmatter 写错了，比如冒号后面没空格、缩进不对、字段名拼错。这种问题用编辑器的 YAML 插件能提前发现。

5.2 技能冲突与覆盖

多个技能同时触发时，可能会出现指令冲突。比如一个技能说“输出用 JSON”，另一个说“输出用 Markdown”，AI 就懵了。

解决办法有两个：一是设置优先级，高优先级技能覆盖低优先级；二是合并技能，把冲突的部分抽出来做成一个基础技能，其他技能引用它。我倾向于第二种，因为优先级机制虽然简单，但多了之后很难维护，谁覆盖谁容易搞混。

还有一个隐蔽的冲突是工具调用冲突。两个技能都声明要用run_command，但一个要跑测试，一个要跑构建，同时触发时可能互相干扰。这种情况建议把工具调用也纳入技能组合的接口定义，明确谁先谁后。

5.3 技能性能问题

技能多了之后，AI 的响应会变慢。因为每次对话都要加载和匹配所有技能，技能越多，匹配开销越大。

优化方法有几个：按需加载，不要把所有技能都放在项目根目录，可以按模块分目录，AI 只加载当前模块相关的技能。精简 description，description 越长，匹配越慢，控制在 100 字以内比较合适。定期清理，半年没用过的技能就删掉，别留着占地方。

我实测下来，一个项目里技能数量控制在 10 个左右时，响应速度基本无感。超过 20 个，就能感觉到明显延迟了。

5.4 常见问题速查表

5.5 独家避坑技巧

最后分享几个我踩过坑之后总结的技巧。

技巧一：技能文件用英文命名，内容用中文写。文件名用英文是为了跨平台兼容，避免编码问题；内容用中文是因为 AI 对中文指令的理解在中文场景下更准确。当然如果你的团队用英文，那就全英文。

技巧二：每个技能都写一个最小示例。在技能文件里加一个examples字段，给一个输入和一个期望输出。这样不仅 AI 理解更准，你自己调试时也有参照。

技巧三：技能版本化。技能文件跟着项目走 Git，每次修改都提交，这样出问题可以回滚。我见过有人直接在生产环境改技能文件，改坏了没法恢复，只能重写。

技巧四：危险操作加确认。如果技能会执行删除、覆盖、部署等危险操作，在 instructions 里明确要求 AI 先输出计划并等待确认。这个习惯救过我好几次。

技巧五：定期 review 技能。技能不是写完就完了，项目在变，技能也要跟着变。我一般每个月花半小时过一遍所有技能，删掉过时的，更新不准确的。这个投入产出比很高。

6. 技能生态的延伸玩法

6.1 把技能接入本地模型

热搜词里claude code 调用lmstudio的本地模型、codex接入deepseek这些，反映的是大家想把 skills 机制和本地模型结合的需求。思路其实不复杂：Claude Code 和 Codex 都支持配置自定义的模型端点，你把端点指向本地运行的模型服务，技能机制照样能用。

具体操作上，Claude Code 可以通过环境变量或配置文件指定 API 地址，Codex 也有类似的配置项。本地模型用 LM Studio、Ollama 之类的工具跑起来，暴露一个兼容的 API 接口，然后在 Claude Code 或 Codex 里把地址指过去就行。

这里要注意的是，本地模型的指令遵循能力通常不如云端大模型，技能里的复杂指令可能会被忽略。我的建议是：本地模型配简单技能，复杂技能还是用云端模型。或者把复杂技能拆成多个简单技能，逐步执行。

6.2 技能与 agents 的配合

热搜词里langchain deep agents、agents anywhere这些，说的是 agent 框架。skills 和 agents 不是竞争关系，而是互补关系。agent 负责规划和调度，skills 负责具体执行。你可以把 skills 看成 agent 的“工具箱”，agent 决定用哪个工具，skills 定义工具怎么用。

实际配合时，agent 框架通常支持注册自定义工具，你可以把 skill 包装成一个工具注册进去。这样 agent 在规划时就能看到这个技能，需要时调用。这种模式在复杂任务上特别有用，比如“自动修复 bug”这种需要多步规划的任务，agent 负责拆解步骤，skills 负责每步的具体执行。

6.3 技能的安全考量

技能本质上是给 AI 的指令，如果技能文件被恶意篡改，AI 可能会执行危险操作。所以技能文件的安全管理很重要。

我的做法是：技能文件纳入代码审查流程，任何人修改技能都要经过 review。敏感技能加签名，用 GPG 签名验证文件完整性。限制技能权限，只给必要的工具权限，比如只读技能就不给写权限。定期审计，检查技能文件是否有异常修改。

热搜词里agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个，说的就是通过污染 agent 的记忆或知识库来攻击。技能文件如果被污染，效果类似。所以安全这根弦不能松。

7. 我个人的一些实操体会

折腾 skills 这半年，最大的感受是：它把“提示词工程”从一次性消耗品变成了可积累的资产。以前写 prompt 是即用即弃，现在写 skill 是越攒越多，团队里每个人都能受益。这个转变的价值，比单个技能能干什么大得多。

另一个体会是：技能的质量比数量重要。我一开始贪多，写了三十多个技能，结果触发混乱、维护困难，最后砍到十二个，反而好用多了。现在我的标准是：一个技能如果一个月内没被触发过，就考虑删掉。

还有一点：不要指望技能解决所有问题。技能能固化流程、约束输出，但它不能替代清晰的思考。如果你自己都没想清楚一个任务该怎么拆解，写成技能也是糊的。先想清楚，再写技能，顺序不能反。

最后分享一个小技巧：技能文件里加一个“反例”字段，写明什么情况下不要用这个技能。这个字段对减少误触发特别有效。比如代码审查技能里写“不要用于审查配置文件”，AI 就不会在你看 YAML 的时候跳出来审查了。这个技巧我是从一次误触发事故里总结出来的，当时 AI 在我改 CI 配置时自动触发了代码审查，输出了一堆无关建议，浪费了不少时间。加上反例字段之后，这类问题再没出现过。