Where Codex Skills Live: User, Repository, and Load-Failure Troubleshooting

Codex uses .agents/skills as the standard shared location. Older guidance that treated ~/.codex/skills and project/.codex/skills as the default can put new Skills in the wrong place and confuse the personal configuration directory with shareable skills.

The short answer: put reusable personal Skills in $HOME/.agents/skills; put repository rules in .agents/skills inside the repository. Each Skill needs its own directory and SKILL.md.

Four Loading Scopes

Codex scans from the current working directory upward to the repository root, so a monorepo can place more specific .agents/skills in subdirectories. Repository Skills can be reviewed and versioned with Git. User Skills should not contain assumptions that only hold in one project.

Legacy versions, plugins, or local runtimes may still expose .codex/skills, but it should not be the default for new shared Skills. Use the current official documentation and the Skills list exposed by the current session.

Minimal Loadable Skill

1
2
3
4

.agents/
└── skills/
    └── verify-build/
        └── SKILL.md

SKILL.md must begin with valid YAML front matter:

1
2
3
4
5
6
7
8

---
name: verify-build
description: Run the repository build and report reproducible failures.
---

# Verify build

Run the documented build command, preserve logs, and do not publish artifacts.

Keep name stable and distinctive. The description should explain when the Skill applies; the body defines steps, boundaries, and validation.

A File Exists but Does Not Load

1. Check the Actual Path

Make sure there is no extra directory layer and the file is not named SKILL.md.txt:

1
2

Get-ChildItem -Force -Recurse .agents\skills
Get-ChildItem -Force -Recurse (Join-Path $env:USERPROFILE '.agents\skills')

2. Check the First Bytes

A UTF-8 BOM (EF BB BF) before --- can make a strict parser report missing YAML frontmatter delimited by ---. Inspect the first bytes:

1
2
3

$path = '.agents\skills\verify-build\SKILL.md'
$bytes = [IO.File]::ReadAllBytes((Resolve-Path $path))
($bytes[0..([Math]::Min(5, $bytes.Length - 1))] | ForEach-Object { $_.ToString('X2') }) -join '-'

The expected prefix is 2D-2D-2D. If it is EF-BB-BF-2D-2D-2D, back up the file and write UTF-8 without BOM:

1
2
3
4

$resolved = (Resolve-Path $path).Path
$content = [IO.File]::ReadAllText($resolved, [Text.Encoding]::UTF8)
$utf8NoBom = [Text.UTF8Encoding]::new($false)
[IO.File]::WriteAllText($resolved, $content, $utf8NoBom)

3. Check YAML and Duplicate Names

Front matter must close correctly, and complex values after a colon may require quotes. Do not assume same-name Skills from different scopes are merged; rename them or keep only the intended copy.

4. Open a New Session

Skill discovery commonly happens when a session starts. After adding or changing a Skill, open a new Codex session and check the available list. Do not delete the whole configuration directory before verifying path, encoding, and YAML.

Acceptance Checklist

1. The path is .agents/skills/<name>/SKILL.md.
2. The first byte begins ---; no UTF-8 BOM precedes it.
3. YAML parses and contains a stable name and clear description.
4. There is no unintended same-name Skill in another scope.
5. A new session exposes and triggers the Skill as described.

References

• Codex Skills: https://developers.openai.com/codex/skills
• Agent Skills specification: https://agentskills.io/