---

name: skill-creator
description: 创建高质量技能的指南。当用户希望创建新技能（或更新现有技能），以通过专业知识、工作流或工具集成扩展 Codex 能力时，应使用此技能。
metadata:
short-description: 创建或更新技能

---

Skill Creator

本技能提供创建高质量技能（Skill）的指导。

关于 Skill

Skill 是模块化、可自包含的文件夹，通过提供专业知识、工作流和工具来扩展 Codex 能力。你可以把它理解为针对特定领域或任务的“上手指南”——它把 Codex 从通用代理转变为具备流程性知识的专业代理，而这类流程知识通常无法仅靠模型本身完整掌握。

Skill 能提供什么

1. 专业化工作流：面向特定领域的多步骤流程
2. 工具集成：针对特定文件格式或 API 的使用说明
3. 领域知识：公司特定知识、数据结构、业务逻辑
4. 资源打包：用于复杂重复任务的脚本、参考资料与资产文件

核心原则

简洁是关键

上下文窗口是公共资源。Skill 会与 Codex 需要的其他内容共享上下文窗口：系统提示词、对话历史、其他 Skill 的元数据，以及用户当前请求。

默认假设：Codex 已经很聪明。 仅补充 Codex 不具备的上下文。对每条信息都要质疑：

• “Codex 真的需要这段解释吗？”
• “这段话值得它消耗的 token 成本吗？”

优先使用简洁示例，而不是冗长解释。

设定合适的自由度

让指令具体程度与任务的脆弱性和变化性匹配：

高自由度（纯文本说明）：适用于可行路径很多、决策依赖上下文、需要启发式判断的情况。

中自由度（伪代码或可参数化脚本）：适用于已有推荐模式、允许部分变化、行为受配置影响的情况。

低自由度（具体脚本、少参数）：适用于操作脆弱且易出错、一致性要求高、必须按固定顺序执行的情况。

把 Codex 理解为在探索路径：两侧是悬崖的窄桥需要严格护栏（低自由度）；开阔平原则允许多条路线（高自由度）。

Skill 的构成

每个 Skill 由必需的 SKILL.md 和可选的打包资源组成：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
├── agents/ (recommended)
│   └── openai.yaml - UI metadata for skill lists and chips
└── Bundled Resources (optional)
    ├── scripts/     - Executable code (Python/Bash/etc.)
    ├── references/  - Documentation intended to be loaded into context as needed
    └── assets/      - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

每个 SKILL.md 由以下部分组成：

• Frontmatter（YAML）：包含 name 与 description。这是 Codex 判断“何时触发此 Skill”的唯一字段，因此必须清晰且完整地描述 Skill 做什么、何时使用。
• 正文（Markdown）：Skill 的使用说明与指导。只有在 Skill 被触发后才会加载（并且也可能不加载）。

Agents 元数据（推荐）

• 面向 UI 的元数据，用于 Skill 列表和 chips
• 先阅读 references/openai_yaml.md，并按其定义与约束生成字段
• 通过阅读 Skill 内容生成面向人的 display_name、short_description、default_prompt
• 使用 scripts/generate_openai_yaml.py 或 scripts/init_skill.py，通过 --interface key=value 传值，确保可确定性生成
• 更新 Skill 后要校验 agents/openai.yaml 是否仍与 SKILL.md 一致；不一致则重新生成
• 仅当用户明确提供时，才填其他可选界面字段（如图标、品牌色）
• 字段定义与示例见 references/openai_yaml.md

打包资源（可选）

Scripts（scripts/）

用于需要确定性可靠性，或经常重复编写的任务执行代码（Python/Bash 等）。

• 何时加入：当相同代码会反复重写，或需要确定性执行
• 示例：scripts/rotate_pdf.py（PDF 旋转）
• 收益：节省 token、执行确定、可在不加载全文到上下文时执行
• 注意：某些情况下 Codex 仍可能需要读取脚本内容做补丁或环境适配

References（references/）

作为“按需加载”进入上下文的参考材料，用于辅助 Codex 的思考与执行。

• 何时加入：当 Codex 在工作中需要查阅该文档
• 示例：
  • references/finance.md（财务 schema）
  • references/mnda.md（公司 NDA 模板）
  • references/policies.md（公司策略）
  • references/api_docs.md（API 规范）
• 适用场景：数据库结构、API 文档、领域知识、公司政策、详细流程指南
• 收益：保持 SKILL.md 精简，只在确实需要时加载
• 最佳实践：若文件很大（>10k 字），在 SKILL.md 中给出 grep 检索模式
• 避免重复：信息应存在于 SKILL.md 或 references 二者之一，不应重复。详细信息优先放 references；SKILL.md 仅保留核心流程指导，避免占用上下文窗口。

Assets（assets/）

不用于加载进上下文，而是直接用于最终产出的文件资源。

• 何时加入：Skill 需要在产出中使用文件资源
• 示例：
  • assets/logo.png（品牌资源）
  • assets/slides.pptx（PPT 模板）
  • assets/frontend-template/（HTML/React 脚手架）
  • assets/font.ttf（字体）
• 适用场景：模板、图片、图标、样板代码、字体、样例文档（复制/修改后输出）
• 收益：把“输出资源”和“说明文档”分离，Codex 无需加载内容即可使用文件

Skill 中不应包含什么

Skill 只应包含直接支持能力的必要文件。不要创建额外说明文档或辅助文件，例如：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等

Skill 应仅包含 AI 代理完成任务所需的信息，不应包含创建过程说明、安装测试步骤、面向人的用户手册等无关内容。多余文档会增加混乱与维护成本。

渐进披露（Progressive Disclosure）设计原则

Skill 采用三级加载机制提高上下文效率：

1. 元数据（name + description）：始终在上下文中（约 100 词）
2. SKILL.md 正文：触发 Skill 后加载（建议 <5k 词）
3. 打包资源：按需加载（理论上无限，因为脚本可直接执行而无需读入上下文）

渐进披露模式

将 SKILL.md 保持为核心内容，尽量控制在 500 行以内，避免上下文膨胀。接近上限时拆分到独立文件，并在 SKILL.md 中明确引用这些文件以及“何时读取”。

关键原则： 当 Skill 支持多个变体、框架或选项时，SKILL.md 只保留核心流程与选择规则。将变体细节（模式、示例、配置）放入 references。

模式 1：高层导引 + 引用文件

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

仅在需要时加载 FORMS.md、REFERENCE.md、EXAMPLES.md。

模式 2：按领域组织

对于多领域 Skill，按领域拆分，避免加载无关内容：

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，Codex 只需读取 sales.md。

对于支持多框架或多供应商的 Skill，也应按变体拆分：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，只读取 aws.md。

模式 3：条件化细节

主文档给基础信息，进阶内容通过链接引用：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

只有在需要这些功能时才读取 REDLINING.md 或 OOXML.md。

重要准则：

• 避免深层嵌套引用：引用层级尽量只比 SKILL.md 深一层，所有引用文件都应可从 SKILL.md 直接到达。
• 长文档要结构化：参考文件超过 100 行时，在顶部放目录，便于 Codex 预览范围。

Skill 创建流程

创建 Skill 一般遵循以下步骤：

1. 通过具体示例理解 Skill
2. 规划可复用内容（scripts / references / assets）
3. 初始化 Skill（运行 init_skill.py）
4. 编辑 Skill（实现资源并编写 SKILL.md）
5. 校验 Skill（运行 quick_validate.py）
6. 基于真实使用迭代

应按顺序执行，除非有明确理由跳过某一步。

Skill 命名

• 仅使用小写字母、数字、连字符；将用户标题规范为 kebab-case（例：Plan Mode -> plan-mode）
• 名称长度不超过 64（字母/数字/连字符）
• 优先短且动作导向（动词开头）
• 如能提高清晰度或触发效果，使用工具命名空间（如 gh-address-comments、linear-address-issue）
• Skill 目录名必须与 skill name 完全一致

第 1 步：用具体示例理解 Skill

仅当该 Skill 的使用模式已非常清楚时才可跳过。本步骤在更新现有 Skill 时同样有价值。

要创建有效 Skill，必须清楚其真实使用方式。可通过用户直接提供示例，或由你生成示例并让用户确认。

例如构建 image-editor skill 时，可以问：

• “这个 skill 需要支持哪些功能？编辑、旋转，还有什么？”
• “你可以给我一些实际使用示例吗？”
• “我猜你可能会说‘去掉红眼’或‘旋转图片’，还有其他典型说法吗？”
• “用户会用什么话来触发这个 skill？”

为避免用户负担，不要在一条消息里问太多问题。先问最关键问题，再按需追问。

当你已经清楚该 Skill 应支持哪些能力时，本步骤结束。

第 2 步：规划可复用内容

把具体示例转为可复用 Skill 时，逐条分析：

1. 如果从零实现，这个示例如何完成
2. 为反复执行这些流程，哪些 scripts/references/assets 值得沉淀

示例：构建 pdf-editor（处理“帮我旋转这个 PDF”）时：

1. PDF 旋转每次都要重复写类似代码
2. 应沉淀 scripts/rotate_pdf.py

示例：构建 frontend-webapp-builder（处理“做个待办应用”“做个步数仪表盘”）时：

1. 前端应用每次都需要重复的 HTML/React 样板
2. 应沉淀 assets/hello-world/ 模板目录

示例：构建 big-query（处理“今天有多少用户登录”）时：

1. 查询 BigQuery 往往要反复摸索表结构和关系
2. 应沉淀 references/schema.md 记录 schema

最终应产出一个“可复用资源清单”：scripts、references、assets。

第 3 步：初始化 Skill

到这一步应开始实际创建 Skill。

仅当你在“更新已有 Skill”时可跳过；否则继续下一步。

新建 Skill 时，始终运行 init_skill.py。该脚本会生成标准模板目录，包含 Skill 所需基础结构，可显著提高效率和可靠性。

用法：

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

示例：

scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

脚本会：

• 在指定路径创建 Skill 目录
• 生成带正确 frontmatter 与 TODO 占位的 SKILL.md 模板
• 通过 --interface key=value 生成 agents/openai.yaml（包含代理生成的 display_name、short_description、default_prompt）
• 按 --resources 可选创建资源目录
• 当 --examples 开启时，生成示例文件

初始化后，按需定制 SKILL.md 并补充资源。如果使用了 --examples，请替换或删除占位文件。

先阅读 Skill 内容生成 display_name、short_description、default_prompt，然后通过 --interface key=value 传给 init_skill.py；或后续用以下命令重新生成：

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

只有在用户明确提供时才填写其他可选 interface 字段。字段定义与示例见 references/openai_yaml.md。

第 4 步：编辑 Skill

编辑（新建或现有）Skill 时，请记住：这个 Skill 是给“另一个 Codex 实例”使用的。应加入对 Codex 有帮助且不显而易见的信息，例如流程性知识、领域细节、可复用资源。

先实现可复用资源

实施时先从上一步识别的 scripts/、references/、assets/ 开始。此步骤可能需要用户输入。例如 brand-guidelines skill 可能需要用户提供品牌资产（放到 assets/）或文档（放到 references/）。

新增脚本必须通过实际运行测试，确保无 bug 且输出符合预期。若脚本很多且相似，可测试有代表性的一部分，在可靠性与交付时间之间平衡。

若使用了 --examples，删除不需要的占位文件。只保留真正需要的资源目录。

更新 SKILL.md

写作准则：始终使用祈使/不定式语气。

Frontmatter

在 YAML frontmatter 中写入 name 与 description：

• name：Skill 名称
• description：这是 Skill 的主要触发机制，帮助 Codex 判断何时使用。
  • 必须同时包含“Skill 做什么”与“何时触发（具体上下文）”
  • 所有“何时使用”信息都要写在这里，不要写在正文
  • 因为正文仅在触发后才加载，正文中的 “When to Use This Skill” 对触发无帮助
  • 示例（docx skill 的 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”

不要在 YAML frontmatter 中添加任何其他字段。

正文

正文应聚焦于 Skill 与其打包资源的使用说明。

第 5 步：校验 Skill

完成开发后，先校验 Skill 目录以尽早发现基础问题：

scripts/quick_validate.py <path/to/skill-folder>

校验脚本会检查 YAML frontmatter 格式、必填字段与命名规则。若失败，按提示修复并重新执行。

第 6 步：迭代

Skill 经过实际使用后，用户通常会提出改进要求，尤其是在刚使用完、体验最鲜明的时候。

迭代工作流：

1. 在真实任务中使用 Skill
2. 识别卡点与低效之处
3. 判断应更新 SKILL.md 还是打包资源
4. 实施修改并再次测试