Codex Skills 完全教程：从入门到生产级

---

目录

1. 什么是 Skill
2. 理解 Skill 的运行原理
3. Skill 的文件结构
4. 第一个 Skill：手把手入门
5. SKILL.md 编写指南
6. Bundled Resources 详解
7. agents/openai.yaml 元数据
8. 中级技巧：渐进式披露设计
9. 中级技巧：自由度控制
10. 进阶：Forward-Testing
11. 进阶：Production 级 Skill 设计模式
12. 完整实战案例
13. 调试与排错
14. 最佳实践速查表

---

1. 什么是 Skill

Skill 是一个自包含的文件夹，作用是把 Codex 从通用型 Agent 转变成某个领域的专家。

Skill 能提供什么

能力	说明
专项工作流	针对特定领域的多步骤流程
工具集成	如何使用特定文件格式或 API 的指令
领域知识	公司专有知识、Schema、业务逻辑
捆绑资源	可直接运行的脚本、参考文档、模板资产

什么不是 Skill

• Skill 不是安装包管理器
• Skill 不是 README 或用户文档
• Skill 不是 CHANGELOG 或安装指南

Skill 是给另一个 Codex 实例看的上岗培训手册。

---

2. 理解 Skill 的运行原理

这是最重要的概念，理解了这个才能写出好 Skill。

上下文窗口就是公共资源

Codex 的上下文窗口是有限的，它同时要容纳：系统提示词、对话历史、其他 Skill 的元数据、以及用户当前的请求。你的 Skill 在和所有这些东西竞争空间。

三级加载机制

Level 1: 元数据（name + description）  → 始终在上下文中（~100 词）
Level 2: SKILL.md 正文                → Skill 被触发时才加载（<5k 词）
Level 3: Bundled Resources            → 按需加载（无上限，因为脚本可直接执行）

这意味着：

• Description 写得好不好，直接决定 Skill 能不能被正确触发
• SKILL.md 要尽量精简，超过 500 行就应该拆分到 references/
• 脚本是最省 token 的，执行时不需要读进上下文

---

3. Skill 的文件结构

my-skill/
├── SKILL.md              ← 必须：核心指令文件
├── agents/
│   └── openai.yaml       ← 推荐：UI 展示元数据
├── scripts/              ← 可选：可执行脚本
│   ├── rotate_pdf.py
│   └── extract_text.py
├── references/           ← 可选：按需加载的参考文档
│   ├── api_docs.md
│   └── schema.md
└── assets/               ← 可选：输出用的模板/图片/字体
    ├── template.pptx
    └── logo.png

各目录职责

SKILL.md（必须）

• YAML 前置元数据（name + description）→ 决定触发条件
• Markdown 正文 → 触发后读取的具体指令

scripts/ — 可执行代码

• 适合：需要确定性可靠执行、或每次都在重写同样逻辑的代码
• 优势：Token 高效，可以直接执行不需要读进上下文
• 例如：PDF 旋转脚本、数据转换脚本

references/ — 参考文档

• 适合：Codex 需要查阅但不需要始终加载的详细信息
• 例如：API 文档、数据库 Schema、公司政策、领域知识
• 最佳实践：超过 1 万词的文件，在 SKILL.md 里加 grep 搜索指引

assets/ — 输出资源

• 适合：最终输出里要用的文件，不需要读进上下文
• 例如：PPT 模板、logo 图片、字体文件、项目脚手架

什么不该放进 Skill

❌ README.md
❌ INSTALLATION_GUIDE.md
❌ QUICK_REFERENCE.md
❌ CHANGELOG.md
❌ 测试说明
❌ 用户可见文档

Skill 是给 AI 看的，不是给人看的。

---

4. 第一个 Skill：手把手入门

4.1 使用 init 脚本创建

# 运行初始化脚本
python3 ~/.codex/skills/.system/skill-creator/scripts/init_skill.py \
  hello-world \
  --path ~/.codex/skills \
  --resources scripts,references

这会创建：

~/.codex/skills/hello-world/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
└── references/

4.2 编写 SKILL.md

把生成的模板替换为以下内容：

---
name: hello-world
description: "Use when user asks to create a hello-world project in any language. Supports Python, JavaScript, Go, and Rust. Handles project setup, basic file structure, and a runnable entry point."
---

# Hello World Skill

## Supported Languages

| Language | Entry File | Run Command |
|----------|-----------|-------------|
| Python   | main.py   | python3 main.py |
| JavaScript | index.js | node index.js |
| Go       | main.go   | go run main.go |
| Rust     | main.rs   | cargo run |

## Workflow

1. Detect language from user request (default: Python if unspecified).
2. Create entry file with print/hello-world logic.
3. If Go or Rust, also create go.mod / Cargo.toml.
4. Print the run command for the user.

## Scripts

- `scripts/validate_project.py <lang> <dir>` — Checks that the generated project has correct structure.

4.3 创建脚本

# scripts/validate_project.py
#!/usr/bin/env python3
"""Validate that a hello-world project has the expected structure."""
import sys
from pathlib import Path

REQUIRED_FILES = {
    "python": ["main.py"],
    "javascript": ["index.js"],
    "go": ["main.go", "go.mod"],
    "rust": ["main.rs", "Cargo.toml"],
}

def validate(lang: str, project_dir: str) -> bool:
    files = REQUIRED_FILES.get(lang)
    if not files:
        print(f"Unknown language: {lang}")
        return False
    base = Path(project_dir)
    ok = True
    for f in files:
        if not (base / f).exists():
            print(f"Missing: {f}")
            ok = False
    if ok:
        print(f"Project structure OK for {lang}")
    return ok

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("Usage: validate_project.py <lang> <dir>")
        sys.exit(1)
    success = validate(sys.argv[1], sys.argv[2])
    sys.exit(0 if success else 1)

4.4 验证

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  ~/.codex/skills/hello-world

输出 Skill is valid! 就说明结构正确。

---

5. SKILL.md 编写指南

5.1 Frontmatter（必须）

---
name: my-skill-name
description: "完整描述，告诉 Codex 什么时候该用这个 Skill。"
---

规则：

• name：全小写 + 连字符，不超过 64 字符，只用 [a-z0-9-]
• description：不超过 1024 字符，不能包含 < 或 >
• description 是唯一的触发机制，必须写清楚：做什么 + 什么时候用

Description 范例：

# ❌ 太模糊
description: "A skill for working with documents"

# ❌ 缺少触发条件
description: "Create and edit DOCX files"

# ✅ 完整
description: "Comprehensive document creation, editing, and analysis with support for
tracked changes, comments, formatting preservation, and text extraction. Use when
Codex needs to work with professional documents (.docx files) for: (1) Creating new
documents, (2) Modifying or editing content, (3) Working with tracked changes,
(4) Adding comments, or any other document tasks"

5.2 Body 编写原则

用祈使句

# ❌ 描述式
This skill allows you to rotate PDF pages.

# ✅ 指令式
Rotate PDF pages using the rotation script.

只写 Codex 不知道的东西

# ❌ 废话连篇（Codex 知道 Python 怎么写）
## Python Basics
Python is a programming language created by Guido van Rossum...
Use `def` to define functions. Use `for` to iterate...

# ✅ 只写领域特定知识
## Internal Schema
The `orders` table has a `status` column with values:
`pending`, `shipped`, `delivered`, `returned`.
Join with `customers` on `customer_id`.

结构清晰，按需组织

根据 Skill 的性质选择合适的结构：

结构类型	适用场景	示例
工作流型	顺序步骤流程	PDF 处理：渲染 → 检查 → 输出
任务型	多种独立操作	PDF Skill：合并 / 拆分 / 提取文本
指南型	规范或标准	品牌规范：颜色 / 字体 / 间距
能力型	一体化多功能系统	产品管理：多维度能力

---

6. Bundled Resources 详解

6.1 scripts/ — 确定性执行

什么时候放脚本：

• 同样的代码每次都在重写
• 操作容易出错，需要确定性可靠执行
• 可以参数化复用的逻辑

脚本的优势：

• Token 高效：直接 exec_command 执行，不需要读进上下文
• 确定性：不像 LLM 生成的代码可能有变体
• 可测试：可以像普通代码一样写测试

# 执行脚本（推荐方式）
python3 scripts/rotate_pdf.py input.pdf 90 output.pdf

# 或者 bash 脚本
bash scripts/deploy.sh staging

6.2 references/ — 按需加载

什么时候放参考文档：

• 详细 API 文档
• 数据库 Schema
• 公司内部政策
• 复杂领域知识
• 超过 500 行的详细内容

大文件技巧：

## API Reference

For detailed endpoint documentation, see `references/api_docs.md`.
To find a specific endpoint: `grep -n "endpoint_name" references/api_docs.md`

6.3 assets/ — 输出用资源

什么时候放资产文件：

• PPT/Word 模板
• Logo、图片
• 字体文件
• 项目脚手架/模板目录
• 不需要读进上下文，直接复制或修改使用的文件

assets/
├── template.pptx        ← PowerPoint 模板
├── brand-logo.png       ← 公司 logo
├── hello-world/         ← 前端项目脚手架
│   ├── index.html
│   ├── style.css
│   └── app.js
└── fonts/
    └── custom.ttf

---

7. agents/openai.yaml 元数据

这个文件是给 UI 展示用的，不是给 Codex 逻辑用的。

interface:
  display_name: "My Skill Name"         # UI 列表显示名
  short_description: "Help with X tasks" # 25-64 字符的简短描述
  icon_small: "./assets/small.png"       # 小图标（可选）
  icon_large: "./assets/large.svg"       # 大图标（可选）
  brand_color: "#3B82F6"                 # UI 强调色（可选）
  default_prompt: "Use $my-skill to help with ..." # 默认提示（可选）

dependencies:
  tools:
    - type: "mcp"
      value: "github"
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"

policy:
  allow_implicit_invocation: true   # false 则只允许 $skill 手动触发

用脚本自动生成

python3 ~/.codex/skills/.system/skill-creator/scripts/generate_openai_yaml.py \
  ~/.codex/skills/my-skill \
  --interface display_name="My Skill" \
  --interface short_description="Help with my skill tasks"

---

8. 中级技巧：渐进式披露设计

这是写出高效 Skill 的核心设计模式。

模式一：高层指南 + 引用文件

# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features
- **Form filling**: See references/forms.md for complete guide
- **API reference**: See references/api_docs.md for all methods
- **Examples**: See references/examples.md for common patterns

Codex 只在用户需要表单填写时才加载 forms.md。

模式二：按领域拆分

bigquery-skill/
├── SKILL.md               ← 概览和导航
└── references/
    ├── finance.md          ← 收入、计费指标
    ├── sales.md            ← 机会、管道
    ├── product.md          ← API 使用、功能
    └── marketing.md        ← 活动、归因

用户问销售指标时，只加载 sales.md。

模式三：按框架/变体拆分

cloud-deploy/
├── SKILL.md               ← 工作流 + 选择指南
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

用户选 AWS，只加载 aws.md。

模式四：条件详情

# DOCX Processing

## Creating documents
Use docx-js for new documents. See references/docx-js.md.

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See references/redlining.md
**For OOXML details**: See references/ooxml.md

关键原则

• 引用文件从 SKILL.md 出发只跳一层，不要深层嵌套
• 超过 100 行的引用文件，顶部加目录（Table of Contents）
• SKILL.md 不超过 500 行，超过就拆

---

9. 中级技巧：自由度控制

根据任务的脆弱性和可变性，匹配不同的自由度：

高自由度（文本指令）

适用场景： 多种方法都可行，决策依赖上下文，启发式引导即可。

## Code Review Guidelines
Focus on security, performance, and maintainability.
Use your judgment for severity levels.
Suggest improvements when patterns are suboptimal.

中自由度（伪代码/带参数脚本）

适用场景： 有推荐模式，允许一定变体，配置影响行为。

## Data Pipeline
1. Read source data with `scripts/ingest.py --source <url> --format <fmt>`
2. Validate schema against `references/schema.md`
3. Transform using the patterns in `references/transform_guide.md`
4. Load to target with `scripts/load.py --target <table> --mode <append|overwrite>`

低自由度（特定脚本，少量参数）

适用场景： 操作脆弱易错，一致性关键，必须按特定顺序执行。

## PDF Rotation (MUST follow this exact sequence)
1. Run: `python3 scripts/rotate_pdf.py <input> <degrees> <output>`
2. Render output: `pdftoppm -png <output> <prefix>`
3. Visually inspect ALL pages for alignment issues
4. If any page has issues, re-run from step 1 with corrected input

类比： 窄桥+悬崖需要明确护栏（低自由度），开阔草地可以自由探索（高自由度）。

---

10. 进阶：Forward-Testing

Forward-testing 是验证 Skill 是否真正有效的关键手段。

什么是 Forward-Testing

让子代理（subagent）假装是普通用户，用你的 Skill 完成真实任务，从而测试：

• Skill 能否被正确触发
• 指令是否足够清晰
• 输出是否符合预期

怎么做

正确方式：

Use $skill-name at /path/to/skill-name to solve problem y

错误方式：

Review the skill at /path/to/skill-name; pretend a user asks you to...

Forward-Testing 原则

1. 用新线程，保持独立
2. 只传 Skill 路径和任务描述，不要泄露你的诊断或预期答案
3. 每次迭代后清理子代理产生的文件，避免污染
4. 只在子代理泄露上下文才能成功时才信任结果 — 如果结果依赖泄露的上下文，说明 Skill 还需要改进
5. 如果测试可能涉及生产系统或需要额外审批，先向用户确认

决策规则

• 倾向于做 forward-testing
• 如果以下任一条件成立，先问用户：
  • 测试耗时较长
  • 需要额外用户审批
  • 可能修改线上生产系统

---

11. 进阶：Production 级 Skill 设计模式

模式一：带有质量检查的工作流

---
name: chart-generator
description: "Generate publication-quality charts. Use when user asks to create any data visualization, chart, or graph from data."
---

# Chart Generator

## Workflow

1. Determine chart type from user request (bar, line, scatter, heatmap, etc.)
2. Generate chart with matplotlib/plotly using `scripts/generate_chart.py`
3. Render to PNG and visually verify
4. If verification fails, fix and re-render
5. Deliver final PNG

## Quality Checks (Mandatory)

After EVERY chart generation:
- Verify no overlapping labels
- Confirm axis labels are readable at target size
- Check color contrast meets WCAG AA
- Ensure title and legend are visible

## Scripts

- `scripts/generate_chart.py --type <chart_type> --data <csv> --output <png>`
- `scripts/verify_chart.py <png_path>` — Automated quality check

模式二：环境感知 Skill

---
name: deploy-helper
description: "Deploy applications to cloud providers. Use when user asks to deploy, ship, or release an application. Supports AWS, GCP, Azure."
---

# Deploy Helper

## Pre-flight Checks

Before any deployment:
1. Verify target environment credentials exist
2. Check that build artifacts are up to date
3. Confirm deployment target matches user's intent (staging vs production)

## Provider Selection

| Provider | Config File | Credentials |
|----------|------------|-------------|
| AWS      | aws-config.yaml | AWS_PROFILE env |
| GCP      | gcp-config.yaml | GOOGLE_APPLICATION_CREDENTIALS |
| Azure    | azure-config.yaml | AZURE credentials |

Load provider-specific details from `references/<provider>.md`.

## Safety Rules

- NEVER deploy to production without explicit user confirmation
- ALWAYS preview changes before executing
- If deployment fails, rollback and explain what went wrong

模式三：带上下文积累的长流程

---
name: code-migration
description: "Migrate codebases between frameworks or languages. Use when user asks to migrate, convert, or transform an existing codebase."
---

# Code Migration Skill

## Phase 1: Analysis
Scan the source codebase and produce `migration-report.md`:
- File count and structure
- Dependencies inventory
- Complexity estimate

## Phase 2: Planning
Based on the report, create a migration plan in `migration-plan.md`:
- Ordered list of files to convert
- Dependency graph
- Risk assessment per file

## Phase 3: Execution
Convert files following the plan. After each batch:
- Run available tests
- Update migration-plan.md with progress
- If error rate > 10%, pause and reassess

## Phase 4: Verification
- Run full test suite
- Compare coverage metrics before/after
- Generate final migration summary

---

12. 完整实战案例

案例：Notion 知识管理 Skill

notion-knowledge-capture/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── page_types.md        ← 各种页面类型的 Schema
│   └── linking_rules.md     ← 链接和关联规则
└── assets/
    └── templates/
        ├── decision.md      ← 决策记录模板
        └── faq.md           ← FAQ 模板

SKILL.md:

---
name: notion-knowledge-capture
description: "Capture conversations and decisions into structured Notion pages. Use when turning chats/notes into wiki entries, how-tos, decisions, or FAQs with proper linking."
---

# Notion Knowledge Capture

## When to Capture

Capture knowledge when the conversation contains:
- A decision that should be持久化
- A how-to that will be repeated
- An FAQ that multiple people ask
- A meeting outcome that affects others

## Workflow

1. Identify the type of knowledge (decision / how-to / FAQ / meeting-notes)
2. Load the appropriate template from `assets/templates/`
3. Fill in the template with conversation content
4. Determine where it belongs in the Notion hierarchy (see `references/linking_rules.md`)
5. Create the page via Notion MCP

## Quality Standards

- Title must be specific and searchable (not "Meeting Notes" but "Q3 Planning: API Rate Limiting Decision")
- Every entry must have: author, date, status, related pages
- Decisions must include: context, options considered, rationale, follow-ups

---

13. 调试与排错

Skill 没有被触发

检查清单：

1. description 是否清晰描述了使用场景？
2. 用户的请求是否匹配 description 中提到的场景？
3. 是否有其他 Skill 的 description 更匹配？
4. Skill 文件夹是否放在 $CODEX_HOME/skills/ 下？

Skill 触发了但行为不对

1. SKILL.md 正文是否在 frontmatter 之后？
2. 指令是否足够具体？（用祈使句，给出明确步骤）
3. 引用的脚本/文件路径是否正确？

验证命令

# 检查结构是否正确
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/my-skill

# 检查 YAML 格式
cat ~/.codex/skills/my-skill/agents/openai.yaml

# 列出所有已安装的 Skill
ls ~/.codex/skills/

---

14. 最佳实践速查表

Description 写法

原则	说明
写清楚做什么 + 什么时候用	两者缺一不可
包含所有触发场景	触发信息只能放 description，不能放 body
不超过 1024 字符	避免 <> 符号
包含文件类型/任务类型	帮助 Codex 精确匹配

SKILL.md 写法

原则	说明
用祈使句	“Run the script” 而不是 “The script can be run”
只写 Codex 不知道的	不解释基础概念
不超过 500 行	超过就拆到 references/
引用文件只跳一层	不要深层嵌套引用
大文件加 grep 指引	方便 Codex 搜索定位

资源管理

原则	说明
脚本优先	确定性任务用脚本，不重写代码
references 只放按需内容	不要污染主文件
assets 只放输出资源	不读进上下文的文件
不放 README/CHANGELOG	Skill 是给 AI 看的

Production 级要求

原则	说明
质量检查内嵌到流程	每个关键步骤后验证
错误恢复明确写出来	失败时该怎么做
Forward-test 复杂 Skill	用子代理模拟真实使用
多环境感知	明确区分 staging/production
安全操作确认	破坏性操作前确认

---

附录：关键路径

路径	用途
~/.codex/skills/	个人 Skill 安装目录
~/.codex/skills/.system/skill-creator/	Skill 创建工具
scripts/init_skill.py	初始化新 Skill
scripts/quick_validate.py	验证 Skill 结构
scripts/generate_openai_yaml.py	生成 UI 元数据
$CODEX_HOME/skills/.system/	系统预装 Skill（不可修改）

---

本教程基于 Codex Skill Creator 系统文档编写，覆盖从零基础到生产级的完整路径。