Agent Skills: Reusable automation for Codex
Skills package instructions and optional assets so Codex can perform specific workflows; they can be invoked explicitly or picked automatically when relevant.
Turn repeatable engineering tasks into shareable, composable capabilities. Agent Skills make Codex act like a library of team-owned automations.
Skills package instructions and optional assets so Codex can perform specific workflows; they can be invoked explicitly or picked automatically when relevant.
Source: Codex — Source link
Highlights
| Metric | Value | Notes |
|---|---|---|
| Required skill file | A SKILL.md file is required and must include a name and description. | |
| Optional components | Skills may include scripts, references, and assets (e.g., templates, resources). | |
| Invocation methods | Explicit invocation via /skills or typing $ to mention a skill; implicit invocation when Codex decides to use a matching skill. | Codex web and iOS don’t support explicit invocation yet |
| Progressive disclosure | At startup Codex loads only each skill’s name and description to manage context efficiently. | |
| Load scopes & precedence | Skills are loaded in precedence order: REPO (multiple repo paths), USER (~/.codex/skills), ADMIN (/etc/codex/skills), SYSTEM (bundled). | Higher-precedence locations overwrite lower-precedence skills with the same name |
| Install from GitHub | You can download curated skills with $skill-installer from the OpenAI skills GitHub repository. | Example: $skill-installer create-plan |
Key points
- A skill is a folder with a required SKILL.md and optional scripts, references, and assets.
- SKILL.md must include name and description; metadata.short-description is optional.
- Two activation paths: explicit (user selects or mentions a skill) and implicit (Codex auto-selects when relevant).
- Progressive disclosure keeps prompts efficient: Codex initially loads only skill names and descriptions.
- Skill storage scopes (high → low): REPO paths, USER (~/.codex/skills), ADMIN (/etc/codex/skills), SYSTEM (bundled).
- Use $skill-creator to bootstrap new skills or create a skill manually by adding a SKILL.md to a valid location.
- Expand built-in skills by running $skill-installer to fetch curated skills from GitHub.
Why this matters
Agent Skills turn individual prompts into shareable, versionable capabilities—speeding onboarding, reducing context loss, and enabling teams to automate repeatable developer workflows while controlling scope and precedence.
