Keep the minimum structure stable
Use a stable lowercase, hyphenated directory name and put SKILL.md at its root. Move long background material into references.
- skill-name/SKILL.md
- Optional agents/openai.yaml
- Optional references/*.md
- Optional scripts/ and assets/
The description controls discovery
Frontmatter should say what the skill does and when the user needs it. Broad descriptions over-trigger; noun lists are hard to discover.
- Use verbs for the capability
- Name typical tasks or inputs
- State important boundaries
- Differentiate neighboring skills
Write the body for execution
Prioritize prerequisites, ordered steps, output format, and validation. Keep only the theory that changes execution in the main file.
- Start with use cases
- Provide executable steps
- Include failure branches and checks
- Give a minimal example
- Keep the main file compact
Common questions
Is a longer SKILL.md better?
No. It should guide execution without loading every reference into context.
Can the skill body use another language?
Yes. A stable English slug is still helpful for scripts and cross-platform use.
Ready to turn a PDF into Codex Skills?
Start with a file you know well, inspect the result, and decide whether it belongs in your workflow.
Upload a PDF