OpenAI Skills
Inside OpenAI Skills: instructions, metadata, helpers and the host boundary
Follow the layers of a skill through the gh-fix-ci example, including metadata, schema checks, deterministic diagnostics and responsibilities that remain outside the repository.
What you will learn
- A folder is the unit of composition
- Validation has several depths
- Keep control flow and evidence flow visible
Before you start
- Basic Git, Python and command-line concepts
- An explicit boundary for permitted repository inspection and changes
Explain the chapter’s source behavior and apply its acceptance checklist without confusing a catalog with its host.
Key takeaways
- Separate human workflow, harness metadata and executable helpers.
- File existence, minimal schema checks and behavioral acceptance are different gates.
- Do not attribute host internals to a catalog repository.
A folder is the unit of composition
The repository uses a directory as the portable unit: SKILL.md carries workflow instructions and metadata, references hold supporting material, assets carry reusable resources, and scripts implement repeatable operations. The selected gh-fix-ci folder adds agents/openai.yaml with a human-readable name, short description, icons and a default prompt. These files have different consumers and should not be flattened into one enormous instruction document.
The pinned openai_yaml reference describes agents/openai.yaml as product-specific harness configuration. Declaring a tool dependency there is not evidence that credentials exist or that a connector is authorized. Conversely, a helper can depend on a local command such as gh even when the presentation file contains only interface fields. Inventory dependencies from both instructions and executable code.
Validation has several depths
The installer’s _validate_skill only checks for a directory and a SKILL.md file. The separate creator quick_validate.py parses frontmatter, checks a small allowed-key set and applies name and description constraints. Neither check proves that a referenced script exists, that its commands are safe, or that the workflow will activate for the right request.
One subtle branch illustrates the difference between a validation success and editorial usefulness. The minimal validator requires name and description keys with string values, but its content checks are conditional on those trimmed strings being nonempty. Empty strings therefore bypass those later checks. Our injected-parser probe exercised this branch; it did not run PyYAML or certify compatibility with a host’s own validator.
Keep control flow and evidence flow visible
In the CI example, the host follows the instructions, a subprocess invokes gh, JSON fields classify checks, and log text becomes a short diagnostic artifact. The helper can report an external link, pending logs or unavailable logs rather than fabricating a success. Its output must remain evidence for the host’s reasoning, not an instruction source that gains authority because it came from a CI log.
This repository does not contain the complete implementation of the host’s skill-selection engine. Consequently, a diagram of catalog, host and tool calls is an architectural explanation, not a claim that every Codex build follows an identical internal call path. Test discovery, selection and permissions in the host you intend to use, while testing deterministic helper branches independently.
Implementation steps
- 1
Map each selected file to its consumer.
- 2
Identify every local command and remote dependency.
- 3
Inspect validation depth and missing behavioral checks.
- 4
Test host selection separately from helper correctness.
Copy-ready example
{"layers":["SKILL.md","agents/openai.yaml","scripts","host tools"],"fileExistsMeansWorkflowSafe":false,"metadataMeansCredentialsGranted":false,"hostInternalsInspected":false}Frequently asked questions
Does quick_validate.py prove the skill works?
No. It is a minimal frontmatter check. Behavioral quality, tool availability and authorization require separate tests.
Is agents/openai.yaml another prompt file?
The inspected reference describes it as product-specific harness configuration. Its interface and dependency fields should be reviewed separately from workflow prose.
Sources
- README.mdSource checked 2026-09-08
- skills/.system/skill-installer/SKILL.mdSource checked 2026-09-08
- skills/.system/skill-installer/LICENSE.txtSource checked 2026-09-08
- skills/.system/skill-installer/scripts/install-skill-from-github.pySource checked 2026-09-08
- skills/.system/skill-installer/scripts/github_utils.pySource checked 2026-09-08
- skills/.system/skill-installer/scripts/list-skills.pySource checked 2026-09-08
- skills/.system/skill-creator/scripts/quick_validate.pySource checked 2026-09-08
- skills/.system/skill-creator/references/openai_yaml.mdSource checked 2026-09-08
- skills/.curated/gh-fix-ci/SKILL.mdSource checked 2026-09-08
- skills/.curated/gh-fix-ci/scripts/inspect_pr_checks.pySource checked 2026-09-08
- skills/.curated/gh-fix-ci/agents/openai.yamlSource checked 2026-09-08
- skills/.system/plugin-creator/SKILL.mdSource checked 2026-09-08
- Current official skills guideSource checked 2026-09-08