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最重要的能力之一。
