Codex完整教程：构建可复用AI工作流，化身专属开发助手

Codex技能（Skills）完整教程：打造可复用AI工作流，让Codex变成你的专属开发助手

在这里插入图片描述

Codex除了具备强大的代码生成能力外，还有一个容易被开发者忽略的核心功能——Skills（技能系统）。

很多人习惯将Codex当作普通的聊天工具使用，但实际上，通过技能系统，我们可以将常用的开发流程、项目规范、运维脚本、测试流程等内容封装为可重复调用的AI工作流。

简单理解：Skill就像是一份“AI工作说明书”，告诉Codex在某个特定场景下应该如何处理、遵守什么规则、调用哪些工具。

本文将带领大家全面了解Codex技能系统的工作原理与实操方法。

什么是Codex Skill

官方定义非常明确：Skill是用来定义Codex在特定场景下的一套“行为指令集”。它可以包含：

• 指令
• 参考资料
• 脚本
• 模板文件
• MCP工具依赖

然后统一打包提供给Codex使用。

举一个实际例子：

前端开发Skill

可以包含：Vue开发规范、Pinia状态管理规范、Element Plus组件规范、Git提交规范。

当Codex调用该技能时，你只需输入“创建一个用户管理页面”，Codex就会自动按照团队规范生成对应的代码。

运维Skill

可以包含：Docker部署流程、Nginx配置规范、PM2启动命令、故障排查步骤。

输入“部署Node项目”，Codex即可自动执行相应流程。

Skill与插件有什么区别

很多人容易混淆这两个概念。实际上，它们解决的是不同层面的问题。

Skill

本质上是“工作流”，解决的是“怎么做”的问题——它告诉Codex在特定任务中应该遵循哪些规范、使用什么工具、按什么步骤执行。

Plugin

本质上是“安装包”，解决的是“如何分发”的问题——它将Skill、配置、资源打包成可分享给其他开发者的标准格式。

两者之间的关系是：先开发并验证Skill工作流，再将其封装成Plugin用于分发。推荐的做法是先开发Skill，确认工作流可行后，再封装为Plugin。

Skill目录结构

一个标准技能目录的结构如下：

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── agents/
    └── openai.yaml

其中，SKILL.md是唯一必须存在的文件，其余目录均为可选辅助目录。

核心文件SKILL.md

这是整个技能的核心所在。一个典型的SKILL.md内容示例如下：

---
name: vue-developer
description: 用于Vue项目开发、组件创建、Pinia状态管理和Element Plus页面开发
---
创建代码时遵循以下规范：
1. 使用Composition API
2. 使用TypeScript
3. 优先使用Pinia
4. 使用Element Plus组件

参数说明

name

技能名称。例如：name: vue-developer。它主要用于显式调用，比如在对话中输入$vue-developer即可触发该技能。

description

技能描述。例如：description: Vue3项目开发助手。Codex会根据这段描述自动判断何时调用该技能。描述的质量直接决定了自动匹配的准确率。

Codex如何加载Skill

很多人会担心：如果安装了100个Skill，会不会撑爆上下文？

这个顾虑是多余的。Codex采用按需加载机制。启动时仅加载技能名称、技能描述和技能路径等基本信息，比如：vue-developer、NodeJS-Deploy、DockerOps。

只有当被显式调用（输入$vue-developer）或者Codex根据description判断匹配成功后，才会读取完整的SKILL.md内容。因此上下文利用率很高，不必担心冗余问题。

Skill触发机制

Codex支持两种触发方式。

方法1：显式调用

直接通过$技能名称来指定，比如$vue-developer或$docker-deploy。在CLI中也可以通过/skills手动选择技能。

方法2：隐式调用

根据description字段自动匹配。例如，你输入“帮我部署一个Node项目”，Codex发现“docker-deploy”这个技能的描述最符合需求，就会自动触发。

创建Skill

官方推荐使用$skill-creator命令来创建。执行后会弹出一个向导界面，询问你这个技能用于什么场景、什么情况下触发、是否需要脚本。然后自动生成SKILL.md和目录结构。

手动创建Skill

当然也可以手动创建。只需建立一个目录，比如my-skill，然后在里面创建SKILL.md文件，写入内容即可立即使用。例如：

---
name: code-review
description: 用于代码审查和质量检查
---
检查以下内容：
1. 代码规范
2. 性能问题
3. 安全风险
4. 可维护性

Skill存放位置

Codex支持多个层级的存放位置，适应不同场景：

仓库级

放在当前项目的.agents/skills目录下，适合项目特定的规范。

用户级

放在~/.agents/skills目录下，适合个人开发规范。

管理员级

在Linux系统中，可以放在/etc/codex/skills目录下，适合企业统一配置。

系统级

Codex自带的技能，比如skill-creator和planner等。

安装官方精选Skill

Codex内置了安装器$skill-installer，比如安装Linear技能可直接执行$skill-installer linear，安装完成后技能会自动加入列表，重启Codex即可使用。

禁用Skill

如果有些技能不想删除但暂时不想让它生效，可以在~/.codex/config.toml中配置：

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

这样技能文件会保留但不会被加载。修改配置后重启Codex才能生效。

openai.yaml高级配置

如果希望在Codex App中展示更丰富的信息，可以在agents/openai.yaml中进行配置。例如：

interface:
  display_name: "Vue开发助手"
  short_description: "Vue项目开发规范"
  icon_small: "./assets/logo.svg"
  brand_color: "#3B82F6"

这样一来，在Codex界面中就会出现显示名称、图标和简介，更加直观友好。

MCP工具依赖

Skill还可以声明对MCP工具的依赖。比如：

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"

表示该Skill依赖OpenAI文档MCP，使用时就会自动关联。

禁止自动触发Skill

默认情况下，Skill允许隐式自动触发（allow_implicit_invocation: true）。如果改成false，那么就只能通过$skill-name显式调用来触发，不会再自动匹配。

实战案例：构建Vue开发技能

假设要创建一个Vue开发辅助技能，可以在~/.agents/skills/vue3-helper目录下创建SKILL.md，内容如下：

---
name: vue3-helper
description: Vue3、Pinia、Element Plus开发助手
---
要求：
1. 使用Vue3
2. 使用Composition API
3. 使用Pinia
4. 使用Element Plus
5. 使用TypeScript

之后直接输入“创建一个用户管理页面”，Codex就会自动按照这些规范生成代码。

Skill最佳实践

官方给出了一些非常实用的建议：

一个Skill只做一件事

不要把Vue、Docker、Python、运维、测试全部塞进一个技能。每个技能保持职责单一，这样更容易维护和复用。

优先使用纯指令

能用SKILL.md里的文本指令解决的问题，就不要写脚本。纯指令更稳定、更容易维护、也更容易在不同环境中迁移。

描述写清触发条件

描述要写得具体。好的描述如“用于Vue3组件开发”，差的描述如“开发助手”——后者完全没法让Codex做准确匹配。description字段直接决定了自动触发的效果。

用真实场景测试

创建完技能后，一定要用真实的任务去测试，比如输入“创建后台管理页面”，看看是否能正确触发并输出符合预期的结果。

总结

Codex Skills本质上是一套AI工作流封装系统。相比传统Prompt，它具备可复用、可维护、可共享、可版本管理、支持脚本扩展、支持MCP集成、支持插件分发等优势。

对于个人开发者来说，可以沉淀自己的开发规范；对于团队来说，可以统一编码风格、部署流程和协作标准，让Codex真正成为团队级AI开发助手。未来随着插件生态的完善，Skill很可能会成为Codex最重要的能力之一。