企业官网建设流程全解析

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

第一次看到“skills”这个标题，很多人会以为是某个泛泛的能力清单，或者又是一套“提升效率的十个技巧”之类的鸡汤合集。但如果你最近在折腾 Claude Code、Codex 这类 AI 编程助手，就会立刻反应过来：这里的 skills 指的是一套让 AI 代理（agent）真正“会干活”的能力封装机制。它不是一个抽象概念，而是实实在在落地到文件、目录、配置里的一套工程化方案。

我接触 skills 的契机很直接：用 Claude Code 写代码时，发现它虽然能理解上下文、能改文件，但每次遇到特定任务——比如按团队规范生成 commit message、按固定模板写单元测试、按内部约定组织目录结构——都得在对话里反复交代一遍。一次两次还行，次数多了就烦，而且每次交代的措辞还不一样，输出质量飘忽不定。skills 就是冲着这个痛点来的：把“怎么做某件事”的经验固化成可复用的能力单元，让 agent 在需要的时候自动加载、按规矩执行。

说白了，skills 解决的是AI 代理的“最后一公里”问题。大模型本身很聪明，但它不知道你团队的代码规范、不知道你项目的目录约定、不知道你偏好的测试框架和断言风格。skills 把这些“隐性知识”显性化、模块化，让 agent 从“什么都能聊两句”变成“这件事就按这个标准干”。它适合谁？适合所有已经在用或准备用 Claude Code、Codex 这类工具做实际开发的人，尤其是团队协作场景下需要统一输出质量的开发者。哪怕你只是个人项目，skills 也能帮你省掉大量重复交代的力气。

2. skills 的核心设计思路：为什么是“技能包”而不是“提示词”

2.1 从提示词到技能包：一次认知升级

早期大家用 AI 编程助手，习惯把要求写在一段长长的提示词里，或者塞进一个CLAUDE.md、AGENTS.md之类的全局配置文件。这种做法在项目初期够用，但很快会暴露三个问题：一是上下文膨胀，所有规则堆在一起，agent 每次都要读一遍，token 消耗大且容易抓不住重点；二是职责不清，前端规范和后端规范混在一起，改一处可能影响另一处；三是无法按需加载，写 React 组件时不需要知道数据库迁移的规矩，但全局配置里全都有。

skills 的设计思路是把“能力”拆成独立的包，每个包有自己的触发条件、自己的说明文档、自己的资源文件。agent 在执行任务时，根据当前上下文判断需要哪些 skill，只加载相关的那些。这就像给一个新人配了一本分章节的操作手册，而不是把整本手册背下来。按需加载是 skills 最核心的设计哲学，也是它比全局提示词更工程化的地方。

2.2 一个 skill 的典型结构

虽然不同工具对 skill 的具体实现有差异，但核心结构大同小异。一个标准的 skill 通常包含以下部分：

• 元信息文件：通常是SKILL.md或类似命名的 Markdown 文件，里面写清楚这个 skill 叫什么、什么时候用、解决什么问题。这是 agent 判断是否加载的依据。
• 指令正文：具体的操作步骤、规范要求、示例代码。这部分是给 agent 看的“操作手册”。
• 资源文件：可选的模板、脚本、配置文件。比如一个生成测试的 skill 可能附带测试模板文件，agent 直接套用而不是从零生成。
• 触发描述：用自然语言描述“当用户要求做 X 时使用本 skill”，让 agent 能准确匹配。

这种结构的优势在于关注点分离：元信息负责“什么时候用”，指令正文负责“怎么用”，资源文件负责“用什么”。三者解耦后，维护和复用都变得简单。你可以把团队的前端规范做成一个 skill，把后端规范做成另一个，把代码审查清单做成第三个，互不干扰。

2.3 为什么不用插件而用 skills

热搜词里同时出现了 plugin 和 skills，很多人会混淆。插件通常是给 IDE 或编辑器用的，扩展的是工具本身的功能；而 skills 扩展的是agent 的行为模式。插件装完就在那里，skills 是按需激活的。举个例子：VS Code 的插件可以给你加一个按钮，但 skills 是告诉 agent“当你看到这个按钮被点击时，按这套流程处理”。两者层次不同，skills 更贴近“业务逻辑”层面。

从工程角度看，skills 的另一个优势是可版本化。skill 就是文件，可以放进 Git 仓库，可以 code review，可以打 tag。团队里谁改了规范，提交一个 PR 就行，所有人拉下来就生效。这种“基础设施即代码”的思路，比在聊天窗口里口口相传靠谱得多。

3. 实操：从零搭建一个可用的 skill

3.1 环境准备与目录约定

在动手之前，先确认你的工具链。Claude Code 和 Codex 对 skills 的支持方式略有不同，但基本都遵循“在项目根目录或用户目录下放一个特定文件夹”的约定。以 Claude Code 为例，常见的做法是在项目根目录创建.claude/skills/目录，每个 skill 一个子文件夹。Codex 侧则可能使用.codex/skills/或类似的路径。具体路径以你所用工具的文档为准，但核心逻辑一致：agent 会扫描这个目录，读取每个 skill 的元信息，建立索引。

我建议的目录结构是这样的：

项目根目录/ ├── .claude/ │ └── skills/ │ ├── commit-message/ │ │ ├── SKILL.md │ │ └── template.txt │ ├── unit-test/ │ │ ├── SKILL.md │ │ └── examples/ │ └── code-review/ │ └── SKILL.md

每个 skill 一个文件夹，文件夹名就是 skill 的标识。这种扁平结构的好处是增删改查都直观，新人一看就懂。不要嵌套太深，agent 扫描时路径越简单越不容易出错。

3.2 写一个 SKILL.md：以“生成规范 commit message”为例

假设我们要做一个 skill，让 agent 在用户说“帮我提交代码”时，自动按团队规范生成 commit message。这个 skill 的SKILL.md可以这样写：

--- name: commit-message description: 当用户要求提交代码、生成 commit message 或执行 git commit 时使用本 skill。按照团队规范生成符合 Conventional Commits 格式的提交信息。 --- # Commit Message 生成规范 ## 格式要求 使用 Conventional Commits 格式： <type>(<scope>): <subject> <body> <footer> ## type 取值 - feat: 新功能 - fix: 修复缺陷 - docs: 文档变更 - style: 格式调整（不影响逻辑） - refactor: 重构 - test: 测试相关 - chore: 构建或辅助工具变更 ## 规则 1. subject 不超过 50 个字符，首字母小写，结尾不加句号 2. body 每行不超过 72 个字符，说明“为什么”而不是“做了什么” 3. 如果关联 issue，footer 写 `Closes #123` 4. 一次提交只做一件事，不要把多个不相关的改动混在一起 ## 示例 feat(auth): add password reset via email Users often forget passwords and had to contact support. This adds a self-service reset flow using email verification. Closes #456

这个文件的关键在于元信息部分（---包裹的 frontmatter）。description字段是 agent 判断是否加载的依据，所以要写得具体，把触发场景列清楚。正文部分则是给 agent 的执行指南，越明确越好，最好带示例。

3.3 让 skill 真正被触发：描述字段的写法技巧

很多人写完 skill 发现 agent 根本不加载，问题多半出在description写得太模糊。比如只写“用于生成 commit message”，agent 可能在你明确说“生成 commit message”时才触发，而你说“帮我提交一下”它就不知道了。好的描述要覆盖多种表达方式：

当用户要求提交代码、生成 commit message、执行 git commit、写提交信息、或提到“commit”“提交”等关键词时使用本 skill。

把同义词、口语化表达都列进去，命中率会高很多。另外，描述里要写清楚使用时机而不是功能本身。agent 关心的是“什么时候该用”，而不是“这个 skill 能干什么”。

3.4 资源文件的组织与引用

如果 skill 需要模板或脚本，放在同目录下，在SKILL.md里用相对路径引用。比如一个生成测试文件的 skill，可以附带template.test.js，然后在指令里写“参考 template.test.js 的结构生成测试”。agent 读取 skill 时会一并加载这些资源，生成时直接套用，比从零发挥稳定得多。

资源文件不要太大，单个文件控制在几 KB 以内。如果模板很长，考虑拆成多个小文件，或者只保留最核心的骨架，细节让 agent 根据上下文补全。资源文件的作用是“定调子”，不是“填内容”。

4. 进阶玩法：组合、复用与团队协作

4.1 skill 之间的组合调用

单个 skill 解决单点问题，但实际开发中任务往往是链式的。比如“实现一个新功能”可能涉及：写代码、写测试、更新文档、提交。如果每个环节都有对应的 skill，agent 能否自动串联？答案是肯定的，但需要你在设计时留好接口。

一种做法是在 skill 的指令里明确“下一步”。比如unit-testskill 的结尾写：“测试写完后，如果用户要求提交，调用 commit-message skill 生成提交信息。”这样 agent 在执行完当前 skill 后，知道接下来该干什么。另一种做法是依赖 agent 自身的规划能力，你只需要把每个 skill 的触发条件写清楚，agent 会在多轮对话中自行判断。

我实测下来，显式引用比隐式依赖更可靠。在 skill 里直接点名“完成后使用 XX skill”，比指望 agent 自己想起来要稳。毕竟 agent 的上下文有限，能少让它“猜”就少让它猜。

4.2 团队协作中的 skill 管理

团队用 skills，最大的挑战不是技术，而是规范的同步。我的建议是：把 skills 目录纳入版本控制，和代码一起 review。谁改了规范，就在 PR 里说明改了什么、为什么改。新成员入职，拉下代码就自带全套规范，不需要口口相传。

另外，建议给 skills 加一个CHANGELOG.md，记录每次变更。当 agent 的输出突然不符合预期时，先查 changelog，看看是不是最近改了 skill。这个习惯能省下大量排查时间。

还有一个坑：不要多人同时改同一个 skill。skill 文件虽然小，但改动影响面大。建议指定一个 owner，或者至少要求改动前在群里同步一声。我见过因为两个人同时改 commit 规范，导致 agent 输出格式混乱的情况，排查了半天才发现是 skill 冲突。

4.3 跨项目复用：把 skill 做成“能力库”

如果你有多个项目，可以把通用的 skill 抽出来，放在一个独立的仓库里，通过 git submodule 或者符号链接引入各个项目。这样改一处，所有项目生效。Claude Code 和 Codex 都支持从用户目录加载全局 skill，你可以把个人偏好的 skill 放在~/.claude/skills/下，项目专属的放在项目目录下，agent 会合并两者。

这种分层结构很实用：全局层放个人习惯（比如你偏好的代码风格），项目层放团队规范（比如必须遵守的架构约定）。两层互不干扰，优先级由工具决定，通常项目层覆盖全局层。

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

5.1 skill 不生效的几种典型情况

5.2 我踩过的三个坑

第一个坑：description 写成了功能说明。一开始我写“本 skill 用于生成符合规范的 commit message”，结果 agent 只有在我明确说“生成 commit message”时才用。后来改成“当用户要求提交代码、执行 git commit、写提交信息时使用”，命中率立刻上来了。描述要写“什么时候用”，不是“能干什么”。

第二个坑：指令正文太抽象。我写过一条“代码要符合团队规范”，agent 完全不知道“团队规范”是什么。后来改成具体的“函数名用 camelCase，常量用 UPPER_SNAKE_CASE，每个函数不超过 50 行”，输出立刻稳定了。给 agent 的指令要像给新人的操作手册，不能像给老员工的备忘录。

第三个坑：资源文件路径用了绝对路径。在我机器上跑得好好的，同事拉下来就报错。改成相对路径后问题解决。skill 是要进版本控制的，任何绝对路径都是定时炸弹。

5.3 性能与 token 消耗的平衡

skills 按需加载虽然省 token，但如果 skill 本身写得太长，加载时还是会吃掉大量上下文。我的经验是：单个 skill 的指令正文控制在 500 字以内，超出的部分拆成多个 skill，或者放到资源文件里。资源文件只有在 agent 真正需要时才会读取，比写在指令里更省。

另外，定期清理不再使用的 skill。我见过一个项目积累了三十多个 skill，agent 每次扫描索引都要花不少时间，而且触发判断也容易出错。skill 不是越多越好，保持精简，每个都真正有用。

6. 从 skills 看 AI 代理的工程化趋势

skills 这个机制的出现，标志着 AI 编程助手从“通用聊天”向“专业工具”的转变。早期的 agent 像一个什么都懂一点但什么都不精的实习生，skills 则是给这个实习生配了一套岗位操作手册，让它能在特定任务上达到熟练工的水平。

这个趋势背后是一个朴素的道理：大模型的能力上限很高，但下限不稳定。同一个问题问两次，答案可能不一样。skills 通过固化流程和规范，把下限拉高，让输出变得可预期。对于生产环境来说，可预期比聪明更重要。

从热搜词里能看到，大家关心的不只是“怎么装 Claude Code”“怎么装 Codex”，而是“codex 好用的 skills”“claude agent skills 深度解析”。这说明用户已经从“能不能用”过渡到“怎么用好”的阶段。skills 正是“用好”的关键抓手。

我个人在实际操作中的体会是：先把一个 skill 写透，再考虑写第二个。很多人一上来就想搭一套完整的 skill 体系，结果每个都写得半吊子，agent 触发混乱，反而添乱。从一个最痛的点开始——比如 commit message 或者单元测试——把它打磨到 agent 每次都能按预期执行，然后再扩展。这个节奏最稳。

最后分享一个小技巧：给每个 skill 写一个“反例”。在指令正文里加一段“不要这样做”，列出常见的错误输出。agent 对反例的敏感度很高，加了反例之后，输出质量通常能再上一个台阶。这个技巧在官方文档里很少提，但实测非常有效。