When to create a skill
Create a skill when the work has a stable procedure: convert a document format, audit a design, build a recurring report, run a domain-specific diagnostic, or generate an artifact with strict structure.
Do not create a skill for every preference. If a rule only applies to one repository, AGENTS.md is usually a better fit. If a task is one-time, the prompt is enough.
- Use skills for process, not just style.
- Include references only when they directly affect execution.
- Prefer scripts for repetitive mechanical steps.
What makes a skill reliable
A reliable skill tells Codex when it applies, what files to read, what commands to run, what output format to produce, and what must be verified before completion.
The instruction should be specific but not overfit to one example. Good skills describe decision rules so Codex can adapt the workflow to the current project.
Keep skills maintainable
Skills become technical assets. They need names, scope, version awareness, and a clear owner. When a workflow changes, update the skill instead of teaching every future prompt the new rule.
If a skill depends on external tools, document the tool requirement and failure behavior. A skill that silently assumes unavailable dependencies will create confusing results.