Codex Skills使用指南：可复用任务���作流完整手册 ​

Codex Skills是可复用的任务工作流，将指令、资源和脚本打包为文件夹，让AI代理能可靠执行特定任务，实现"一次编写、处处使用"。

核心概念 ​

Skill本质 ​

包含SKILL.md（必选）、脚本和资源文件的文件夹，SKILL.md需有YAML前置元数据（name和description）。

工作机制：渐进式披露 ​

使用场景 ​

代码生成、文档处理、测试自动化、PR评审等重复性任务。

安装Skills（三种方式） ​

1. 全局安装（所有项目可用） ​

# 安装官方技能库
npx skills add Codex-Data/skills -g --yes

# 安装自定义技能
npx skills add https://github.com/your-username/your-skill -g

全局技能路径：

• Linux/macOS: ~/.codex/skills/
• Windows: %USERPROFILE%/.codex/skills/

2. 项目级安装（仅当前项目可用） ​

# 创建项目技能目录
mkdir -p .codex/skills

# 安装技能到项目
npx skills add Codex-Data/skills/pdf-cleaner --project

项目级技能路径：.codex/skills/（点开头，Git可忽略）

启动时需在项目目录下运行Codex才会加载。

3. VS Code图形化安装 ​

1. 打开Codex聊天面板（Ctrl+Shift+P → Codex: Open Chat）
2. 输入/install-skill + 技能仓库URL或名称
3. 选择安装范围（全局/项目）

调用Skills（两种方式） ​

1. 显式调用（推荐，精准可控） ​

CLI中：使用$前缀或/skills命令

# 列出所有可用技能
codex /skills

# 调用特定技能并传递参数
codex $pdf-cleaner --input report.pdf --output clean-report.md

VS Code中：输入/触发技能列表，选择后添加参数

/pdf-cleaner 处理这份PDF文件，提取文本并转为Markdown

2. 隐式调用（自动匹配） ​

当任务描述与技能description匹配时，Codex自动选择并调用：

帮我清理这份PDF中的格式错误，提取纯文本
# 若存在description为"清理PDF格式并提取纯文本"的技能，会自动触发

注意：

• 匹配准确性取决于技能描述的清晰度
• 可通过/disable-auto-skills临时关闭自动匹配

创建自定义Skills（四步流程） ​

Step 1：创建技能目录与文件 ​

# 全局创建
mkdir -p ~/.codex/skills/my-first-skill
cd ~/.codex/skills/my-first-skill
touch SKILL.md

# 或项目级创建
mkdir -p .codex/skills/my-first-skill
cd .codex/skills/my-first-skill
touch SKILL.md

Step 2：编写SKILL.md（核心文件） ​

---
name: "代码注释生成器"
description: "为JavaScript/TypeScript函数自动生成JSDoc风格注释，包含参数、返回值和示例"
metadata:
  short-description: "快速生成JSDoc注释"
  author: "你的名字"
  version: "1.0.0"
---

## 使用说明
1. 选中需要添加注释的函数
2. 调用此技能，自动生成符合规范的JSDoc注释

## 操作步骤
1. 分析函数签名，提取参数名和类型
2. 根据函数逻辑推断返回值类型和描述
3. 生成包含参数、返回值、示例的完整注释
4. 将注释插入函数上方

## 示例
输入：
function add(a, b) { return a + b }

输出：
/**
 * 计算两个数字的和
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 两个数的和
 * @example add(2, 3) // 5
 */
function add(a, b) { return a + b }

必填字段：name、description 可选字段：metadata下的所有内容，用于UI展示和分类

Step 3：添加辅助脚本（可选） ​

如果技能需要执行外部命令，可在技能目录中添加脚本文件：

touch comment_generator.py

在SKILL.md中引用：

## 依赖脚本
执行comment_generator.py处理AST分析，生成精准注释

Step 4：测试与调试 ​

# 本地测试
codex $my-first-skill --test

# 调试模式（显示详细执行日志）
codex $my-first-skill --debug

# 发布共享
# 推送到GitHub，通过npx skills add <github-url>安装

Skills管理命令 ​

最佳实践 ​

VS Code专用技巧 ​

总结 ​

Skills把重复性任务打包成可复用工作流，让AI代理执行更可靠。

关键词：Codex Skills, 任务工作流, Skills安装, 自定义Skill, SKILL.md, 渐进式披露