skill-creator

用途

Skill Creator 是一个指导性技能，用于帮助用户创建有效的新技能，或更新现有技能，从而扩展 Codex 的能力。技能是模块化、自包含的包，通过提供专门知识、工作流和工具来扩展 Codex 的能力，可将其视为特定领域或任务的“入门指南”，把 Codex 从通用智能体转变为配备程序性知识的专用智能体。

技能提供的内容

专门工作流：针对特定领域的多步骤流程
工具集成：处理特定文件格式或 API 的说明
领域专业知识：公司特定知识、模式、业务逻辑
捆绑资源：用于复杂和重复任务的脚本、参考资料和资产

核心原则

简洁是关键：上下文窗口是公共资源，技能与其他内容共享上下文窗口。默认假设 Codex 已经非常智能，只添加 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（必需）：包含 YAML frontmatter（name 和 description 字段，这是 Codex 判断技能何时被使用的唯一字段）和 Markdown 正文（仅在技能触发后加载）。

Scripts（scripts/）：可执行代码，用于需要确定性可靠性或反复重写的任务。优点是令牌高效、确定性、可能无需加载到上下文即可执行。

References（references/）：按需加载到上下文中的文档和参考资料，如数据库模式、API 文档、领域知识、公司政策等。保持 SKILL.md 精简，仅在需要时加载。

Assets（assets/）：不加载到上下文，而是在 Codex 输出中使用的文件，如模板、图像、图标、样板代码、字体等。

不应包含的内容

技能应只包含直接支持其功能的基本文件。不要创建无关文档或辅助文件，包括 README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md 等。

渐进式披露设计原则

技能使用三级加载系统管理上下文：元数据（名称+描述，始终在上下文中，约100词）、SKILL.md 正文（技能触发时加载，少于5000词）、捆绑资源（按需加载，无限制）。

SKILL.md 正文应保持在500行以内，接近此限制时拆分内容到单独文件，并从 SKILL.md 引用它们。

模式1：带参考的高级指南——在 SKILL.md 中保留核心工作流，将变体细节移到单独参考文件。

模式2：领域特定组织——按领域组织内容，避免加载无关上下文。

模式3：条件细节——显示基本内容，链接到高级内容。

重要指南：避免深层嵌套引用，保持引用距 SKILL.md 一层深度；对于超过100行的参考文件，在顶部包含目录。

技能创建流程

理解技能：通过具体示例明确技能将如何使用，可通过用户示例或生成示例并验证。
规划可复用内容：分析每个示例，确定哪些脚本、参考资料和资产会有帮助。
初始化技能：运行 scripts/init_skill.py <skill-name> --path <output-directory> 生成模板目录。
编辑技能：实现资源并编写 SKILL.md。脚本必须实际运行测试。
打包技能：运行 scripts/package_skill.py <path/to/skill-folder> 打包为可分发的 .skill 文件，自动验证技能。
基于实际使用迭代。

编写指南

始终使用祈使/不定式形式。Frontmatter 中只包含 name 和 description 字段，description 是主要的触发机制，应包含技能做什么以及何时使用的具体触发条件。不要在正文中放置“何时使用”信息，因为正文仅在触发后加载。

适用场景

适用于用户希望创建新技能或更新现有技能以扩展 Codex 能力时。

限制

资料中未提供关于收费、价格、平台支持范围等具体信息。