54Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.54Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.
55Skills are loaded and visible to the agent (at least their metadata), so Codex can discover and choose them implicitly. This keeps rich workflows available without bloating context up front.55Skills are loaded and visible to the agent (at least their metadata), so Codex can discover and choose them implicitly. This keeps rich workflows available without bloating context up front.
56 56
57Use skill folders to author and iterate on workflows locally. If a plugin
58already exists for the workflow, install it first to reuse a proven setup. When
59you want to distribute your own workflow across teams or bundle it with app
60integrations, package it as a [plugin](https://developers.openai.com/codex/plugins/build). Skills remain the
61authoring format; plugins are the installable distribution unit.
62
57A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.63A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.
58 64
59- my-skill/65- my-skill/
87 93
88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.94Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.
89 95
9096| Layer | Global | repo || Layer | Global | Repo |
91| :----- | :--------------------- | :--------------------------------------------- |97| :----- | :--------------------- | :--------------------------------------------- |
92| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |98| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |
93| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |99| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |
145Build in this order:151Build in this order:
146 152
1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.1531. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.
1481542. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.2. Install a [plugin](https://developers.openai.com/codex/plugins) when a reusable workflow already exists. Otherwise, create a [skill](https://developers.openai.com/codex/skills) and package it as a plugin when you want to share it.
1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).1553. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).
1504. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.1564. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.