Conventions Codex

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.

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, developerName, category, capabilities
• defaultPrompt — an array of starter prompts (not a single string). At most 3 entries (extras ignored); each capped at 128 characters (longer entries truncated).
• websiteURL, privacyPolicyURL, termsOfServiceURL
• brandColor, composerIcon, logo, logoDark (dark-mode logo variant), screenshots (PNG files stored under ./assets/, paths relative to plugin root)

Notation: $+ARGUMENTS and $+{CLAUDE_PLUGIN_ROOT} in this file are split by a + so Claude Code does not replace them when it loads this skill; the real tokens have no + (nlpm:conventions-claude §2.4).

A manifest path REPLACES the default location; it does not add to it (observed on Codex 0.159.2 on 2026-10-01 through the app-server skills/list and hooks/list methods; this corrects the earlier "paths supplement default discovery" claim):

• skills — with no skills key, Codex loads the plugin-root skills/ directory. With "skills": "./codex/skills/", root skills/ is not loaded.
• hooks — with no hooks key, Codex loads the plugin-root hooks/hooks.json, including a Claude Code plugin's hooks file (it expands $+{CLAUDE_PLUGIN_ROOT} there). With "hooks": "./codex/hooks.json", the root file is not loaded. To keep a plugin's Claude hooks out of Codex, point hooks at a file holding {"hooks": {}}.
• apps, mcpServers — replacement vs. addition not verified this pass.

"commands": [] stops Codex turning a plugin's Claude Code commands/*.md into extra skills. Without it, Codex 0.159.2 converts commands into skills named source-command-<command> (written under .codex-plugin/migrated-command-skills/ in the installed copy), which duplicate a Codex port's own skills. It converts only some commands (commands whose body uses $+ARGUMENTS were skipped in testing, and a few without it were too), so the duplicates are easy to miss. A plugin that ships a Claude commands/ directory alongside a Codex skill tree should set "commands": []; do NOT flag the key as unknown.

A symlinked skill directory is dropped on install (Codex 0.159.2, local and Git marketplace sources alike): the installed copy omits it, so the skill never loads. Ship real directories in a Codex skill tree.

4. .agents/plugins/marketplace.json (marketplace manifest)

Three marketplace tiers exist in Codex:

• Official Curated — OpenAI-managed. Workspace plugin publishing and additional marketplaces (Amazon Bedrock, Claude Code interop) shipped in 0.146.0 (2026-07-29); the exact self-serve mechanics are still settling — verify before asserting.
• Repository — <repo-root>/.agents/plugins/marketplace.json aggregates plugins shipped from that repo.
• Personal — ~/.agents/plugins/marketplace.json.

Schema:

{
  "name": "xiaolai",
  "interface": {
    "displayName": "xiaolai Marketplace"
  },
  "plugins": [
    {
      "name": "nlpm",
      "source": {
        "source": "github",
        "repo": "xiaolai/nlpm"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_USE"
      },
      "category": "developer-tools",
      "interface": {
        "displayName": "nlpm"
      }
    }
  ]
}

Per-plugin source types: "github", "git", "local".

policy values are UPPERCASE enums (corrected 2026-08-04 against nlpm's own shipping .agents/plugins/marketplace.json and observed real plugins): installation e.g. "AVAILABLE"; authentication e.g. "ON_USE" or "ON_INSTALL". The lowercase "auto"/"none" the v0.3.0 overlay showed was wrong — do NOT flag AVAILABLE/ON_USE/ON_INSTALL as invalid.

5. .codex/config.toml

TOML — NOT JSON. Top-level sections nlpm cares about:

• [features] — feature flags. Breaking change ~2026-04 (CLI 0.129+): [features].codex_hooks was renamed to [features].hooks (boolean; enables hooks from hooks.json or inline [hooks]). Old key is a deprecated alias and emits a warning. Flag config files that still use codex_hooks.
• [mcp_servers.<id>] — MCP server registrations. Fields: command, args, cwd, url, enabled, enabled_tools, disabled_tools, env, startup_timeout_sec, tool_timeout_sec (per-tool, default 60s — added 2026-06).
• [hooks.<event>] — inline hook registrations (alternative to .codex/hooks.json).
• [agents] — global subagent settings ONLY: enabled, max_concurrent_threads_per_session, default_subagent_model, default_subagent_reasoning_effort, interrupt_message. Individual subagents are not [agents.<name>] tables — they are standalone TOML files at .codex/agents/*.toml (project) or ~/.codex/agents/*.toml (personal), one file per agent, with required name + description + developer_instructions and optional model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config (corrected 2026-08-02 — the old [agents.<name>] / config_file / nickname_candidates schema is gone).
• [permissions.*] — permission policy.
• project_doc_max_bytes, project_doc_fallback_filenames — AGENTS.md controls (see §7).
• Optional model-catalog JSON path loaded at startup, overridable per profile.

REMOVED — [profiles.*] table syntax is gone as of 0.134.0 (2026-05-26). Profiles now live in dedicated per-profile files ~/.codex/<name>.config.toml, selected with --profile <name>. A config still using [profiles.foo] tables is stale — flag it.

No .mcp.json at repo root. Codex does NOT read Claude's .mcp.json — MCP servers live inside config.toml. A bridge from .mcp.json → .codex/config.toml is a common port pattern (see cc-suite:bridge-mcp skill).