Skip to content

CowboyLogic/ai-dev / skills/client-config-codex

client-config-codex

Flagged

Manage OpenAI Codex CLI configuration files including config.toml, project .codex/config.toml, profiles, model providers, sandbox and approval settings, permission profiles, rules files, MCP servers, hooks, skills, plugins, custom agents, AGENTS.md instructions, and requirements.toml. Use this skill whenever the user wants to view, edit, add, or understand any Codex setting: trusted projects, approval policy, sandbox mode, network access, allow-listing commands, MCP servers, hooks, skills, plugins and marketplaces, model or reasoning effort, custom model providers, authentication, sessions, or AGENTS.md. Trigger on: "configure codex", "codex config.toml", "trust this project in codex", "codex approval policy", "codex sandbox", "add MCP server to codex", "codex hook", "codex rules", "codex profile", "codex plugin", "set codex model", "codex AGENTS.md", or "show my codex config".

FileKindSize
README.mdmarkdown3.0 KB
SKILL.mdskill md8.9 KB
references/agents-plugins.mdmarkdown12.8 KB
references/cli-commands.mdmarkdown21.2 KB
references/config-schema.mdmarkdown43.0 KB
references/hooks.mdmarkdown17.0 KB
references/instructions.mdmarkdown7.5 KB
references/mcp.mdmarkdown12.9 KB
references/permissions.mdmarkdown23.9 KB
references/skills.mdmarkdown6.6 KB
scripts/show-config.pyscript19.1 KB
scripts/update-references.pyscript6.8 KB
sources.jsonconfig3.8 KB

references/skills.md

View on GitHub
# Skills Reference

A skill is a directory with a `SKILL.md` plus optional scripts and references. Codex starts with
each skill's name, description, and file path, then loads the full `SKILL.md` only when it decides
to use the skill (progressive disclosure). Skills follow the open agent skills standard
(<https://agentskills.io>). Standalone skills work in Codex CLI and the IDE extension; skills
bundled in plugins reach more surfaces.

## Layout

```text
my-skill/
├── SKILL.md            # required: instructions + metadata
├── scripts/            # optional: executable code
├── references/         # optional: documentation
├── assets/             # optional: templates, resources
└── agents/
    └── openai.yaml     # optional: UI metadata, invocation policy, dependencies
```

## SKILL.md

```markdown
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.
```

- `name` and `description` are the only documented required frontmatter fields. The docs describe
  no others (no `allowed-tools`, no invocation toggles). Invocation policy lives in
  `agents/openai.yaml`.
- Implicit matching depends on `description`. Keep it concise, state scope and boundaries, and
  front-load the key use case and trigger words so it survives shortening.
- Keep each skill focused on one job. Prefer instructions over scripts unless you need
  deterministic behavior. Write imperative steps with explicit inputs and outputs.
- Codex detects skill changes automatically. If an update does not appear, restart Codex.

### Catalog budget

The initial skills list is capped at 2% of the model's context window (8,000 characters when the
window is unknown). Codex shortens descriptions first, then may omit skills and show a warning.
Set `[skills] max_context_tokens` in `config.toml` to change the token budget (positive integer,
capped at `10000`). This applies only to the initial list. A selected skill still loads in full.

## Where Codex loads skills

Codex reads repository, user, admin, and system locations. For repositories it scans
`.agents/skills` in **every directory from the current working directory up to the repository
root**.

| Scope | Location |
|-------|----------|
| `REPO` | `$CWD/.agents/skills` |
| `REPO` | `$CWD/../.agents/skills` (a folder above CWD, inside a Git repo) |
| `REPO` | `$REPO_ROOT/.agents/skills` (topmost repo folder; root skills for every subfolder) |
| `USER` | `$HOME/.agents/skills` |
| `ADMIN` | `/etc/codex/skills` |
| `SYSTEM` | Bundled with Codex (for example `skill-creator` and plan skills) |

- Same-`name` skills are **not merged**. Both can appear in skill selectors. The docs state no
  precedence order, so avoid duplicate names across scopes.
- Symlinked skill folders are supported. Codex follows the link target when scanning.
- Plugins can also carry skills. See [agents-plugins.md](agents-plugins.md).

> [!NOTE]
> The docs do not list `$CODEX_HOME/skills` (`~/.codex/skills`) as a scan location. On 0.163.0 it
> is scanned as a user-scope root, alongside `~/.agents/skills`, `$CODEX_HOME/skills/.system`, and
> the repo and working-directory `.agents/skills` (a skill placed there appeared in the model-visible
> list under `codex debug prompt-input`). It holds the bundled system skills under `.system/`
> (`imagegen`, `openai-docs`, `review-agent`, `skill-creator`, `skill-installer`; the bundled
> `plugin-creator` was removed in 0.159.0), and the bundled `$skill-installer` installs into
> `$CODEX_HOME/skills`. Put your own skills in `~/.agents/skills` or a repo's `.agents/skills`, which
> the docs do document.

## Invoking skills

- **Explicit:** run `/skills` in the CLI (or IDE) to pick one, or type `$` to mention a skill by
  name (`$skill-creator`). `/skills` inserts the selected skill's context so the next request
  follows it.
- **Implicit:** Codex chooses a skill when the task matches its `description`.
- To stop implicit use of one skill, set `allow_implicit_invocation: false` in its
  `agents/openai.yaml`. Explicit `$skill` still works. On 0.163.0 such a skill is left out of the
  model-visible skill list (the bundled `review-agent` is an example), so it is used only when invoked
  explicitly.

## Optional metadata: `agents/openai.yaml`

Sets UI metadata for the ChatGPT desktop app, invocation policy, and tool dependencies.

```yaml
interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false   # default true

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"
```

## Enable or disable a skill

Disable without deleting by adding an entry to `~/.codex/config.toml`, then restart Codex:

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

> [!NOTE]
> The docs disagree on `path`: the skills guide and sample config use the `SKILL.md` file path, the
> config reference says "path to a skill folder containing `SKILL.md`". Use the `SKILL.md` path as
> shown. Verified on 0.163.0 with `codex debug prompt-input`: a `SKILL.md` path with
> `enabled = false` removes the skill from the model-visible list, and a folder path has no effect.

Custom agent files can also carry `skills.config` disables. See
[agents-plugins.md](agents-plugins.md).

## Install and create

- **Curated skills:** `$skill-installer <name>` (for example `$skill-installer linear`). You can
  prompt it to download skills from other repositories. Codex detects new skills automatically;
  restart if one does not appear. Curated sources: <https://github.com/openai/skills>.
- **Create:** `$skill-creator` asks what the skill does, when it triggers, and whether it stays
  instruction-only (the default) or includes scripts. Or hand-write `SKILL.md`.
- **Distribute:** for anything reusable beyond one repo, or two or more skills together, or a
  skill plus a connector, package a plugin instead. Direct skill folders are for local authoring
  and repo-scoped workflows.
- **Check:** confirm the skill appears in `/skills`, and test prompts against the `description`
  to confirm the right trigger behavior. `codex debug prompt-input`, run from the directory you care
  about, prints the skill list the model actually receives and makes no model call; use a throwaway
  `CODEX_HOME` for a hermetic check, because the command writes to `$CODEX_HOME`.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall