OpenAI Skills
OpenAI Skills 架构：指令、元数据、辅助脚本与宿主边界
通过 gh-fix-ci 理解技能的组成，区分展示配置、最小结构校验、确定性诊断以及仓库之外的宿主职责。
你将学会
- 目录是组合单位
- 校验存在不同深度
- 让控制流程与证据流各自清楚
开始前需要
- 基础 Git、Python 与命令行知识
- 明确的仓库检查与修改权限边界
解释本章源码行为，应用验收清单，并区分目录与宿主。
先看结论
- 区分人类可读工作流、宿主元数据与可执行脚本。
- 文件存在、最小结构校验和行为验收是不同关卡。
- 不要把宿主内部实现归因于技能目录仓库。
目录是组合单位
仓库把目录作为可携带单元：SKILL.md 存放工作流和元数据，references 提供补充材料，assets 保存可复用资源，scripts 执行可重复操作。所选 gh-fix-ci 还提供 agents/openai.yaml，包含展示名、短描述、图标和默认提示。这些文件面向不同消费者，不应全部塞成一份巨大指令。
固定版本的 openai_yaml 参考文档将 agents/openai.yaml 定义为产品相关的宿主配置。在里面声明工具依赖，不证明凭据已经存在，也不意味着连接器已获得授权。反过来，即使展示配置只有界面字段，脚本仍可能依赖 gh 这样的本地命令，因此应同时从说明和代码盘点依赖。
校验存在不同深度
安装器的 _validate_skill 只确认目录与 SKILL.md 存在。另一个 creator 脚本 quick_validate.py 会解析 frontmatter，检查少量允许键，并限制名称和描述格式。这些检查都不能证明引用脚本一定存在、命令一定适合执行，或者工作流会在正确请求上触发。
一个细节能说明“校验通过”与“内容有用”的差别：最小校验器要求名称和描述键存在且为字符串，但后续内容检查只在去空白后非空时执行。因此空字符串会跳过那些检查。我们的注入解析器探针复现了该分支，没有运行 PyYAML，也不代表宿主自身的校验逻辑相同。
让控制流程与证据流各自清楚
在 CI 示例中，宿主遵循指令，子进程调用 gh，JSON 字段用于分类检查，日志文本被整理成诊断片段。脚本可以报告外部链接、未就绪或不可获取的日志，而不是编造成功。输出应是供宿主推理的证据，不应因为来自 CI 日志，就变成获得新权限的指令。
这个仓库不包含宿主技能选择引擎的完整实现。因此，目录、宿主与工具调用图只是架构解释，并非承诺所有 Codex 版本内部调用路径完全一致。应在目标宿主测试发现、选择和权限，再独立测试辅助函数的确定性分支。
实施步骤
- 1
标明每个文件由谁消费。
- 2
识别本地命令与远端依赖。
- 3
检查校验深度和缺少的行为测试。
- 4
分别验证宿主选择与辅助函数正确性。
可复制示例
{"layers":["SKILL.md","agents/openai.yaml","scripts","host tools"],"fileExistsMeansWorkflowSafe":false,"metadataMeansCredentialsGranted":false,"hostInternalsInspected":false}常见问题
quick_validate.py 能证明技能好用吗？
不能。它只是最小 frontmatter 校验，行为质量、工具可用性与授权需要另外检查。
agents/openai.yaml 是另一份提示词吗？
所查参考文档将其定义为产品相关的宿主配置，应将界面、依赖字段与工作流正文分别审查。
资料来源
- README.md来源核查 2026-09-08
- skills/.system/skill-installer/SKILL.md来源核查 2026-09-08
- skills/.system/skill-installer/LICENSE.txt来源核查 2026-09-08
- skills/.system/skill-installer/scripts/install-skill-from-github.py来源核查 2026-09-08
- skills/.system/skill-installer/scripts/github_utils.py来源核查 2026-09-08
- skills/.system/skill-installer/scripts/list-skills.py来源核查 2026-09-08
- skills/.system/skill-creator/scripts/quick_validate.py来源核查 2026-09-08
- skills/.system/skill-creator/references/openai_yaml.md来源核查 2026-09-08
- skills/.curated/gh-fix-ci/SKILL.md来源核查 2026-09-08
- skills/.curated/gh-fix-ci/scripts/inspect_pr_checks.py来源核查 2026-09-08
- skills/.curated/gh-fix-ci/agents/openai.yaml来源核查 2026-09-08
- skills/.system/plugin-creator/SKILL.md来源核查 2026-09-08
- 当前官方技能指南来源核查 2026-09-08