Codex Skills: Build and Run Reusable Workflows

Codex skills are reusable packages of instructions, supporting files, and sometimes scripts that help Codex handle a recurring task consistently. You build one by defining when it applies and how to do the work, then make it available in a Codex environment so it can be selected or invoked when relevant.

What Codex skills are

A skill is a small, task-focused workflow for an AI coding agent. Instead of repeating the same detailed prompt every time, you store the guidance in a named package that Codex can consult when the task fits. Examples include reviewing a pull request against a team checklist, updating documentation after an API change, or preparing a release summary from repository files.

A skill is not the same as a model, a plugin, or a general project instruction file. It is a reusable procedure: it tells Codex what the job is, which context matters, and what steps or tools to use. Skills can be concise, or include extra reference material and executable helpers when a task benefits from them.

How a skill is structured

At minimum, a skill needs a directory containing a SKILL.md file. That file provides the skill’s name and description, along with instructions for carrying out the task. The name and description help Codex determine whether the skill is relevant; the rest of the file explains how to perform it.

A skill directory may also contain supporting resources, such as scripts, templates, examples, or reference documents. Keep the main instructions focused, and put longer material in separate files that the instructions tell Codex when to read. This makes it easier to maintain the workflow without loading every detail for every request.

A simplified layout might look like this:

• review-checklist/SKILL.md — purpose, applicability, and review procedure.
• review-checklist/references/standards.md — detailed project conventions.
• review-checklist/scripts/check.sh — an optional repeatable check, if appropriate for the environment.

Exact conventions can vary by Codex product and configuration, so check the documentation for the environment you use before assuming a particular discovery path or command.

Building a useful workflow

Start with a task that recurs and has a recognizable outcome. A skill works best when it can describe both when to use it and what “done” means. “Help with code” is too broad; “check a change for missing tests, backward compatibility, and documentation updates” gives Codex a more useful scope.

1. Choose a bounded task. Identify the repeated request, its inputs, and the expected result.
2. Write a precise description. State the situations that should trigger the skill and those that should not.
3. Document the procedure. Give an ordered checklist, relevant repository locations, and how to handle uncertainty or missing information.
4. Add only useful resources. Include templates, reference files, or scripts if they improve consistency; avoid unnecessary dependencies.
5. Try realistic prompts. Test both a request that should activate the skill and a similar one that should not.
6. Revise from observed results. Remove ambiguity, add missing edge cases, and keep instructions aligned with how the repository actually works.

For example, a documentation-update skill might tell Codex to inspect the changed public interfaces, find the corresponding guide, preserve the existing style, and report if no documentation location is clear. That is more reliable than telling it simply to “update the docs,” because it defines a process and a sensible stopping point.

Making skills available and putting them to work

Creating the directory is only one part of using a skill: Codex must be able to discover it in the environment where the task runs. Depending on the product and setup, skills may be stored in a project location or a user-level location. Follow the relevant Codex instructions for the supported location, then reopen or refresh the working session if the environment requires it to recognize changes.

Once available, a skill may be selected explicitly or used by Codex when the request matches its description, depending on the interface. Do not assume automatic selection is guaranteed. If the workflow is important, name the skill in your request, or verify from the interaction that its instructions were actually applied.

Skills guide the work; they do not make results infallible. Review code changes, run relevant tests, and inspect generated files before accepting them. A skill can also explain a verification step, such as running a project’s test command, but whether that command can run depends on the tools and permissions available in the session.

Choosing what belongs in a skill

Use a skill for repeatable, task-level guidance. Keep instructions tied to the task rather than trying to encode every preference or project fact into one large document. Project-wide conventions may belong in the repository’s general agent instructions, while a skill can explain a specialized workflow that applies only to certain requests.

• Good fit: a repeatable review checklist, a release-note workflow, or a migration procedure with clear verification steps.
• Weak fit: a one-off request, an instruction that applies to every conversation, or a process that depends on unavailable private information.
• Consider a script: when the work is deterministic and a command can perform it more reliably than prose alone.
• Keep human judgment: when decisions depend on product intent, incomplete requirements, or trade-offs the skill cannot resolve.

Skills and scripts can complement each other. The instructions can tell Codex when to run a script, what its output means, and what to do if it fails. A script should not silently make consequential changes beyond the workflow’s intended scope.

Common problems and safety considerations

If a skill is not being used, check its location, its required file name and structure, and whether its description clearly matches the request. Also check whether the current interface supports skills and whether it needs a refreshed session. Vague descriptions can make a skill hard to select, while overly broad descriptions can cause it to be considered for unrelated work.

If Codex follows the skill inconsistently, make the procedure concrete. Replace subjective phrases such as “check carefully” with observable checks, and say what to do when a check cannot be completed. Avoid conflicting instructions across the skill, project guidance, and the user’s request; where instructions disagree, clarify which source should govern.

Treat skill files as instructions, not as a security boundary. Review scripts and referenced content before using them, especially if they can access files, execute commands, or transmit data. Keep secrets out of skill files and avoid granting tools broader access than the task needs. A skill should not override the user’s intent or substitute for reviewing potentially destructive actions.

Frequently Asked Questions

Do Codex skills run automatically?
They may be selected when their descriptions match a task, depending on the Codex environment. For important workflows, explicitly request the skill and confirm it was applied rather than relying on automatic selection.

Can a Codex skill include scripts?
A skill can include supporting files such as scripts, where the environment permits them. Document what each script does and how to interpret its output; inspect it before use, particularly if it changes files or runs commands.

Are skills the same as project instructions?
No. Project instructions generally describe guidance that applies broadly to work in a repository. A skill packages a more specific, reusable workflow for tasks that meet its stated conditions.

Can I share a skill with a team?
You can share its files through an appropriate team or repository workflow, provided the members’ Codex environments support the same skill format and location. Document any assumptions about tools, commands, and project structure.

How do I know whether a skill is working?
Try representative requests, including one that should match and one that should not. Check whether Codex follows the procedure, handles missing information sensibly, and produces the expected output; revise the description or steps if it does not.

Related

• What Is an NFC Tag and How Does It Work?
• Learning Agents: 4 Parts & How They Work
• When to Retire a Working Feature: Decision Guide