e97f85bd53
* Add OpenCode converter coverage and specs * Add Codex target support and spec docs * Generate Codex command skills and refresh spec docs * Add global Codex install path * fix: harden plugin path loading and codex descriptions * feat: ensure codex agents block on convert/install * docs: clarify target branch usage for review * chore: prep npm package metadata and release notes * docs: mention opencode and codex in changelog * docs: update CLI usage and remove stale todos * feat: install from GitHub with global outputs
60 lines
3.7 KiB
Markdown
60 lines
3.7 KiB
Markdown
# Codex Spec (Config, Prompts, Skills, MCP)
|
||
|
||
Last verified: 2026-01-21
|
||
|
||
## Primary sources
|
||
|
||
```
|
||
https://developers.openai.com/codex/config-basic
|
||
https://developers.openai.com/codex/config-advanced
|
||
https://developers.openai.com/codex/custom-prompts
|
||
https://developers.openai.com/codex/skills
|
||
https://developers.openai.com/codex/skills/create-skill
|
||
https://developers.openai.com/codex/guides/agents-md
|
||
https://developers.openai.com/codex/mcp
|
||
```
|
||
|
||
## Config location and precedence
|
||
|
||
- Codex reads local settings from `~/.codex/config.toml`, shared by the CLI and IDE extension. citeturn2view0
|
||
- Configuration precedence is: CLI flags → profile values → root-level values in `config.toml` → built-in defaults. citeturn2view0
|
||
- Codex stores local state under `CODEX_HOME` (defaults to `~/.codex`) and includes `config.toml` there. citeturn4view0
|
||
|
||
## Profiles and providers
|
||
|
||
- Profiles are defined under `[profiles.<name>]` and selected with `codex --profile <name>`. citeturn4view0
|
||
- A top-level `profile = "<name>"` sets the default profile; CLI flags can override it. citeturn4view0
|
||
- Profiles are experimental and not supported in the IDE extension. citeturn4view0
|
||
- Custom model providers can be defined with base URL, wire API, and optional headers, then referenced via `model_provider`. citeturn4view0
|
||
|
||
## Custom prompts (slash commands)
|
||
|
||
- Custom prompts are Markdown files stored under `~/.codex/prompts/`. citeturn3view0
|
||
- Custom prompts require explicit invocation and aren’t shared through the repository; use skills to share or auto-invoke. citeturn3view0
|
||
- Prompts are invoked as `/prompts:<name>` in the slash command UI. citeturn3view0
|
||
- Prompt front matter supports `description:` and `argument-hint:`. citeturn3view0turn2view3
|
||
- Prompt arguments support `$1`–`$9`, `$ARGUMENTS`, and named placeholders like `$FILE` provided as `KEY=value`. citeturn2view3
|
||
- Codex ignores non-Markdown files in the prompts directory. citeturn2view3
|
||
|
||
## AGENTS.md instructions
|
||
|
||
- Codex reads `AGENTS.md` files before doing any work and builds a combined instruction chain. citeturn3view1
|
||
- Discovery order: global (`~/.codex`, using `AGENTS.override.md` then `AGENTS.md`) then project directory traversal from repo root to CWD, with override > AGENTS > fallback names. citeturn3view1
|
||
- Codex concatenates files from root down; files closer to the working directory appear later and override earlier guidance. citeturn3view1
|
||
|
||
## Skills (Agent Skills)
|
||
|
||
- A skill is a folder containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. citeturn3view3turn3view4
|
||
- `SKILL.md` uses YAML front matter and requires `name` and `description`. citeturn3view3turn3view4
|
||
- Required fields are single-line with length limits (name ≤ 100 chars, description ≤ 500 chars). citeturn3view4
|
||
- At startup, Codex loads only each skill’s name/description; full content is injected when invoked. citeturn3view3turn3view4
|
||
- Skills can be repo-scoped in `.codex/skills/` or user-scoped in `~/.codex/skills/`. citeturn3view4
|
||
- Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
|
||
|
||
## MCP (Model Context Protocol)
|
||
|
||
- MCP configuration lives in `~/.codex/config.toml` and is shared by the CLI and IDE extension. citeturn3view2turn3view5
|
||
- Each server is configured under `[mcp_servers.<server-name>]`. citeturn3view5
|
||
- STDIO servers support `command` (required), `args`, `env`, `env_vars`, and `cwd`. citeturn3view5
|
||
- Streamable HTTP servers support `url` (required), `bearer_token_env_var`, `http_headers`, and `env_http_headers`. citeturn3view5
|