⌨️ Codex教程

Codex Skills 使用教程

Codex Skills：打造可复用工作流与扩展 AI 编程能力

Codex Skills（技能）是用于封装专项任务工作流的可复用单元，能将固定指令、参考资料、脚本与规范打包，让 Codex 在处理同类任务时稳定遵循统一流程。它是自定义 AI 编程行为的核心方式，也是插件的核心组成部分 —— 你先用 Skills 设计工作流，再打包为插件分发给团队复用。本文基于官方文档完整讲解 Skills 的创建、存储、调用、管理与分发，覆盖从个人提效到团队标准化的全场景用法。

一、Skills 核心基础概念

1.1 什么是 Skills

Skill 是一个标准化目录，以SKILL.md为核心，可包含指令、脚本、参考文档与资源，让 Codex 可靠执行某一类专项任务（如代码审查、项目初始化、接口调试）。它遵循开放智能体技能标准，支持 CLI、IDE 扩展、桌面端全平台使用。

1.2 Skills 与 Plugins 的关系

Skills：专注工作流本身的设计与编写，是可复用的指令逻辑载体；
Plugins：是 Skills、应用集成、MCP 服务的分发安装包，用于跨项目 / 跨团队共享 Skills。
简单说：本地用 Skills，分享用 Plugins。

1.3 两种调用方式

显式调用：在提示中直接指定技能，CLI/IDE 输入/skills查看列表，或输入$技能名触发；
隐式调用：Codex 根据你的任务描述，自动匹配技能description触发，无需手动指定。

1.4 高效加载机制：渐进式披露

Codex 启动时仅加载技能的名称、描述、路径，不会立即读取完整SKILL.md，仅在决定使用该技能时才加载完整指令。

初始技能列表限制为模型上下文窗口的 2%（约 8000 字符），避免挤占有效上下文；
描述过长会优先缩短，技能过多时部分会被省略并弹出提示；
选中技能后，仍会完整加载该技能的所有指令，保障执行效果。

二、Skill 标准目录结构

一个完整 Skill 包含必选文件与可选扩展文件，结构清晰、易于维护：

my-skill/                # 技能根目录
├── SKILL.md             # 【必选】元数据+执行指令
├── scripts/             # 【可选】可执行脚本
├── references/          # 【可选】参考文档/规范
├── assets/              # 【可选】模板、图标等资源
└── agents/
    └── openai.yaml       # 【可选】UI元数据、策略、依赖

核心文件：SKILL.md 规范

SKILL.md分为两部分：YAML 前端数据（必选 name+description）+ Markdown 执行指令。

---
name: react-code-review
description: 对React函数组件做代码审查，检查Hooks规范、性能、可访问性，仅适用于TSX文件
---
## 执行步骤
1. 读取目标文件，确认是React TSX函数组件
2. 检查Hooks调用顺序与依赖项完整性
3. 校验组件是否做不必要重渲染，给出优化建议
4. 验证可访问性（alt文本、语义化标签）
5. 输出简洁的审查报告，标注问题等级与修改方案
## 禁止行为
- 不修改业务逻辑，仅做规范与性能审查
- 不生成无关代码，仅输出建议

三、快速创建 Skill（两种方式）

方式 1：使用内置创建器（推荐新手）

Codex 自带$skill-creator，交互式生成技能，无需手动搭建目录：

启动 Codex，输入：

$skill-creator

按提示回答：
- 技能用途
- 触发场景
- 是否需要脚本
- 仅指令还是包含脚本
创建器自动生成目录与SKILL.md，直接编辑即可。

方式 2：手动创建（精准控制）

# 创建用户级技能目录
mkdir -p ~/.agents/skills/react-code-review
cd ~/.agents/skills/react-code-review

创建并编写SKILL.md（参考上文示例）；
按需添加 scripts、references 等目录；
修改后重启 Codex 即可生效。

四、Skill 存储位置与作用域

Codex 从四个层级加载技能，就近优先、互不覆盖，相同名称技能会同时显示。

作用域	路径	适用场景
REPO（项目级）	当前项目 /.agents/skills	项目专属技能，团队共享
REPO（父目录）	项目上级目录 /.agents/skills	多模块共用技能
REPO（根目录）	项目根目录 /.agents/skills	全项目通用技能
USER（用户级）	~/.agents/skills	个人所有项目通用
ADMIN（系统级）	/etc/codex/skills	机器所有用户共用
SYSTEM（官方）	Codex 内置	基础通用技能（skill-creator 等）

注意：项目级技能仅在仓库被标记为信任时加载；支持符号链接，方便技能共享。

五、Skill 调用与使用

5.1 显式调用（精准触发）

适合明确需要某技能的场景：

查看所有可用技能：

/skills

直接调用技能：

$react-code-review src/components/Button.tsx

5.2 隐式调用（自动匹配）

Codex 根据任务描述匹配description触发，无需手动指定：

好的描述：明确用途 + 触发条件 + 适用范围；
示例描述：对React TSX组件做代码审查，检查Hooks、性能、可访问性；
触发提示：帮我审查这个Button组件的代码规范。

关键规则

隐式调用完全依赖description，建议前置核心关键词，即便描述被缩短也能正确匹配。

六、Skill 管理：安装、启用与禁用

6.1 安装第三方技能

使用$skill-installer快速安装官方 / 社区技能：

# 安装 linear 技能
$skill-installer linear

支持从 Git 仓库下载，安装后自动检测，不生效则重启 Codex。

6.2 禁用技能（不删除）

在~/.codex/config.toml中配置，禁用指定技能：

[[skills.config]]
path = "/Users/xxx/.agents/skills/react-code-review/SKILL.md"
enabled = false

修改后必须重启 Codex生效。

七、高级配置：agents/openai.yaml

用于配置技能 UI 展示、调用策略与工具依赖，提升使用体验：

interface:
  display_name: "React代码审查"
  short_description: "审查React组件规范与性能"
  icon_small: "./assets/icon.svg"
  brand_color: "#61dafb"
policy:
  allow_implicit_invocation: false  # 禁止隐式调用，仅允许显式触发
dependencies:
  tools:
    - type: "mcp"
      value: "eslint-mcp"
      description: "ESLint检查服务"

allow_implicit_invocation: false：强制手动$技能名调用，避免误触发；
dependencies：声明 MCP 等依赖，Codex 会自动检查依赖状态。

八、技能分发：打包为插件

如需跨项目 / 跨团队共享技能，将其打包为 Codex 插件：

新建插件目录，放入技能文件夹；
在.codex-plugin/plugin.json声明技能路径：

{
  "name": "frontend-skills",
  "version": "1.0.0",
  "description": "前端团队通用技能包",
  "skills": "./skills/"
}

共享插件目录，他人通过codex plugin install ./路径安装使用。

九、最佳实践

单技能单职责：一个技能只做一件事，避免逻辑臃肿，便于维护与匹配；
指令优先，脚本为辅：优先用 Markdown 指令描述流程，仅在需要确定性行为时用脚本；
指令步骤化：用 imperative 句式，明确输入、执行步骤、输出格式；
描述精准：前置触发关键词，确保隐式调用准确率；
作用域分离：个人技能放 USER 目录，团队技能放 REPO 根目录，避免冲突；
禁止隐式高危技能：涉及删除、构建、发布的技能，关闭隐式调用，仅允许显式触发；
持续迭代：根据使用反馈优化SKILL.md指令，提升执行稳定性。

十、常见问题排查

技能不显示
- 检查路径是否在加载目录中，目录命名是否为.agents/skills；
- 确认SKILL.md包含必填的name和description；
- 重启 Codex 重新扫描技能。
隐式调用不触发
- 优化description，更明确描述触发场景；
- 检查openai.yaml是否关闭了隐式调用；
- 技能过多被省略，清理无用技能。
技能修改不生效
- 技能修改自动检测，未生效则重启 Codex；
- 检查文件路径是否正确，无语法错误。
项目级技能不加载
- 确认当前项目已被标记为信任；
- 检查技能路径在项目内.agents/skills。
技能冲突
- 同名技能会同时显示，调用时指定完整路径；
- 禁用重复或无用技能，减少列表干扰。

十一、总结

Skills 是 Codex 实现个性化、标准化、可复用工作流的核心能力，通过目录化管理、双模式调用、分层加载，既能满足个人提效需求，也能支撑团队规范落地。从简单的代码审查，到复杂的项目初始化、自动化部署，都可以封装为 Skill，让 Codex 始终按你的预期执行任务。配合 AGENTS.md、MCP 与 Plugins，可构建完整可控的 AI 开发工作流，大幅降低重复沟通与指令编写成本。

返回列表