Codex skills: where they live, how $ invocation works, and how to write one

A skill is a directory. The only required file is SKILL.md: YAML frontmatter with a name and a description, then Markdown instructions. Around it, three optional folders carry weight the instructions can lean on: scripts/ for executable code the skill tells Codex to run, references/ for documentation too long to inline, and assets/ for templates. An optional agents/openai.yaml adds UI metadata and dependencies for distribution.

---
name: apply-design-system
description: Apply the project design system when building or editing UI. Use for any component, page, or styling task; reads DESIGN.md and forbids colors, fonts, or spacing outside its tokens.
---

# Apply the design system

1. Read DESIGN.md at the repo root before writing any UI code.
2. Use only its semantic tokens for color, its type scale for text,
   and its spacing scale for layout.
3. If a needed value has no token, stop and say so instead of
   inventing one.

• .agents/skills/ in the repository: project skills, shared with everyone who clones it.
• ~/.agents/skills/: your personal skills, present in every project.
• /etc/codex/skills: admin-managed skills on shared machines.
• System bundles that ship with the product.
• Installed skills: $skill-installer pulls curated ones; plugins distribute beyond that.

The repo location is the one that changes team behavior. A skill in .agents/skills/ rides along with the codebase: every collaborator, every CI run, every fresh clone gets the same procedures without setup. Project contracts, how UI gets styled, how releases go out, belong there rather than in any one person's home directory.

Explicit invocation is the easy case: type $ in the Codex CLI and select the skill, and it loads regardless of how its description reads. The interesting case is implicit: Codex keeps each skill's name and description available, and pulls in the full body when it judges your request matches. That judgment can only be as good as the description, which makes the description the real interface. "Use for any component, page, or styling task" gives the matcher verbs and situations to bind to; "design helper" gives it nothing.

Codex reads AGENTS.md on every run: it is the project's standing orders, build commands, conventions, constraints, and every line of it is paid for on every request. Skills are the opposite contract: near-zero cost while idle, full procedures when relevant. The division that works is short rules in AGENTS.md, long procedures in skills, and durable artifacts (token files, DESIGN.md, schemas) in the repo where both can point at them. The full file taxonomy, including where CLAUDE.md and DESIGN.md sit, is in CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

The example skill above is nine lines of instruction, and that is its strength. Everything it enforces lives in one artifact: a DESIGN.md at the repo root carrying the actual system, semantic color tokens in light and dark, the type scale, spacing, motifs, and do-not rules. Codex is a strong implementer with no visual memory between sessions; the file is the memory. Skills full of adjectives ("clean, modern, consistent") do nothing, because there is nothing to check work against. A skill pointing at a file with exact values turns every styling decision into a lookup.

npx --yes identityforge@latest apply ambient-sage

The SKILL.md convention grew into an open agent-skills standard: Claude Code discovers the same shape under .claude/skills/, and Cursor's Agent Skills load the same way next to its Rules. Discovery paths and invocation syntax differ per tool; the anatomy and the description-driven trigger do not. Write skills that reference artifacts in your repository rather than one tool's internals and they transfer almost verbatim; the Claude Code side of the same story is in Claude Code skills, explained.