最小目录结构
每个 Skill 使用稳定的英文小写连字符目录名，根目录包含 SKILL.md；较长的背景材料可放在 references 子目录。
- skill-name/SKILL.md
- 可选 agents/openai.yaml
- 可选 references/*.md
- 可选 scripts/ 与 assets/
描述决定何时触发
frontmatter description 应同时说明这个 Skill 做什么、用户在什么场景下需要它。过于宽泛的描述会造成误触发，只有名词堆叠则很难被发现。
- 使用动词描述能力
- 写出典型输入或任务
- 说明重要边界
- 避免与相邻 Skill 使用完全相同的触发词
正文应该面向执行
正文优先写前置条件、顺序步骤、输出格式和验证方法。背景理论只保留执行所必需的部分，其余放到引用文件。
- 先给适用场景
- 再给可执行步骤
- 明确失败分支和检查项
- 提供最小示例
- 保持主文件紧凑
常见问题
SKILL.md 越长越好吗？
不是。主文件应足够指导执行，但不应把所有参考资料一次性塞入上下文。
可以使用中文 Skill 吗？
正文可以使用中文；目录名建议使用稳定的英文 slug，便于跨平台和脚本处理。
准备把 PDF 变成 Codex Skills？
先用一个你熟悉的文件验证结果，再决定是否纳入长期工作流。
上传 PDF 开始转换