Walkthrough
Create a Codex Skill with $skill-creator
A Codex skill saves instructions, references, and optional scripts for a task you repeat. Codex can match it automatically or you can call it by name.
A focused skill saved in the right scope and tested on one new task.
How it works
- 1Start with a result worth repeating
- 2Choose where the skill belongs
- 3Give the skill one clear job
- 4Test a fresh example
Follow the setup path in Codex
- 1
Start with a result worth repeating
In the ChatGPT desktop app, choose Codex and open a chat where the workflow succeeded. If you are starting fresh, provide one real input and show what a good result must include. Fix a weak workflow before saving it as a skill.
- 2
Choose where the skill belongs
Use `.agents/skills` when the workflow depends on one repository. Use `~/.agents/skills` when it should be available across your projects. Open the repository first if you choose repository scope.
Tip: A repository skill appears only when you work in that repository.
- 3
Give the skill one clear job
Run `$skill-creator`. Choose a short lowercase name such as `source-audit`. The description should name the exact task, its input, its result, and when the skill should not run.
Tip: Codex uses the description to match tasks. Replace broad language such as `helps with writing` with a specific job and boundary.
- 4
Test a fresh example
Open a new task in the scope where you saved the skill. Call it with `$skill-name` and provide one representative input. Then try one plain-language request that should match and one that should not.
Tip: If either trigger test fails, tighten the description and test again.
Understanding
The project determines where a repository skill can run
A repository skill belongs to one project, while a user skill can appear across projects. Open the relevant Codex project before deciding which scope fits the workflow.
Official sources and check dates
The dates below show when each official source was checked against the steps on this page.