skill-creator

技能创建器

此技能提供创建高效技能的指导。

关于技能

技能是模块化、独立的软件包，可通过提供专业知识、工作流和工具来扩展 Codex 的能力。可以将它们视为针对特定领域或任务的“入门指南”——它们能将 Codex 从通用 Agent 转变为具备程序性知识的专业 Agent，而这些知识是任何模型都无法完全掌握的。

技能提供的内容

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——用于处理特定文件格式或 API 的说明
3. 领域专业知识——特定于公司的知识、架构和业务逻辑
4. 捆绑资源——用于复杂且重复任务的脚本、参考资料和素材

核心原则

简洁至关重要

上下文窗口是一种公共资源。技能与 Codex 所需的所有其他内容共享上下文窗口：系统提示词、对话历史、其他技能的元数据，以及用户的实际请求。

默认假设：Codex 已经非常聪明。 只添加 Codex 尚不了解的上下文。审视每条信息：“Codex 真的需要这段解释吗？”以及“这段话值得占用相应的 token 吗？”

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

设定适当的自由度

根据任务的脆弱性和可变性，匹配具体程度：

高自由度（基于文本的说明）：适用于存在多种有效方法、决策取决于上下文，或需要依靠启发式方法指导的情况。

中自由度（带参数的伪代码或脚本）：适用于存在首选模式、允许一定变化，或配置会影响行为的情况。

低自由度（参数较少的具体脚本）：适用于操作脆弱且容易出错、一致性至关重要，或必须遵循特定顺序的情况。

可以把 Codex 想象成在探索一条路径：悬崖边的狭窄桥梁需要明确的护栏（低自由度），而开阔的田野则允许多种路线（高自由度）。

技能的组成

每项技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── 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 用来判断何时使用该技能的唯一字段，因此清晰、全面地描述技能的内容及其适用场景非常重要。
• 正文（Markdown）：使用该技能的说明和指导。仅在技能触发后（如果触发）加载。

捆绑资源（可选）

脚本（scripts/）

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

• 适用情况：反复重写相同代码，或需要确定性结果时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省 token、结果确定，可在不加载到上下文中的情况下执行
• 注意：Codex 可能仍需读取脚本，以进行修补或适配特定环境

参考资料（references/）

文档和参考资料，可按需加载到上下文中，为 Codex 的流程和思考提供依据。

• 适用场景：Codex 工作时需要参考的文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 用途：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优势：保持 SKILL.md 精简，仅在 Codex 判断需要时加载
• 最佳实践：如果文件较大（超过 10k 个单词），在 SKILL.md 中添加 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考资料文件中，不要两边都放。除非信息确实是技能的核心内容，否则详细信息优先放在参考资料文件中；这样既能保持 SKILL.md 精简，又能让信息易于查找，而不会占用过多上下文窗口。SKILL.md 中只保留必要的流程指令和工作流指南；详细的参考资料、架构和示例则移至参考资料文件中。

资源文件（assets/）

不打算加载到上下文中，而是供 Codex 在生成输出时使用的文件。

• 适用场景：技能需要在最终输出中使用文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、字体排版文件 assets/font.ttf
• 用途：模板、图像、图标、样板代码、字体、会被复制或修改的示例文档
• 优势：将输出资源与文档分开，让 Codex 无需将文件加载到上下文中即可使用

技能中不应包含的内容

技能只应包含直接支持其功能的必要文件。不要创建多余的文档或辅助文件，包括：

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

技能只应包含 AI Agent 完成当前任务所需的信息。不要包含有关创建过程的辅助背景、设置和测试流程、面向用户的文档等。创建额外的文档文件只会增加杂乱和困惑。

渐进式披露设计原则

技能使用三级加载系统，高效管理上下文：

1. 元数据（名称 + 描述） - 始终位于上下文中（约 100 个单词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个单词）
3. 捆绑资源 - Codex 按需加载（数量不限，因为脚本可以执行而无需读入上下文窗口）

渐进式披露模式

将 SKILL.md 正文精简至必要内容，并控制在 500 行以内，以尽量减少上下文膨胀。接近此限制时，将内容拆分到单独的文件中。将内容拆分到其他文件时，务必在 SKILL.md 中引用这些文件，并清楚说明何时阅读，确保使用该技能的读者知道这些文件的存在及其适用场景。

核心原则： 当技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指南。将特定变体的详细信息（模式、示例、配置）移到单独的参考文件中。

模式 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

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

模式 2：按领域组织

对于包含多个领域的技能，按领域组织内容，以避免加载无关上下文：

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。

同样，对于支持多个框架或变体的技能，也应按变体组织：

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

当用户选择 AWS 时，Codex 只会读取 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)

只有当用户需要相关功能时，Codex 才会读取 REDLINING.md 或 OOXML.md。

重要指南：

• 避免过深的嵌套引用——将引用控制在距 SKILL.md 一层的范围内。所有参考文件都应由 SKILL.md 直接链接。
• 为较长的参考文件添加结构——对于超过 100 行的文件，请在顶部添加目录，以便 Codex 在预览时了解其完整范围。

技能创建流程

创建技能包括以下步骤：

1. 通过具体示例了解技能
2. 规划可复用的技能内容（脚本、参考文件、资源）
3. 初始化技能（运行 init_skill.py）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 package_skill.py）
6. 根据实际使用情况迭代

请按顺序执行这些步骤，只有在有明确理由说明某步骤不适用时才跳过。

技能命名

• 只能使用小写字母、数字和连字符；将用户提供的标题规范化为连字符格式（例如，“Plan Mode” -> plan-mode）。
• 生成名称时，长度应少于 64 个字符（字母、数字、连字符）。
• 优先使用简短、以动词开头且能描述操作的短语。
• 在有助于提升清晰度或触发效果时，按工具添加命名空间（例如，gh-address-comments、linear-address-issue）。
• 技能文件夹名称必须与技能名称完全一致。

步骤 1：通过具体示例了解技能

只有在已清楚了解技能的使用模式时，才跳过此步骤。即使是在处理现有技能时，此步骤仍然很有价值。

要创建有效的技能，必须清楚了解技能的具体使用方式。可以通过用户直接提供的示例了解，也可以生成示例并通过用户反馈加以验证。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应支持哪些功能？编辑、旋转，还是其他操作？”
• “你能举几个使用此技能的例子吗？”
• “我能想到用户可能会提出‘去除这张图片中的红眼’或‘旋转这张图片’之类的请求。你觉得还有哪些其他使用方式？”
• “用户说什么时应该触发此技能？”

为避免让用户应接不暇，不要在一条消息中提出太多问题。先问最重要的问题，再根据需要继续提问，以提高效果。

当明确了技能应支持的功能后，即可结束此步骤。

步骤 2：规划可复用的 Skill 内容

要将具体示例转化为有效的 Skill，请通过以下方式分析每个示例：

1. 考虑如何从头开始执行该示例
2. 确定在反复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

示例：创建 pdf-editor Skill 来处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存入 Skill 会很有帮助

示例：设计 frontend-webapp-builder Skill 来处理“帮我构建一个待办应用”或“帮我构建一个用于追踪步数的仪表盘”之类的请求时，分析表明：

1. 每次编写前端 Web 应用都需要相同的 HTML/React 样板代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存入 Skill 会很有帮助

示例：创建 big-query Skill 来处理“今天有多少用户登录？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新了解表架构及其关系
2. 将记录表架构的 references/schema.md 文件存入 Skill 会很有帮助

要确定 Skill 的内容，请分析每个具体示例，并列出要包含的可复用资源：脚本、参考资料和资源文件。

步骤 3：初始化 Skill

此时，就该实际创建 Skill 了。

只有在正在开发的 Skill 已经存在，且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

从头开始创建新 Skill 时，务必运行 init_skill.py 脚本。该脚本会便捷地生成新的 Skill 模板目录，并自动包含 Skill 所需的所有内容，从而让 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 模板
• 根据 --resources 选项（可选）创建资源目录
• 在设置 --examples 时（可选）添加示例文件

初始化后，自定义 SKILL.md 并根据需要添加资源。如果使用了 --examples，请替换或删除占位文件。

步骤 4：编辑 Skill

编辑（新生成或已有的）Skill 时，请记住，创建 Skill 是为了供 Codex 的另一个实例使用。请加入对 Codex 有益且不易察觉的信息。考虑哪些流程知识、特定领域细节或可复用资源能帮助另一个 Codex 实例更有效地执行这些任务。

学习经过验证的设计模式

根据 Skill 的需求，查阅以下实用指南：

• 多步骤流程：参阅 references/workflows.md，了解顺序工作流和条件逻辑
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式

这些文件包含设计有效 Skill 的成熟最佳实践。

从可复用的 Skill 内容着手

开始实现时，先着手处理上面确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实现 brand-guidelines Skill 时，用户可能需要提供品牌资源或模板，以便存入 assets/，或者提供文档以便存入 references/。

必须通过实际运行新增脚本来测试，确保没有错误，且输出符合预期。如果有许多相似脚本，只需测试具有代表性的脚本样例，以在确保可靠性的同时兼顾完成时间。

如果使用了 --examples，请删除 Skill 不需要的占位文件。只创建确实需要的资源目录。

更新 SKILL.md

写作指南： 始终使用祈使式／不定式形式。

Frontmatter

使用 name 和 description 编写 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，可帮助 Codex 理解何时使用该技能。
  • 同时说明 Skill 的功能，以及使用它的具体触发条件／情境。
  • 将所有“何时使用”信息都写在这里，不要放在正文中。正文只会在触发后加载，因此在正文中添加“何时使用此技能”部分对 Codex 没有帮助。
  • docx 技能的描述示例：“全面的文档创建、编辑和分析，支持修订、批注、格式保留和文本提取。当 Codex 需要处理专业文档（.docx 文件）时使用，具体包括：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订，(4) 添加批注，或任何其他文档任务”

不要在 YAML frontmatter 中包含任何其他字段。

正文

编写使用此技能及其捆绑资源的说明。

步骤 5：打包技能

技能开发完成后，必须将其打包成可分发的 .skill 文件并分享给用户。打包过程会先自动验证技能，确保其符合所有要求：

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

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

1. 自动验证技能，检查以下内容：

   • YAML frontmatter 格式和必需字段
   • 技能命名约定和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 打包通过验证的技能，创建一个以技能命名的 .skill 文件（例如 my-skill.skill），其中包含所有文件，并保留适用于分发的目录结构。.skill 文件是扩展名为 .skill 的 zip 文件。

如果验证失败，脚本将报告错误并退出，不会创建软件包。修复所有验证错误，然后重新运行打包命令。

步骤 6：迭代

测试技能后，用户可能会要求改进。通常，这种情况会在使用技能后立即发生，此时用户对技能的表现仍有新鲜的印象。

迭代工作流：

1. 在实际任务中使用技能
2. 留意遇到的困难或低效之处
3. 确定应如何更新 SKILL.md 或捆绑资源
4. 实施更改并再次测试