Codex Skill 安装与使用教程（新手村）

把 Codex 想象成一个新同事：你每次都要把要求从头讲一遍，它能干活，但总差一点默契。Skill（技能） 就是写给这个同事的工作手册。你把「遇到文档任务就按这套流程来」写进一个文件，之后 Codex 自己会照着做。

这篇文章从零开始讲：技能是什么、Skill放在哪、三种安装方式、日常怎么用、怎么做一个自己的Skill。

0. 开始之前，先确认三件事

• [x] 电脑上装了 Codex（桌面应用或命令行版都可以，本文例子两边通用）。
• [x] 网络能访问 GitHub（安装技能需要从网上下载，除非你走 3.3 节的手动复制）。
• [x] 知道自己的 Windows 用户名（后面的路径会用到）。

1. Skill 是什么

1.1 一句话解释

技能是一个文件夹，里面放着一份「说明书」SKILL.md，告诉 Codex 某一类任务该怎么做。Codex 装上它以后，遇到相关任务会自动翻开说明书照着执行。

没有Skill的时候，你每次都要说：

帮我写一份会议纪要，按时间、参会人、议题、结论、待办来整理，待办要标责任人和截止时间……

有Skill的时候，你只需要说：

写个会议纪要。

剩下的 Codex 自己知道。

1.2 为什么需要Skill

• 可复用：一次写好，以后每次都能用。
• 可分享：一个文件夹拷给同事，或者放进 Git 仓库，团队就都用上了。
• 可沉淀：你反复交代的流程，不用每次重新描述。

1.3 一个Skill长什么样

一个技能文件夹里，SKILL.md 是唯一的必需文件，它分两部分：

其余文件夹都是可选的，按需添加：

⚠️ 新手提示：只写一个 SKILL.md 就够了，后面几个文件夹用不到就先不管。

1.4 几个名词先对齐

一句话总结：插件是个大箱子，技能是箱子里的东西。

2. Skill放在哪里

2.1 三个层级

• 新手优先用 用户级，放在 C:\Users\<你的用户名>\.codex\skills\，省心，哪里都能用。
• 想跟团队共享、让技能跟着仓库走，就放 项目级（建议用 .codex\skills\），提交到 Git 就行。
• 系统级是 Codex 自己管理的，你不需要去碰它，也看不到它。

2.2 怎么找到你的Skill目录（Windows）

按 Win + R，输入下面这行，回车：

%USERPROFILE%\.codex\skills

或者在 PowerShell / 终端里输入：

explorer "$env:USERPROFILE\.codex\skills"

📌 目录不存在就先不管，安装技能时会自动创建，你也可以手动新建一个。

2.3 CODEX_HOME 是什么（非必需）

默认情况下，技能目录就是 ~/.codex/skills（Windows 上为 C:\Users\<你的用户名>\.codex\skills）。
如果你设置了环境变量 CODEX_HOME（或某些版本中为 OPENAI_CODEX_HOME），技能目录会变为 %CODEX_HOME%\skills。

⚠️ 绝大多数情况下不用设置这个变量，保持默认即可。本文按默认路径讲解。

3. 安装技能

3.1 方法 A：让 Codex 帮你装（推荐新手）

🌐 此方法需要联网下载Skill文件。

这是最简单的方式，你不需要碰命令行，也不需要手动下载任何东西。

1. 打开 Codex，新开一个会话。
2. 输入：帮我安装一个Skill，回车。
3. Codex 会调用自带的 skill-installer，列出官方精选技能，大概长这样： ```text 你：帮我安装一个Skill Codex：官方Skill技能如下：
   1. humanizer —— 让文字读起来像人写的
   2. code-review —— 按标准审查代码变更
   3. pdf —— 处理 PDF 文档 …… 想装哪个？ 你：装 humanizer Codex：已安装。新会话里就能用了。 ```
4. 输入技能名字，等它装完。
5. 新开一个会话（或重启 Codex），Skill就生效了。

整个过程不用手动运行任何脚本，skill-installer 会自动完成下载和安装。

3.2 方法 B：从 GitHub 装

🌐 此方法需要联网。

官方Skill都放在 github.com/openai/skills 仓库里： - 精选Skill在 skills/.curated/ - 实验Skill在 skills/.experimental/

装某个Skill时，把仓库或路径直接发给 Codex：

帮我把这个Skill装上：
https://github.com/openai/skills/tree/main/skills/.experimental/xxx

任何公开 GitHub 仓库里的技能都能这样装。私有仓库也可以，前提是你本机配置了对应的 Git 凭证。

💡 一次想装多个Skill，就把多个 URL 或路径用空格分隔，或者分多条消息发送，Codex 会逐个处理。

3.3 方法 C：手动复制（离线也能用）

不想联网，或者想装一个没发布到 GitHub 的技能，直接手动复制：

1. 拿到技能文件夹（下载 ZIP 解压，或者 git clone）。
2. 确认文件夹里直接有 SKILL.md，不是又套了一层。
3. 把整个文件夹复制到 C:\Users\<你的用户名>\.codex\skills\。
4. 重新打开 Codex（或新开一个会话）。

⚠️ 注意两点： - 复制的是整个文件夹，不是只复制 SKILL.md 一个文件（脚本、参考资料都在文件夹里）。 - 文件夹名最好就是技能名（如 humanizer），方便识别，也避免同名冲突。

3.4 怎么确认装好了

新开一个会话后，任选一种方式检查：

• 桌面版：在输入框里输入 $，弹出的技能列表里应该能看到它。
• 命令行版：输入 /skills，会列出当前所有Skill。
• 直接看目录：C:\Users\<你的用户名>\.codex\skills\ 里多了对应文件夹。

如果看不到，先看 4.4 节的排查清单。

4. 使用技能

4.1 方式一：自动触发，什么都不用做

技能装好后，你正常说话就行。Codex 在会话开始时读取所有已安装Skill的 name 和 description，当你的请求语义上与某个Skill的描述相匹配时，它会自动加载该Skill的详细指令并执行。

比如你装了会议纪要Skill，然后说：

帮我把下面这段会议记录整理成纪要。

Codex 看到 description 里写着「在整理会议记录时使用」，就会自动调用它。

所以安装Skill时那句话是对的：装完就能用，不需要额外命令。

4.2 方式二：显式调用，指定用哪个

想明确指定某个Skill，就在输入框里输入 $ 加Skill名：

$humanizer 把我下面这段话改得更像人写的

输入 $ 本身会弹出已安装Skill的列表，选一个就行。

💻 命令行版：先输入 /skills 查看列表，然后直接输入技能名（不含 $）并跟上提示词，例如： text humanizer 把这段话改得更自然 具体语法请参考你使用的命令行客户端的帮助。

4.3 插件里的Skill

Skill也可以跟着插件一起装。在 Codex 的插件面板里安装插件后，插件自带的Skill立刻生效。调用方式取决于插件实现，有些支持 @插件名 快速唤起，有些则仍需用 $Skill名 或自动匹配。

💡 推荐优先使用 $Skill名 或依赖自动触发，具体可查阅插件文档。插件主要面向「一套打包好的工作流」，普通用户从Skill开始就够用了。

4.4 技能没生效？按这个清单查

5. 创建自己的Skill

5.1 最快的方式：让 Codex 帮你建

直接说：

帮我创建一个Skill，用来把零散需求整理成开发任务清单。

Codex 会调用自带的 skill-creator，帮你建好文件夹和 SKILL.md 骨架，你只需要补充具体步骤。

5.2 手动创建：一个完整例子

我们做一个「会议纪要」Skill，手动走一遍全流程。

第一步，建文件夹：

C:\Users\<你的用户名>\.codex\skills\meeting-notes\

第二步，在文件夹里新建 SKILL.md，内容如下：

---
name: meeting-notes
description: 把会议记录整理成结构化纪要。当用户提到会议纪要、会议记录、meeting notes、会议复盘时使用。
---

# 会议纪要Skill

把用户提供的会议原始记录整理成下面这个结构：

1. 会议主题与时间
2. 参会人
3. 讨论要点（按主题分组）
4. 决定的事项
5. 待办事项（责任人 + 截止时间）

要求：
- 用中文输出。
- 保留原始记录里的数字、人名，不要编造。
- 待办用表格呈现。
- 原始记录里没有的信息，写「未记录」，不要自己补。

第三步，保存文件，新开一个会话，输入：

写个会议纪要

或者：

$meeting-notes 把这段会议记录整理一下

看到输出格式符合预期，这个技能就算建好了。不满意就回去改 SKILL.md，改完新开会话再试。

5.3 命名规则

• 用小写字母、数字、连字符，比如 meeting-notes、code-review。
• 名字尽量短，不超过 64 个字符。
• 文件夹名 = 技能名 = name 字段，三者保持一致。

5.4 验证Skill

• 新会话里输入 $，列表里能看到 meeting-notes，说明格式没问题。
• 官方 skill-creator 内置了校验脚本（如 validate_skill.py），会检查元信息、命名和未填完的占位符，你可以在创建时让它自动运行。
• 最实在的验证是实际用一次：让 Codex 按你的技能跑一遍，看结果对不对。

5.5 description 的写法（最重要的一步）

description 决定 Codex 什么时候自动调用技能，所以写的是「什么时候用」，不是「它是什么」。

❌ 反面例子（太抽象）：

description: 这是一个会议纪要技能。

✅ 好一点的写法（明确触发场景）：

description: 把会议记录整理成结构化纪要。当用户提到会议纪要、会议记录、meeting notes、会议复盘时使用。

📌 技巧：写得太泛（「处理文档」）会让 Codex 乱用，写得太窄（「只处理周二的站会」）又会漏用。把常见的触发说法列在 description 里，是最实用的做法。

6. 常见问题

Q1：装了Skill，但 Codex 好像没反应？
先看 4.4 节的清单，八成是新会话没开，或者Skill放错层级。

Q2：两个同名Skill冲突怎么办？
同名Skill不会合并。建议保持名字唯一，装之前看一眼是否已存在；手动复制时也别覆盖别人的文件夹。

Q3：SKILL.md 格式写错了会怎样？
缺 name 或 description 的话，Skill不会被识别。检查开头 --- 有没有成对，字段有没有写对。

Q4：Skill安全吗？
技能本质上是给 Codex 的指令和脚本，安装前打开 SKILL.md 和 scripts/ 看一眼内容。只装官方仓库、或你信得过的来源。任何让你「把密钥发过去」「执行不明命令」的Skill，直接拒绝。

Q5：Skill会读我的私人文件吗？
技能本身是本地文件，Codex 只在任务需要时读取它。但你要知道：装一个Skill，等于告诉 Codex「这类任务可以照这个说明做」。所以先读一遍再装，是对自己负责。

Q6：想换一台电脑 / 跟同事共享？
把整个技能文件夹复制过去，或放进 Git 仓库，两边就都有了。不需要重新安装。

Q7：官方精选Skill有哪些？
看 github.com/openai/skills 的 skills/.curated/ 目录，或在 Codex 里输入「列出可安装的Skill」。常见的有 humanizer（文字去 AI 味）、code-review（代码审查）等。

7. 资源与下一步

• 📘 官方文档：https://developers.openai.com/codex/skills
• 📦 官方Skill仓库：https://github.com/openai/skills
• 🔌 官方插件文档：https://developers.openai.com/codex/plugins

🚀 建议的下一个动作

1. 用 方法 A 装一个 humanizer，把一段自己写的话丢给它试试。
2. 按 5.2 节做一个自己的小技能，哪怕只是「每周总结格式」。
3. 玩熟了之后，再研究插件和 agents/openai.yaml。

🎯 Skill这个东西，装一个、用一次，比看十篇文章都强。动手吧！