Codex Skills: Choose, Install and Verify a Working Skill

Published on October 27, 2026 by Steven Jones

Codex skills are reusable instructions that tell OpenAI Codex how to carry out a specific task. The difficult part is rarely copying a SKILL.md file. The hard part is choosing a skill that improves an existing workflow, installing it where Codex can find it, and proving it activates only when appropriate.

This guide covers useful skills to start with, a complete read-only example, explicit and automatic invocation, a negative-control test and a reproducible installation failure. The example uses no scripts, API keys or external services, so you can isolate skill behaviour before adding more powerful integrations.

Start with a task, not a directory of skills

Task	Skill worth considering	What you should verify
Review proposed deployments	Read-only release risk checklist	Recognises specific high-risk changes without editing files
Investigate failed CI checks	Repository-specific test failure triage	Uses the actual test commands and distinguishes flaky failures from code faults
Prepare a pull request for review	Local PR readiness checklist	Finds missing tests and documentation without approving or merging
Maintain project documentation	Repository map and conventions updater	Changes only the requested documents and links to the right source files

The best first skill captures a procedure you otherwise repeat: a precise checklist, a required output format or a set of project-specific commands. A generic instruction to “write better code” adds little to a capable coding model. Developers who use large skill collections repeatedly run into overlapping rules and waste context. A small set of narrow, regularly used skills is easier to audit and keep current.

A skill is also different from an MCP server. The skill describes a workflow; an MCP server exposes tools and external actions. If your workflow needs remote GitHub access, read the Codex CLI MCP setup and permissions guide before giving it additional capabilities. Installing a skill does not grant it credentials or bypass Codex approvals.

---

---

Pin the Codex CLI version before testing

Use a known CLI build during a reproducibility check. OpenAI published Codex CLI 0.163.0 on 15 October 2026; the commands below pin that reference build rather than silently installing whatever version happens to be latest when you run them.

npm install -g @openai/codex@0.163.0
codex --version

Record the exact output of codex --version in your test notes. If you use the desktop app or an IDE extension instead, record its version separately, as behaviour and installation paths can differ. Run Codex from the root of the repository where the skill will live, then sign in if required.

Reproduction detail	Value
Reference CLI package	@openai/codex@0.163.0, npm installation
Skill location	.agents/skills/release-risk-note/SKILL.md
Skill dependencies	None beyond a working Codex installation; plain Markdown only
Editorial verification	27 October 2026: skill file structure and misplaced-directory recovery checked locally
Live Codex activation	Not independently executed here; expected results below are a reader-run verification protocol

For current discovery locations and invocation behaviour, see OpenAI’s official skills documentation. Avoid relying on old tutorials that still require an experimental skills flag or assume only the legacy ~/.codex/skills directory is supported.

Install a small original Codex skill

Our example, release-risk-note, reviews a proposed change list and returns a short deployment risk note. It never reads the repository, changes files or approves a release. Those constraints make it a useful first test: you can check the output against a fixed input, and there is no external integration to complicate diagnosis.

In PowerShell, open the repository root and create the required folder:

New-Item -ItemType Directory -Force .agents\skills\release-risk-note | Out-Null
notepad .agents\skills\release-risk-note\SKILL.md

Save the following content as SKILL.md. The YAML frontmatter is mandatory: its name identifies the skill, while its description controls when Codex should consider using it.

---
name: release-risk-note
description: Produce a read-only deployment risk note from a supplied change list. Use when asked to review release or deployment risks. Do not use for release announcements, code changes or deployment approval.
---

# Release risk note

Review only change text supplied by the user. Do not read files, run commands, access the network or edit anything.

Rules:
- If a change includes `DROP TABLE` or explicitly deletes a database table, flag `DESTRUCTIVE_DB`.
- If a change rotates or replaces a secret, token or webhook signing key, flag `SECRET_ROLLOUT`.
- Otherwise, flag `none`.

Use exactly these four labels:

Decision: `HOLD` if one or more flags, otherwise `CHECKS_CLEAR`.
Flags: comma-separated flags in rule order, or `none`.
Evidence: quote the relevant change fragments, or `none`.
Next check: request a backup/rollback plan for `DESTRUCTIVE_DB`; request secret deployment order for `SECRET_ROLLOUT`; otherwise suggest ordinary tests and review.

Never state that a deployment is safe or approved. For multiple flags, include each required next check.

The distinction between the description and body is easy to miss. Codex initially sees a skill’s name, description and location. It loads the detailed instructions after selecting the skill. A beautifully written body will not fix vague discovery metadata, and a strong description cannot rescue incorrect instructions.

Verify discovery, explicit invocation and output

Launch a fresh session with codex from the same repository. Type /skills and look for release-risk-note. Seeing the name establishes discovery, not that the body was read or the task was performed correctly.

Next, explicitly invoke the skill with this exact test prompt:

$release-risk-note Review deployment risks for these changes:
- Rename the checkout button from Submit to Place order.
- Database migration: DROP TABLE legacy_orders.
- Rotate the webhook signing secret for the payment endpoint.

The expected result is a four-field note with the following substantive content. Exact explanatory wording may vary, but neither risk flag should be missing:

Decision: HOLD
Flags: DESTRUCTIVE_DB, SECRET_ROLLOUT
Evidence: "DROP TABLE legacy_orders"; "Rotate the webhook signing secret"
Next check: Confirm a recoverable backup and rollback plan; check the secret deployment order.

Check the session activity as well as the final answer. The skill should be selected and its instructions loaded. If Codex produces a plausible risk assessment without loading the skill, the answer alone does not prove that installation worked. This separation between discovery, loading and correct execution makes troubleshooting much faster.

Test automatic activation, then try to trigger it incorrectly

Open a new Codex session and omit the dollar-prefixed name. Use the same change list, preceded only by: Review the deployment risks in these changes and give me a short release risk note. This is an implicit invocation test. Codex should match the request to the skill description and apply the four-field format. Automatic selection remains model-dependent, so repeat it rather than treating one success as a guarantee.

Now start another session with a negative-control request:

Write a friendly release announcement using this change list.
Do not assess deployment risks.
- Rename the checkout button from Submit to Place order.
- Database migration: DROP TABLE legacy_orders.
- Rotate the webhook signing secret for the payment endpoint.

The release-risk-note skill should not activate. The same source material is present, but the requested task is different. If the four-field risk report appears anyway, the description is too broad, another instruction is interfering, or Codex has selected the wrong workflow. Tighten the description rather than adding more rules to the body.

There is another useful control: ask for a deployment risk note with only the button rename. The expected decision is CHECKS_CLEAR with Flags: none. That does not certify a production release; it only means this narrow checklist found neither of its two defined risk types.

A reproducible installation failure: the wrong skills directory

A common source of confusion is mixing Codex configuration directories with skill discovery directories. For a repository-scoped skill, this guide uses .agents/skills. Putting the file under .codex/skills instead does not satisfy that documented repository location.

Here is a reversible PowerShell failure reproduction, starting from the correct installation above:

New-Item -ItemType Directory -Force .codex\skills\release-risk-note | Out-Null

Move-Item .agents\skills\release-risk-note\SKILL.md .codex\skills\release-risk-note\SKILL.md

Test-Path .agents\skills\release-risk-note\SKILL.md
# False

Move-Item .codex\skills\release-risk-note\SKILL.md .agents\skills\release-risk-note\SKILL.md

Test-Path .agents\skills\release-risk-note\SKILL.md
# True

Both path results were reproduced in a local file-system check. They demonstrate the misplaced-file problem and its correction; they are not a claim that a live Codex session was run. Refresh /skills after moving the file, and restart Codex if the updated list does not appear.

If the skill is listed but never activates automatically, check for policy.allow_implicit_invocation: false in its optional agents/openai.yaml. If the skill is missing entirely, look for a disabled entry in ~/.codex/config.toml. These are different failure classes: a disabled skill is unavailable, while a skill with implicit invocation disabled can still be used explicitly.

Your search, your sources

Make DIY AI a preferred source

See more of our reporting in Google Top Stories, AI Overviews and AI Mode.

Add DIY AI on Google

How to decide whether a skill is actually worth keeping

Compare the same prompt with and without the skill in separate fresh sessions. Record the CLI version, skill revision, model, input and whether Codex loaded the skill. Then assess four things: discovery, task correctness, unwanted activation and side effects. A visible skill that produces no better result than a normal prompt adds maintenance without much benefit.

Review third-party skills before installing them. Read SKILL.md, inspect any scripts, check tool dependencies and permissions, and favour pinned revisions for team use. A skill can carry instructions that request shell commands or remote actions. Neither a popular catalogue nor a large number of stars substitutes for reviewing what those instructions will do in your repository.

Keep repository rules and reusable task procedures separate. Use AGENTS.md for broad project guidance such as test commands and directory conventions; use a skill for a bounded workflow with an identifiable trigger and result. If you are still deciding which coding agent fits your process, DIY AI’s Claude Code vs OpenAI Codex comparison covers the wider agent choice without turning this tutorial into a product comparison.

Codex skills verification checklist

• Record the exact Codex CLI or IDE version and install source.
• Install the skill in the correct repository or user scope, with valid name and description frontmatter.
• Confirm that /skills shows the skill before assessing its output.
• Run one explicit $skill-name prompt and inspect whether the instructions loaded.
• Run an implicit prompt, a negative-control prompt and a low-risk input in fresh sessions.
• Check unintended file changes, commands and external actions before adopting third-party skills.

Keep the skill only if it makes a repeated task more predictable. A four-line deployment note with documented limits is more valuable than a hundred-page collection of untested instructions.