/conventions-codex

name: conventions-codex
description: "Codex CLI artifact schemas: config.toml, .codex-plugin, skills, hooks, AGENTS.md."
version: 0.3.2
user-invocable: false

Codex CLI Conventions

Tool-specific overlay for OpenAI Codex CLI artifacts. Loaded by the scorer and checker when an artifact is classified as **Tier 2-Codex** (per `agents/scorer.md` step 3). The universal floor lives in `nlpm:conventions`; this overlay adds Codex-specific schemas on top.

**Last refreshed:** 2026-08-02 against Codex 0.146.0 (2026-07-29); §3/§4 field-type + policy-enum corrections 2026-08-04; §3 artifact-path, `commands` and symlink corrections 2026-10-01, observed on Codex 0.159.2.

**Primary authoritative sources:**

• <https://learn.chatgpt.com/docs> (the `developers.openai.com/codex/*` tree now 308-redirects here)
• <https://learn.chatgpt.com/docs/build-skills>
• <https://learn.chatgpt.com/docs/agent-configuration/agents-md>
• <https://learn.chatgpt.com/docs/agent-configuration/subagents>
• <https://learn.chatgpt.com/docs/config-file/config-reference>
• <https://learn.chatgpt.com/docs/hooks>
• <https://learn.chatgpt.com/docs/skills-and-plugins>
• <https://learn.chatgpt.com/docs/changelog>
• <https://github.com/openai/codex> (authoritative for `CLA.md`, `contributing.md`, and machine-readable spec samples like `plugin-json-spec.md`)

---

1. File system layout

Codex separates the **cross-tool surface** (`.agents/`) from the **Codex-private surface** (`.codex/`). The Claude Code mental model of "everything under one tool directory" does not transfer.

| Artifact | Project scope | User scope | |---|---|---| | Skills | `.agents/skills/<name>/SKILL.md` (CWD→repo-root scan) | `~/.agents/skills/`, admin `/etc/codex/skills/` | | Plugin manifest | `<plugin-root>/.codex-plugin/plugin.json` | — | | Marketplace | `.agents/plugins/marketplace.json` (+ legacy `.claude-plugin/marketplace.json`) | `~/.agents/plugins/marketplace.json` | | AGENTS.md | Git root → CWD; per dir `AGENTS.override.md` → `AGENTS.md` → fallback (one file/dir; closer overrides earlier) | `~/.codex/AGENTS.override.md`, `~/.codex/AGENTS.md` | | Config | `.codex/config.toml` (trust-gated) | `~/.codex/config.toml` | | Hooks | `.codex/hooks.json` OR inline `[hooks]` in `config.toml` | `~/.codex/hooks.json` | | Slash commands / prompts | — (not project-shareable) | `~/.codex/prompts/<name>.md` | | MCP servers | `[mcp_servers.<id>]` table inside `config.toml` | same | | Skill sidecar (Codex-specific) | `<skill>/agents/openai.yaml` next to `SKILL.md` | — |

**Trust gate:** Project hooks load only when `.codex/` is trusted. Trust is enforced via `/hooks` and `allow_managed_hooks_only` in `requirements.toml`.

---

2. SKILL.md (Tier 1, open spec — `name`, `description` required only)

Codex reads SKILL.md from `.agents/skills/`, **not** `.codex/skills/` (reconfirmed 2026-08-02 against `build-skills`: *"Codex reads skills from `.agents/skills` directories, not `.codex/skills`"*; it scans `.agents/skills` from CWD up to the repo root, plus `~/.agents/skills` and `/etc/codex/skills`). Skills placed under `.codex/skills/` — a common mistake in repos ported from Claude Code's `.claude/skills/` habit — are **not discovered** by Codex; flag them. The required frontmatter is the agentskills.io baseline — `name` and `description` — same as every other tool.

**Codex-specific extras live in a SIDECAR `agents/openai.yaml`**, not in SKILL.md frontmatter. Treat the sidecar as additive metadata, not a deviation from the open spec.

**Sidecar fields:**

# <skill>/agents/openai.yaml
interface:
  display_name: "My Skill"
  short_description: "One-line summary"      # added 2026-06
  default_prompt: "Use this skill when..."
  icon_small: "icon-16.png"
  icon_large: "icon-512.png"                 # added 2026-06
  brand_color: "#FF6B00"
policy:
  allow_implicit_invocation: true            # default true; set false to disable auto-selection
dependencies:
  tools:
    - type: "bash"
      value: "jq"
      description: "JSON processor"
      transport: "stdio"

**Correction (2026-06-07):** `dependencies.tools` is an **array of tool objects** (`type`, `value`, `description`, `transport`), **not** a bare string list. The v0.1.0 `- bash` / `- jq` form was wrong.

Duplicate-name skills across scopes are NOT merged — both appear in selectors, repo-level wins for local workflows.

---

3. `.codex-plugin/plugin.json` (plugin manifest)

{
  "name": "my-codex-plugin",
  "version": "1.0.0",
  "description": "Short summary",
  "skills": "./skills/",
  "mcpServers": "./mcp/servers.json",
  "apps": "./apps/",
  "hooks": "./hooks.json",
  "commands": [],
  "interface": {
    "displayName": "My Plugin",
    "longDescription": "Detailed description for installer UI"
  }
}

**Required field:** `name` (kebab-case) — and only when a `plugin.json` is present at all. **All other top-level fields are optional**, including `version`, `description`, `author`, and `interface` (corrected 2026-08-02 against the vendor's `plugin-json-spec.md`; the earlier "version + description required" claim was wrong). Codex 0.159.2 installs a plugin whose manifest lacks `name` but loads none of its skills, so a missing `name` fails silently. **Optional artifact paths — each a relative-path STRING** (corrected 2026-08-04 against the vendor `plugin-json-spec.md`): `skills` (string), `hooks` (string), `apps` (string), `mcpServers` (string **or** object). A bare directory string like `"skills": "./skills/"` is the documented sample form. Do NOT flag a scalar-string `skills`/`hooks`/`apps`/`mcpServers` as wrong. (The v0.3.0 overlay showed only an array form; Codex 0.159.2 also accepts a one-element array for `skills`, but the string is the documented form.)

**Optional identity fields (added 2026-06):** `author` (`{name, email, url}`), `homepage`, `repository`, `license`, `keywords`. **Optional UI block** `interface`:

• `displayName`, `shortDescription`, `longDescription`, `developerNam