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 由两部分组成：

1. 顶部 YAML frontmatter
2. 正文说明

示例：

---
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.

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