Codex Skill 创建和使用教程

想无msn

11人浏览 · 2026-06-29 19:03:12

想无msn · 2026-06-29 19:03:12 发布

1. Skill 是什么

Skill 是给 Codex 使用的一组可复用说明和工具。可以把它理解成一个“专项操作手册”：

普通对话中，Codex 需要临时理解你的需求，再决定怎么操作。
有了 skill 后，Codex 可以在遇到特定任务时自动加载对应说明，按固定流程执行。
如果任务需要脚本、模板、参考资料，也可以一起放进 skill 目录中。

适合做成 skill 的场景通常有这些特点：

经常重复执行，例如导出 Git 增量文件、生成固定格式文档、检查固定规则。
操作步骤容易出错，例如 Git 提交范围是否包含起始提交。
需要固定脚本辅助，例如 PowerShell、Python、SQL 脚本。
希望同事之间复用同一套操作流程。

2. Skill 能解决什么问题

Skill 的核心作用是把“经验”和“工具”沉淀下来，让后续使用更稳定。

以 export-git-updates 为例，它解决的是“根据 Git 提交范围导出增量文件”的问题。这个任务里有一个容易出错的点：

git A..B

这个范围表示“从 A 之后到 B”，不包含 A 本身。

所以如果用户说“从某提交之后导出，不包含这个提交”，可以直接用这个提交作为 StartRef。如果用户说“包含这个提交和之后”，就需要用这个提交的父提交作为 StartRef。

把这个规则写进 skill 后，Codex 后续处理类似任务时就不需要每次重新解释。

3. Skill 的基本目录结构

一个 skill 本质上是一个文件夹，最少需要 SKILL.md。

推荐结构如下：

skill-name/
├─ SKILL.md
├─ agents/
│  └─ openai.yaml
└─ scripts/
   └─ tool-script.ps1

各文件作用如下：

文件或目录	是否必需	作用
`SKILL.md`	必需	写 skill 名称、触发描述、执行流程
`agents/openai.yaml`	推荐	配置界面展示名称、简介、默认提示
`scripts/`	可选	存放可复用脚本
`references/`	可选	存放较长的参考资料
`assets/`	可选	存放模板、图片、字体等输出资源

4. SKILL.md 的关键内容

SKILL.md 由两部分组成：

顶部 YAML frontmatter
正文说明

示例：

---
name: export-git-updates
description: Export a ZIP package of changed files between Git commits using a bundled PowerShell script. Use when Codex is asked to "帮我从某提交开始导出增量文件", "导出增量代码", "打增量包", "导出某个提交及之后的文件", "include this commit and later", or otherwise package changed files from a Git start ref to HEAD or another end ref.
---

# Export Git Updates

## Overview

Use `scripts/export-git-updates.ps1` to export changed files from a Git repository into an `update-output` package directory plus a ZIP file.

这里最重要的是 description。Codex 是否自动触发这个 skill，主要看 description 是否准确覆盖使用场景。

写 description 时建议包含：

这个 skill 做什么
什么用户说法应该触发它
关键关键词，例如“导出增量代码”“打增量包”“从某提交之后导出”

5. 创建 skill 的推荐步骤

5.1 确定 skill 名称

名称建议使用小写英文、数字和连字符。

例如：

export-git-updates

不要使用空格、中文、下划线或特殊符号。

5.2 选择安装目录

个人 skill 通常放在：

C:\Users\<用户名>\.codex\skills

5.3 创建目录结构

可以手工创建，也可以用 skill-creator 的初始化脚本。

手工创建示例：

New-Item -ItemType Directory -Force -Path C:\Users\<用户名>\.codex\skills\export-git-updates
New-Item -ItemType Directory -Force -Path C:\Users\<用户名>\.codex\skills\export-git-updates\agents
New-Item -ItemType Directory -Force -Path C:\Users\<用户名>\.codex\skills\export-git-updates\scripts

5.4 编写 SKILL.md

SKILL.md 里要写清楚：

什么时候使用这个 skill
执行前需要确认什么
具体命令怎么运行
运行后怎么校验
哪些事情不能做，例如不要覆盖文件、不要运行编译测试

5.5 放入脚本

如果任务依赖脚本，把脚本放进 scripts/ 目录。

以导出增量文件为例：

export-git-updates/
└─ scripts/
   └─ export-git-updates.ps1

这样同事只要安装 skill，就能复用同一份脚本，不需要每个项目仓库都放一份。

5.6 编写 agents/openai.yaml

示例：

interface:
  display_name: "Git Update Export"
  short_description: "Export changed files from Git commits"
  default_prompt: "Use $export-git-updates to export changed files starting from a specific Git commit."

注意 default_prompt 里要带 $skill-name，例如 $export-git-updates。

6. export-git-updates 示例

6.1 当前目录结构

本机已经创建好的导出 skill 在：

C:\Users\用户\.codex\skills\export-git-updates

目录结构如下：

export-git-updates/
├─ SKILL.md
├─ agents/
│  └─ openai.yaml
└─ scripts/
   └─ export-git-updates.ps1

6.2 这个 skill 的用途

export-git-updates 用于根据 Git 提交范围导出变更文件，并生成：

更新包目录
ZIP 压缩包
提交清单 commit-list.csv
文件清单 file-list.csv
汇总文件 summary.txt

导出脚本基于 Git 提交对象读取文件，不依赖当前工作区内容。因此本地未提交修改不会被误打包。

6.3 常见触发说法

可以这样要求 Codex：

[$export-git-updates] 导出当前项目从 5e062f06 之后到 HEAD 的变更文件，不包含这个提交

也可以这样说：

帮我从某提交开始导出增量文件

如果 skill 已被自动识别，Codex 会读取 SKILL.md 并按里面的流程执行。

6.4 包含或不包含起始提交

这是使用这个 skill 时最重要的规则。

不包含起始提交：

导出 5e062f06 之后的提交，不包含 5e062f06

实际 Git 范围：

5e062f06..HEAD

脚本参数：

-StartRef 5e062f06 -EndRef HEAD

包含起始提交：

导出 5e062f06 这个提交和之后的提交

需要先找到父提交：

git rev-parse --verify "5e062f06^"

然后使用父提交作为 StartRef。

原因是脚本内部使用的是：

StartRef..EndRef

这个范围不会包含 StartRef 本身。

7. 使用 export-git-updates 的完整流程

假设要在仓库：

E:\sunline\dm-dbs\dm-dq-sql-editor

导出 5e062f06 之后到 HEAD 的变更文件，并且不包含 5e062f06。

7.1 进入目标仓库

Set-Location E:\sunline\dm-dbs\dm-dq-sql-editor

7.2 查看工作区状态

git status --short

即使有本地修改，也不会影响导出包内容。但需要在结果里说明当前工作区存在本地修改，避免误解。

7.3 确认提交存在

git rev-parse --verify "5e062f06^{commit}"
git rev-parse --verify HEAD

7.4 预览提交范围

git log --reverse --oneline "5e062f06..HEAD"

7.5 预览变更文件数量

git diff --name-status --find-renames=90% --diff-filter=ACDMRT "5e062f06..HEAD"

7.6 检查输出目录是否已存在

Test-Path -LiteralPath .\update-output\update_sql_editor_after_5e062f06_to_HEAD
Test-Path -LiteralPath .\update-output\update_sql_editor_after_5e062f06_to_HEAD.zip

如果已经存在，不要直接覆盖，除非用户明确要求。

7.7 执行导出

powershell -ExecutionPolicy Bypass -File C:\Users\juanmao\.codex\skills\export-git-updates\scripts\export-git-updates.ps1 `
  -StartRef 5e062f06 `
  -EndRef HEAD `
  -PackageName update_sql_editor_after_5e062f06_to_HEAD

7.8 校验结果

Get-Content -Encoding UTF8 -Path .\update-output\update_sql_editor_after_5e062f06_to_HEAD\summary.txt
(Import-Csv -Path .\update-output\update_sql_editor_after_5e062f06_to_HEAD\commit-list.csv).Count
(Import-Csv -Path .\update-output\update_sql_editor_after_5e062f06_to_HEAD\file-list.csv).Count
Get-Item -LiteralPath .\update-output\update_sql_editor_after_5e062f06_to_HEAD.zip | Select-Object FullName,Length,LastWriteTime

最终需要向用户说明：

导出目录
ZIP 包路径
提交数量
变更文件数量
已打包文件数量
删除文件数量
是否运行编译或测试

8. 如何分享给同事使用

把整个 skill 文件夹复制给同事，不要只复制 SKILL.md。

需要复制：

export-git-updates/
├─ SKILL.md
├─ agents/
│  └─ openai.yaml
└─ scripts/
   └─ export-git-updates.ps1

同事放到自己的目录：

C:\Users\<同事用户名>\.codex\skills\export-git-updates

然后重新打开 Codex 或新建会话，使 skill 被重新加载。

安装后可以用下面命令检查文件是否齐全：

Get-ChildItem -Recurse C:\Users\<同事用户名>\.codex\skills\export-git-updates

9. 常见问题

9.1 skill 没有自动触发怎么办

可以显式指定 skill：

[$export-git-updates] 帮我导出当前项目从 5e062f06 之后到 HEAD 的变更文件

如果还是没有触发，检查：

skill 是否放在 C:\Users\<用户名>\.codex\skills 下
文件夹名是否是 export-git-updates
是否存在 SKILL.md
SKILL.md 的 frontmatter 是否包含 name 和 description
是否已经重启 Codex 或开启新会话

9.2 PowerShell 脚本不能执行怎么办

导出命令里使用：

powershell -ExecutionPolicy Bypass -File <脚本路径>

这会绕过当前会话的执行策略限制。如果仍失败，需要检查脚本路径是否正确。

9.3 输出目录已经存在怎么办

默认不要覆盖。

可以选择换一个 PackageName，例如：

-PackageName update_sql_editor_after_5e062f06_to_HEAD_v2

只有用户明确要求覆盖时，才加：

-Force

9.4 本地未提交修改会不会被打包

不会。

export-git-updates.ps1 从 Git 提交对象导出文件，不读取当前工作区文件内容。但仍建议在执行前查看：

git status --short

并在结果中说明工作区是否有本地修改。

9.5 要不要运行编译或测试

默认不运行。

这个 skill 的目标是导出变更文件，不是验证代码构建。只有用户明确要求编译或测试时才执行。

10. 编写 skill 的建议

写新 skill 时建议遵守以下规则：

SKILL.md 保持简洁，只放核心流程。
复杂脚本放到 scripts/，不要把大段脚本写在说明里。
详细参考资料放到 references/，按需读取。
模板、图片、字体等资源放到 assets/。
description 要写清楚触发场景，这是自动触发的关键。
对容易误操作的地方写清楚保护规则，例如是否允许覆盖、是否允许删除、是否运行测试。

11. 最小可用模板

创建新 skill 时，可以从这个模板开始：

---
name: my-skill-name
description: Explain what this skill does and when Codex should use it. Include common user phrases that should trigger it.
---

# My Skill Name

## Overview

Describe the task this skill handles.

## Workflow

1. Confirm the target context.
2. Check required inputs.
3. Run the required command or script.
4. Verify the output.
5. Report the result.

## Guardrails

- Do not overwrite existing files unless the user explicitly asks.
- Do not run compile or tests unless the user explicitly asks.
- Report any assumptions before acting.

这个模板可以根据具体任务继续补充脚本、参考资料或资源文件。