# Skills in Codex

Codex skills are folders with a SKILL.md that it scans from .agents/skills, lists by name and description, and loads in full when you mention them with $ or the task matches.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/skills/codex

This page covers Codex CLI; the IDE extension uses the same skill folders and `$` mention.

## At a glance

| | Codex |
|---|---|
| Term | Skill: a directory with a `SKILL.md` file |
| Configured in | `.agents/skills/<name>/` in the repo, `~/.agents/skills/` for you; `~/.codex/config.toml` to disable one |
| Loads / runs | Name, description and file path are listed at start; the full `SKILL.md` loads when Codex selects the skill or you mention it |
| Scope & precedence | Repo, user, admin, system locations; the docs state no precedence between them. Same-name skills are not merged |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Skill instructions and frontmatter | `.agents/skills/add-migration/SKILL.md` |
| 2 | Conventions the skill reads on demand | `.agents/skills/add-migration/references/drizzle-conventions.md` |
| 3 | Verification script (shown on the [example scenario](https://ai-sw-factory.mellicci.dev/fundamentals/skills/example-scenario) page) | `.agents/skills/add-migration/scripts/check-migration.sh` |
| 4 | Invoke it | `codex '$add-migration add a priority column to tickets'` |

`.agents/skills/add-migration/SKILL.md`:

```markdown
---
name: add-migration
description: "Change the ticket-service database schema safely: edit src/db/schema.ts, generate a migration with pnpm db:generate, and verify it. Use for any new table, column or index."
---

1. Run `ls src/db/migrations` to see the current migrations.
2. Read `references/drizzle-conventions.md`.
3. Edit `src/db/schema.ts` for the change I requested in my prompt.
4. Run `pnpm db:generate`. Never edit files in `src/db/migrations/`.
5. Run `scripts/check-migration.sh` and fix what it reports.
6. Summarize the new migration file and its SQL.
```

Codex picks the skill implicitly when your request matches the description, or you name it with `$add-migration` (or pick it from `/skills`). Codex detects new skills automatically; restart it if one doesn't appear.

## Specifics

### Locations and discovery

| Scope | Location | Note |
|---|---|---|
| Repo | `$CWD/.agents/skills`, each parent up to `$REPO_ROOT/.agents/skills` | Scans every directory from the working directory to the repository root |
| User | `$HOME/.agents/skills` | Follows you across repositories |
| Admin | `/etc/codex/skills` | Machine or container defaults |
| System | Bundled with Codex | For example `skill-creator` and plan skills |

Symlinked skill folders are followed. To disable a skill without deleting it, add an entry to `~/.codex/config.toml` and restart Codex:

```toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
```

List skills with `/skills` in the CLI. A plugin is the unit for distributing skills (and optionally MCP servers) to others; direct folders are for local and repo use.

### SKILL.md fields

| Field or file | Status | Purpose |
|---|---|---|
| `name` | Required | Skill name; the `$` mention uses it |
| `description` | Required | What it does and when to use it; drives implicit selection |
| `scripts/`, `references/`, `assets/` | Optional | Code, documentation, templates |
| `agents/openai.yaml` | Optional | App UI metadata, tool dependencies, and `policy.allow_implicit_invocation` (default `true`; `false` leaves only explicit `$skill`) |

The documentation lists no other frontmatter fields.

### Invocation and arguments

| Way | Syntax | Note |
|---|---|---|
| Explicit | `$add-migration` in your prompt | Also `/skills` to pick from a list |
| Implicit | Your request matches the `description` | Front-load the key use case and trigger words |

The documentation doesn't specify argument placeholders for skills. The fallback used above: the requested change is plain text in your prompt, and the instructions say to read it there. Custom prompts (`~/.codex/prompts/*.md`, run as `/prompts:<name>`) do support `$1`–`$9`, `$ARGUMENTS` and named `$KEY` placeholders, but the docs mark them deprecated in favor of skills, which can also be shared through a repo and invoked implicitly.

### Scripts and pre-injected data

| Mechanism | In Codex |
|---|---|
| Scripts in `scripts/` | Supported; the instructions tell Codex to run them, and the output lands in context |
| Command pre-injection while loading | The documentation doesn't specify it |
| Fallback | Step 1 has Codex run `ls src/db/migrations` itself |

Script approval prompts follow your approval policy; `approval_policy.granular.skill_approval` controls whether skill-script prompts surface.

### Context cost and visibility

| What | Cost |
|---|---|
| Initial list | Name, description and file path of every skill, capped at 2% of the context window (8,000 characters if the window is unknown) |
| Over budget | Codex shortens descriptions first, then may omit skills and show a warning |
| Selected skill | Full `SKILL.md` is read regardless of the budget |
| Setting | `skills.max_context_tokens` in `config.toml`; default 2% of the window, explicit values capped at 10,000 tokens |

## Gotchas

- Put the trigger words at the start of the description; shortened descriptions can lose the end.
- Codex doesn't merge skills that share a `name`; both can appear in the selector.
- With many skills installed, some may be dropped from the initial list. Trim or disable unused ones.
- Edits to `config.toml` need a restart. Skill folder changes are detected automatically.
- Treat a skill you didn't write, from a plugin or another repository, as code: read it before you run it.