Install and Configure Skills in Codex

Install a Codex skill by placing a directory containing SKILL.md in ~/.agents/skills/ for personal use or .agents/skills/ for a repository. Give it a specific name and description, keep supporting files in the same directory, and test explicit and automatic invocation.

Choose a discovery location

• User: ~/.agents/skills/<skill-name>/SKILL.md applies across repositories.
• Repository: <project>/.agents/skills/<skill-name>/SKILL.md applies to that project and can be version controlled.
• Nested repository folders: Codex discovers .agents/skills/ directories from the working directory up to the repository root.
• Plugin: <plugin>/skills/<skill-name>/SKILL.md distributes a reusable skill with the plugin.

Use the narrowest location that matches the workflow. Keep personal preferences out of a shared repository skill, and never store credentials in skill instructions or supporting files.

1. Create the skill

mkdir -p ~/.agents/skills/review-release

Create ~/.agents/skills/review-release/SKILL.md:

---
name: review-release
description: Review a release candidate for missing verification, unsafe secrets, and incomplete notes. Use before publishing a release.
---

Read the release notes and changed files. Report blocking issues first, then list the commands used to verify the candidate.

The name and description tell Codex how to present and select the skill. Keep the description concrete so unrelated requests do not trigger it.

2. Configure supporting files

Add references/, scripts/, or templates inside the skill directory when the workflow needs them. Link to each file with a relative path and explain when Codex should read or run it. Avoid copying environment files, secrets, absolute machine paths, or generated output.

For repository scope, copy the complete folder to .agents/skills/review-release/ and review every script before committing it.

3. Verify discovery and behavior

Start Codex in the intended repository. Invoke the skill explicitly with $review-release, then describe the task without naming the skill to test the frontmatter description. Confirm that supporting files load only when needed and scripts operate safely on a disposable release candidate.

Codex detects edits to known skill locations automatically. Restart Codex if you created a top-level skill directory that was not present when the session began.

Update, disable, or remove a skill

Update SKILL.md and its supporting files as one reviewed change, then repeat both tests. A user can disable a specific skill without deleting it by adding a matching [[skills.config]] entry with enabled = false to ~/.codex/config.toml. Remove the whole directory when the skill is no longer needed.

Troubleshooting

• Missing skill: confirm the path ends in <skill-name>/SKILL.md and that Codex started inside the expected repository.
• Wrong skill triggers: narrow the frontmatter description and include explicit use and non-use cases.
• Supporting file missing: use paths relative to SKILL.md and copy the entire directory.
• Project skill ignored: confirm the .agents/skills/ directory lies between the working directory and repository root.
• Duplicate names: Codex does not merge same-named skills; rename or remove the duplicate so users can identify the intended one.

Official sources

These instructions were checked against the following vendor documentation.

• OpenAI: Build skills
• OpenAI: Codex customization