企业官网建设流程全解析

在实际 AI 辅助开发工作中，很多开发者会遇到一个典型困境：工具装好了，基础命令也会用了，但总感觉它只能完成一些零散的、简单的任务，无法真正融入自己的核心工作流。比如，你希望它能自动生成符合团队规范的 API 接口代码、一键执行复杂的本地构建部署流程，或者根据 Jira 工单自动生成 Git 提交信息。这些都不是单一指令能解决的，它们需要一系列连贯的、可复用的步骤组合。这正是 Codex 的 Skills（技能）机制要解决的核心问题。Skills 不是简单的命令别名，而是将指令、上下文、脚本和资源打包在一起的“任务级能力单元”，它让 Codex 从一个被动的问答工具，转变为一个能主动遵循预设流程、稳定执行复杂任务的智能体。

本文面向已经安装 Codex 但尚未深入使用其高级功能的开发者。我们将从零开始，彻底理解 Skills 的概念、工作机制和最佳实践。你将学会如何创建自己的第一个技能，如何组织和管理技能库，以及如何利用技能搭建可复用的自动化工作流，最终将 Codex 深度集成到你的日常开发、测试和部署环节中。整个过程不需要你预先掌握复杂的 AI 或脚本知识，我们将通过具体的示例和清晰的步骤，带你从“会用”走向“精通”。

1. 理解 Codex Skills：从指令到可复用工作流

在深入动手之前，我们必须先厘清几个核心概念：什么是 Skill？它和普通的提示词、插件有什么区别？为什么我们需要它？

1.1 Skill 的本质：封装确定性的工作流

一个 Skill（技能）本质上是一个目录，其中至少包含一个SKILL.md文件。这个文件定义了技能的元数据（名称、描述）和具体的执行指令。你可以把它想象成一个针对特定任务的“超级模板”或“自动化脚本说明书”。当 Codex 决定使用某个技能时，它会将SKILL.md中的完整指令加载到其上下文中，从而确保执行过程的稳定性和可预测性。

与一次性的聊天提示词相比，Skill 的核心优势在于可复用性和确定性。一次精心编写的提示词可能这次有效，下次因为上下文细微变化就失效了。而一个定义良好的 Skill，通过明确的触发条件和步骤描述，能在相同场景下被反复、稳定地调用。

1.2 Skill 与 Plugin 的定位差异

这是初学者最容易混淆的一点。根据官方设计，两者的分工非常明确：

• Skill（技能）：是工作流的创作格式。它关注的是“做什么”和“怎么做”，是逻辑和指令的集合。它最适合在本地或团队仓库内定义和迭代具体的工作流程，比如“为新功能分支创建标准的目录结构”或“运行项目的全套代码质量检查”。
• Plugin（插件）：是能力的分发和安装单元。一个插件可以包含一个或多个技能，同时还能打包 MCP 服务器配置、应用映射、界面资源等。当你希望将开发好的技能分享给更广泛的用户，或者将其与某个应用程序捆绑分发时，才需要将其打包成插件。

简单来说：先设计 Skill 来解决具体问题，再考虑是否将其打包为 Plugin 进行分发。对于个人或团队内部使用，直接在.agents/skills目录下维护技能库就足够了。

1.3 Codex 如何发现和使用技能

Codex 采用一种称为“按需展开”的智能上下文管理策略。启动时，它并不会加载所有技能的完整内容，那样会迅速耗尽有限的上下文窗口。相反，它只读取每个技能目录下的SKILL.md文件中的name和description字段，生成一个轻量级的技能列表。

当用户提出需求时，Codex 会基于这个列表中的描述，判断哪个技能最适合当前任务。只有在确定要使用某个技能后，才会将该技能完整的SKILL.md指令内容加载到上下文中。这种机制既保证了技能匹配的灵活性，又最大限度地节约了宝贵的上下文资源。

技能可以通过两种方式触发：

1. 显式调用：用户直接在对话或命令中指定技能名称，例如在 Codex CLI 中输入/skills后选择，或在提示词中写入$skill-name。
2. 隐式调用：Codex 根据用户自然语言描述的意图，自动匹配技能描述中合适的关键词和场景，从而推荐或直接使用该技能。这就要求技能的description必须写得精准、清晰。

2. 环境准备与技能目录结构

在创建第一个技能之前，我们需要确保 Codex 环境就绪，并理解技能文件的存放位置规则。

2.1 确认 Codex 安装与基础功能

首先，打开终端，运行以下命令检查 Codex CLI 是否已正确安装并可访问技能相关功能：

# 检查 Codex CLI 版本 codex --version # 列出当前已发现的技能（初始可能为空或只有系统内置技能） codex /skills list # 尝试调用内置的技能创建器（如果可用） codex $skill-creator

如果codex命令未找到，请根据官方文档重新完成安装和配置。确保你的 Codex 版本支持 Skills 功能。

2.2 理解技能的多级存储位置

Codex 会从多个层级的位置扫描并加载技能，优先级从高到低（局部覆盖全局）如下表所示：

关键规则：Codex 会从当前工作目录（$CWD）开始向上扫描，直到仓库根目录，寻找.agents/skills文件夹。如果不同位置存在同名技能，它们会同时出现在技能列表中，不会被合并，Codex 可能会提示你进行选择。

对于初学者，我们建议从仓库级技能开始。在你的项目根目录下创建.agents/skills目录。

# 进入你的项目目录 cd /path/to/your/project # 创建技能存储目录 mkdir -p .agents/skills # 查看目录结构 tree .agents -a

预期输出应显示一个空的skills目录。

3. 创建你的第一个技能：自动化生成 RESTful API 控制器

让我们通过一个实战案例来学习技能的创建。假设我们有一个 Spring Boot 项目，需要频繁地为新的资源创建符合团队规范的 RESTful Controller。手动编写虽然简单，但容易遗漏注解、格式不一致。我们将创建一个名为generate-spring-controller的技能来自动化这个过程。

3.1 使用技能创建器（推荐给新手）

Codex 内置了skill-creator工具，它能通过交互式问答引导你完成技能的创建。在项目根目录下运行：

codex $skill-creator

创建器会询问一系列问题，以下是一个示例对话流程及回答思路：

1. What should this skill do?(这个技能做什么？)
   • 回答：Generate a Spring Boot REST controller for a given resource name, following our team's coding standards. It should include standard CRUD endpoints, proper annotations, and placeholder method bodies.
2. When should Codex use this skill?(Codex 应在什么场景下使用它？)
   • 回答：When the user asks to create a new API controller, generate a REST controller, or scaffold a CRUD endpoint for a resource. Keywords: “controller”, “REST”, “API”, “CRUD”, “scaffold”.
3. Should this skill include runnable scripts, or is it instructions-only?(这个技能包含可运行脚本，还是仅是指令？)
   • 回答：Instructions-only.（对于纯代码生成任务，通常先使用纯指令技能）。

回答完毕后，skill-creator会在当前目录（或你指定的目录）下生成一个技能文件夹，例如.agents/skills/generate-spring-controller/，并包含一个初步的SKILL.md文件。

3.2 手动创建与编写 SKILL.md

理解技能结构后，手动创建能让你更清晰地控制细节。按照以下步骤操作：

# 在项目的技能目录下创建技能文件夹 mkdir -p .agents/skills/generate-spring-controller # 创建并编辑核心的 SKILL.md 文件 cd .agents/skills/generate-spring-controller

用文本编辑器创建SKILL.md文件，内容如下：

--- name: generate-spring-controller description: Generates a standard Spring Boot REST controller with CRUD endpoints for a given resource name. Use when user asks to create an API controller, REST endpoint, or scaffold CRUD operations. --- You are an expert Java and Spring Boot developer. Your task is to generate a complete, production-ready Spring Boot REST controller class based on the user's request. **Instructions:** 1. First, ask the user for the **singular resource name** (e.g., "Product", "User", "Order"). 2. Based on the resource name, generate a corresponding Java class file. 3. The controller must be placed in the `com.example.demo.controller` package (adjust if the user specifies a different base package). 4. Follow these coding standards: * Use `@RestController` and `@RequestMapping("/api/v1/{resource-kebab}")` annotations. * Inject a service using `@Autowired` (field injection for simplicity in this scaffold). * Implement standard CRUD endpoints: * `GET /` -> `getAll()` returns List<Resource> * `GET /{id}` -> `getById(@PathVariable Long id)` returns Resource * `POST /` -> `create(@RequestBody Resource resource)` returns Resource * `PUT /{id}` -> `update(@PathVariable Long id, @RequestBody Resource resource)` returns Resource * `DELETE /{id}` -> `delete(@PathVariable Long id)` returns ResponseEntity<Void> * Use `@Slf4j` for logging (ensure project has Lombok). * Include placeholder method bodies with TODO comments and log statements. * Use proper Javadoc for the class and public methods. 5. After generating the code, provide a brief explanation of the structure and remind the user to create corresponding `Service`, `Repository`, and `Entity` classes. **Output Format:** Provide the complete Java code in a markdown code block labeled `java`. Then, add a summary section. **Example Interaction:** User: "Create a controller for managing books." Assistant: "I'll help you generate a Book controller. First, what's the singular name of the resource? (e.g., Book)" User: "Book" Assistant: [Generates the BookController.java code]

这个SKILL.md文件的结构非常清晰：

• Front-matter (元数据)：被---包裹的 YAML 块，定义了技能的name和description。description是隐式匹配的关键，务必准确描述触发场景。
• 指令主体：详细说明了技能的目标、交互步骤、代码规范、输出格式，甚至包含了一个示例对话。这相当于给 Codex 的一份“工作手册”。

3.3 为技能添加可选资源与配置

一个技能目录下还可以包含其他文件，使其功能更强大：

• scripts/：存放可执行的 Shell、Python 等脚本，技能指令中可以调用它们来执行外部操作。
• references/：存放参考文档、API 说明等，供 Codex 在生成内容时查阅。
• assets/：存放代码模板、配置文件等静态资源。
• agents/openai.yaml：用于配置技能在 Codex App 中的界面显示和高级策略。

让我们为控制器生成技能添加一个agents/openai.yaml文件，以控制其调用策略：

# .agents/skills/generate-spring-controller/agents/openai.yaml interface: display_name: "生成 Spring 控制器" short_description: "根据资源名生成标准的 Spring Boot REST CRUD 控制器代码。" # icon_small: "./assets/controller-icon.svg" # 可选图标 # icon_large: "./assets/controller-icon-lg.png" brand_color: "#10B981" # Emerald green policy: # 设为 false 则只能通过 $generate-spring-controller 显式调用，不会自动推荐 allow_implicit_invocation: true dependencies: # 声明此技能依赖的工具或上下文（此处为示例，实际需根据项目调整） # tools: # - type: "mcp" # value: "javaDocServer" # description: "Access to Java SDK documentation"

创建完成后，你的技能目录结构应如下所示：

your-project/ ├── .agents/ │ └── skills/ │ └── generate-spring-controller/ │ ├── SKILL.md │ └── agents/ │ └── openai.yaml └── (其他项目文件)

4. 技能的调用、测试与验证

技能创建后，需要重启 Codex（CLI 或 IDE 插件）以重新扫描并加载新技能。之后，就可以进行测试了。

4.1 触发与使用技能

方法一：隐式调用（基于描述匹配）在 Codex 对话窗口中，直接输入自然语言请求：

“我需要一个用于管理订单的 REST API 控制器。”

如果技能的description写得好，并且allow_implicit_invocation为true，Codex 应该能识别出这个请求与generate-spring-controller技能匹配，并自动应用该技能的指令来与你交互。

方法二：显式调用（直接指定）在 Codex 输入中，直接使用技能名称（带$前缀）：

$generate-spring-controller

或者，在支持斜杠命令的 CLI 或 IDE 中，输入/skills可能会列出可用技能供你选择。

4.2 验证技能输出

一个成功的交互应该遵循SKILL.md中定义的流程。以上面的技能为例，理想的交互过程是：

1. Codex 识别技能并首先提问：“我将为您生成一个控制器。请问资源的单数名称是什么？（例如：Order）”
2. 用户回答：“Order”
3. Codex 生成完整的OrderController.java代码，包含所有要求的注解、CRUD 方法和日志。

你应该检查生成的代码是否：

• 包路径正确。
• 包含了@RestController,@RequestMapping,@Autowired等注解。
• 有GET,POST,PUT,DELETE方法。
• 方法签名和返回值类型符合规范。
• 包含了@Slf4j和日志语句。
• 有清晰的TODO注释。

4.3 调试技能不生效的常见问题

如果技能没有按预期触发或工作，请按以下清单排查：

5. 设计高效技能的最佳实践与进阶模式

掌握了基础创建和调用后，遵循以下最佳实践能让你的技能更强大、更可靠。

5.1 技能设计原则

1. 单一职责：一个技能只做好一件事。不要创建“生成控制器并连接数据库还运行测试”的巨无霸技能。将其拆分为generate-controller、generate-service、run-unit-tests等多个技能，组合使用。
2. 指令优先于脚本：除非必须调用外部工具或执行确定性操作（如文件移动、执行命令），否则尽量用清晰的文字指令指导 Codex 完成工作。这保持了灵活性，并能利用 Codex 最新的模型能力。
3. 清晰的输入与输出：在指令中明确说明技能需要用户提供什么信息（如资源名、文件路径），以及最终会输出什么（如代码块、文件列表、总结报告）。
4. 用真实提示词测试描述：不断用你期望用户会说的各种话来测试技能的description，确保它在该触发时触发，在不该触发时保持“沉默”，避免误匹配。

5.2 组合技能以构建工作流

真正的自动化威力来自于技能的串联。Codex 可以在一轮对话中依次或根据条件使用多个技能。

示例：新功能开发工作流你可以设计三个技能：

• $create-feature-branch：基于 Jira issue key 创建并切换 Git 分支。
• $scaffold-crud-module：根据模块名，生成 Entity, Repository, Service, Controller 的骨架代码。
• $run-local-validation：运行项目的代码格式化、静态检查和单元测试。

当开始一个新功能时，你可以依次调用它们，或者在一个更高级的“总管”技能中按顺序调用这些子技能。

5.3 利用脚本和外部工具

当任务需要与本地环境交互时，可以在技能目录的scripts/子目录下放置可执行脚本。

例如，创建一个deploy-to-staging技能，其SKILL.md指令中包含步骤：“运行部署脚本scripts/deploy.sh”。而scripts/deploy.sh内容可能如下：

#!/bin/bash # scripts/deploy.sh echo "开始部署到预发环境..." # 假设使用某个部署工具 ./your-deploy-tool --env staging --version $(git rev-parse --short HEAD) if [ $? -eq 0 ]; then echo "✅ 部署成功！" echo "预发环境地址：https://staging.example.com" else echo "❌ 部署失败，请检查日志。" exit 1 fi

在SKILL.md中，你可以这样指示 Codex：“请执行项目根目录下的部署脚本scripts/deploy.sh，并将结果反馈给我。” Codex 在沙箱环境中执行该脚本后，会将输出返回给你。

注意：执行脚本涉及安全与权限。请仅在可信的技能中包含脚本，并清楚了解脚本的行为。Codex 的沙箱环境会限制某些操作。

5.4 管理个人与团队技能库

随着技能增多，管理变得重要。

• 个人技能库 (~/.agents/skills): 将通用的、与特定项目无关的技能放在这里，如format-code、commit-with-convention、docker-build。
• 项目技能库 (./.agents/skills): 放置项目特有的技能，如项目独有的代码生成模板、部署脚本。
• 使用 Git 管理: 将项目的.agents/skills目录纳入版本控制，这样团队所有成员都能共享同一套自动化标准。
• 技能文档化: 在团队 Wiki 或README.md中维护一个技能清单，说明每个技能的用途、触发方式和示例。

6. 从技能到插件：打包与分发

当你开发了一个非常有用的技能，并希望分享给其他项目或社区时，就需要考虑将其打包为插件。

6.1 插件与技能的关系回顾

再次强调：技能是工作流，插件是包装。插件是一个更大的分发单元，可以包含：

• 一个或多个技能。
• 配置说明。
• 图标、主题等界面资源。
• 对 MCP 服务器的配置。

6.2 使用技能安装器探索社区技能

在考虑自己分发之前，可以先使用内置的$skill-installer来安装他人分享的技能（如果该技能已打包为插件并发布在已知仓库）。例如，尝试安装一个可能存在的linear（项目管理工具）集成技能：

codex $skill-installer linear

这会将技能及其相关资源安装到你的用户全局或当前仓库技能目录中。这是快速扩展 Codex 能力的有效方式。

6.3 创建你自己的插件（高级）

创建插件涉及更多配置，通常需要一个plugin.toml或类似的清单文件来描述插件元数据、包含的技能路径、依赖关系等。具体步骤请参考 Codex 官方文档中关于“构建插件”的章节。核心思路是：将你的技能目录、agents/openai.yaml以及其他资源，按照插件规范组织，然后通过 Codex 的插件机制进行安装。

7. 生产环境考量与安全

将 Skills 用于生产环境或团队协作时，需注意以下几点：

1. 权限控制：对于能执行脚本（尤其是写操作、系统调用）的技能，要严格控制其使用范围和权限。避免技能被误用导致数据丢失或系统损坏。
2. 代码审查：将技能定义文件（SKILL.md,agents/openai.yaml, 脚本）纳入团队的代码审查流程，确保其安全性和符合规范。
3. 版本管理：技能的迭代和变更应有记录。当技能逻辑更新后，需要通知团队成员更新其本地的技能库或插件。
4. 环境隔离：明确区分开发、测试、生产环境所使用的技能。例如，部署技能应指向正确的环境端点，避免误操作。
5. 错误处理：在技能的指令或脚本中，考虑加入基本的错误处理和用户提示，让失败的情况也有清晰的反馈。

通过系统地应用 Codex Skills，你可以将大量重复、繁琐的开发操作转化为稳定、可复用的自动化流程。从创建一个简单的代码生成技能开始，逐步构建起属于你个人或团队的智能体技能矩阵，最终让 Codex 成为你开发工作中不可或缺的高效协作者。