什么是 Skill？
给 AI 的「上岗培训手册」——告诉它在特定场景下该做什么、怎么做、用什么工具。
Codex 本体
一个聪明但刚入职的新员工
Skill
你给他的某项工作的操作手册
触发 Skill
让他做那项工作时，自动翻开手册
Skill 不是插件、不是 API、不是代码库。它是一个 Markdown 文件（SKILL.md），用自然语言告诉 Codex 在特定场景下该如何行动。
Skill 的最小结构
只需要一个文件夹 + 一个文件。
my-skill/
└── SKILL.md ← 唯一必须的文件⚠️ description 是 Skill 的「触发器」，Codex 通过它决定是否使用这个 Skill。
--- (YAML 头部)
name: my-skill
description: 一句话描述...
---# 正文 (Markdown)
告诉 Codex 具体该怎么做...
只在 Skill 被触发后才会加载| 组成部分 | 说明 |
|---|---|
| YAML 头部 | --- 之间，只有 name 和 description 两个必填字段 |
| Markdown 正文 | 具体的操作指令，只在 Skill 被触发后才会加载 |
你的第一个 Skill
跟着三步走，5 分钟完成。
Step 1
创建文件夹
$ mkdir -p ~/.codex/skills/hello-world💡 Skill 放在 ~/.codex/skills/ 目录下，Codex 会自动扫描并加载。文件夹名 = Skill 名，用小写 + 连字符。修改后下次对话自动生效，无需重启。
Step 2
编写 SKILL.md
---
name: hello-world
description: 用指定语言说 Hello。当用户要求用某种语言打招呼、说 hello、问好时触发。
---
# Hello World 技能
## 执行步骤
1. 从用户输入中识别目标语言（默认：中文）
2. 用该语言输出 "Hello, World!"
3. 附上语言的趣味小知识（一句话）
## 多语言示例
- 中文：你好，世界！（全球使用人数最多的语言）
- 英语：Hello, World!（源自 1978 年 C 语言教材）
- 日语：こんにちは、世界！（敬体表达）
- 法语：Bonjour, le monde !（感叹号前需要一个空格）
- 韩语：안녕하세요, 세계!（有敬语和非敬语之分）
## 注意事项
- 如果用户没指定语言，默认用中文
- 只输出一种语言的结果，不要列出所有语言
- 保持简洁，不要解释 Hello World 的历史
Step 3
测试效果
在 Codex 中直接对话即可触发：
👤 用日语说 hello
⬇
🤖 こんにちは、世界！
日语有敬体和平体之分，这是敬体表达。
🎉 就这么简单！你已经完成了第一个 Skill。
进阶：加一个脚本
很多 Skill 不只是告诉 Codex「怎么想」，还需要「怎么做」。
带脚本的翻译助手
translate-helper/
├── SKILL.md
└── scripts/
└── detect_language.py# detect_language.py
def detect(text):
if 包含中文字符:
return "中文"
elif 包含日文假名:
return "日语"
else:
return "英语"目录结构扩展
scripts/
可执行代码（Python / Bash）
references/
参考文档（加载到上下文）
assets/
输出资源（模板、图片等）
💡 只创建你实际需要的目录
写好 description 的 3 个技巧
description 决定 Skill 能不能被正确触发。
01
明确说出「什么时候用」
❌ 一个处理 PDF 的工具
✅ 创建、编辑和提取 PDF。当用户需要生成报告、合并拆分、提取文字时触发。
02
覆盖用户可能的说法
❌ 画图工具
✅ 生成数据可视化图表。当用户要求画图、做图表、画柱状图、饼图时触发。
03
说明边界（什么时候不用）
❌ 处理所有文档
✅ 处理 .docx 格式的 Word 文档。不适用于 PDF（使用 pdf skill）。
写好正文的 4 个原则
精简为王
上下文窗口是公共资源。
只写 Codex 不知道的东西。
只写 Codex 不知道的东西。
用例子代替解释
"经分析，该方案优于替代方案 A"
← 好的
"我们觉得可以试试"
← 差的
← 好的
"我们觉得可以试试"
← 差的
控制自由度
高自由：文字原则
中自由：伪代码 + 参数
低自由：具体脚本步骤
中自由：伪代码 + 参数
低自由：具体脚本步骤
祈使句命令式
❌ "用户可能需要..."
✅ "根据数据生成报告"
✅ "根据数据生成报告"
控制自由度详解
| 自由度 | 适用场景 | 指令形式 |
|---|---|---|
| 高自由 | 多种方式都行，靠判断 | 文字描述原则 |
| 中自由 | 有推荐模式，允许变通 | 伪代码 + 参数说明 |
| 低自由 | 操作脆弱，必须一致 | 具体脚本，明确步骤 |
## 低自由度示例（必须严格执行）
1. 执行 scripts/backup.sh 备份当前数据
2. 等待备份完成，确认输出包含 "Backup OK"
3. 执行 scripts/migrate.py 进行数据迁移
4. 如果报错，立即执行 scripts/rollback.sh 回滚
⚠️ 顺序不可改变，步骤 2 不可跳过。用脚手架快速创建
Codex 内置了 init_skill.py 脚本，可以一键创建 Skill 骨架。
# 最简模式
python3 ~/.codex/skills/.system/skill-creator/scripts/init_skill.py my-skill \
--path ~/.codex/skills
# 带脚本目录
python3 ~/.codex/skills/.system/skill-creator/scripts/init_skill.py my-skill \
--path ~/.codex/skills --resources scripts
# 带示例文件
python3 ~/.codex/skills/.system/skill-creator/scripts/init_skill.py my-skill \
--path ~/.codex/skills --resources scripts,references --examples创建后，编辑生成的 SKILL.md，把 TODO 部分替换成你的实际内容即可。
Skill 编写速查
文件夹名
小写 + 连字符，如
rental-house-skillSKILL.md
唯一必须文件，含 YAML 头部 + Markdown 正文
description
清晰说明做什么 + 何时触发（1-3 句话）
正文
精简、命令式、用例子说明、控制自由度
scripts/
可执行脚本（Python / Bash）
references/
参考文档（加载到上下文供查阅）
assets/
输出资源（模板、图片，不加载到上下文）
常见问题
Q：Skill 创建后 Codex 找不到？
检查路径是否在
~/.codex/skills/ 下，且文件夹内必须有 SKILL.md。Q：Skill 被触发了但执行结果不对？
检查正文指令是否足够明确。加入具体的步骤编号和示例，降低 Codex 的自由度。
Q：description 写多长合适？
1-3 句话。重点是覆盖用户的触发场景。不要太长（浪费上下文），也不要太短（无法触发）。
Q：Skill 里能调用外部 API 吗？
可以，在
scripts/ 目录放脚本，通过 curl 或 Python requests 调用。Skill 本身是自然语言指令，具体执行靠脚本。Q：修改了 Skill 后需要重启 Codex 吗？
不需要。Codex 每次对话时会重新扫描 Skill 目录，修改后下次对话自动生效。
动手试试吧！
打开终端，创建你的第一个 Skill ⚡