boshu2__agentops/docs/contracts/codex-skill-api.md

Codex Skill API Contract

Source of truth for what the Codex runtime actually supports. All converter output and validation must conform to this contract. Orientation contract: AGENTS.md.

Official docs:

• Codex Skills
• Build skills and invocation policy
• Codex Multi-Agent
• Codex CLI Features

---

SKILL.md Frontmatter

Every generated AgentOps Codex projection emits only the two fields Codex uses for discovery:

---
name: skill-name
description: 'Explain when this skill triggers and when it does not.'
---

The portable Agent Skills specification requires name and description and also permits license, compatibility, string-to-string metadata, and the experimental space-separated allowed-tools field. The AgentOps generator does not currently emit those optional fields. AgentOps-only fields such as skill_api_version, context, model, user-invocable, and output_contract must be stripped from Codex output.

---

Optional: agents/openai.yaml

Codex skills may include agents/openai.yaml for display metadata and policy:

interface:
  display_name: "User-facing name"
  short_description: "Brief description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "toolName"
      description: "Tool description"
      transport: "streamable_http"
      url: "https://example.com"

Field	Purpose
interface.display_name	User-visible name in Codex UI
interface.short_description	Brief description for skill browser
policy.allow_implicit_invocation	false prevents auto-activation (explicit $skill only)
dependencies.tools	MCP server dependencies

The Codex default for policy.allow_implicit_invocation is true. Setting it to false prevents implicit activation while preserving explicit $skill invocation. For parity projections, scripts/codex-sync.sh maps canonical disable-model-invocation: true to this policy. It merges that field into the projected copy of source agents/openai.yaml, preserving its UI metadata, dependencies and other policy fields. If no source file exists, it generates the policy file alone.

The generator always derives metadata from canonical source files. Removing the frontmatter flag, or setting it to false, restores source YAML verbatim or removes a generated-only policy file. A caller-authored source policy is still respected; with no explicit source policy, Codex's default applies. For development installs linked directly to skills/<name>/, set the matching policy in canonical agents/openai.yaml; those installs bypass projection.

---

Skill Discovery And Installation

The portable Codex skill root is .agents/skills/ at repository or parent scope and $HOME/.agents/skills/ at user scope. Current Codex desktop installs may also index $HOME/.codex/skills/; on Bo's development fleet both user roots are symlinks to this repository's canonical skills/ tree.

Scope	Path	Use Case
Repo (nearest)	.agents/skills/ from CWD	Folder-specific workflows
Repo (parent)	../.agents/skills/	Nested repo organization
Repo (root)	$REPO_ROOT/.agents/skills/	Organization-wide skills
User	$HOME/.agents/skills/	Portable personal skill collection
Host compatibility	$HOME/.codex/skills/	Codex-host symlink root when configured
Admin	/etc/codex/skills/	System-wide defaults
System	Bundled with Codex	Built-in skills

Development symlinks may point directly at skills/<name>/; checked-in skills-codex/ packages are the portable Agent Skills release projection. Canonical skills/ frontmatter is intentionally host-extended and is evaluated against the AgentOps profile, not mislabeled as portable. The release gate scripts/validate-codex-api-conformance.sh validates every projected package against the portable field, type, identity, body, and relative-resource-link contract before applying Codex-specific checks. Plugin caches are neither source nor an installation target and may be deleted without affecting the canonical repository skills.

---

Skill Invocation

Method	Syntax	Description
Explicit	$skill-name or /skills menu	User directly requests the skill
Implicit	Automatic	Codex matches task to skill description

Skills are loaded via progressive disclosure: metadata first (name, description), full SKILL.md only when activated. Because the description is the implicit-routing surface, a projection must preserve the complete source description, including use cases, preconditions, exclusions and any Triggers: clause. Only whitespace is normalized. Keep source descriptions concise and front-load their key use case: Codex may shorten the initial discovery list to fit its context budget, but the generated package must not silently discard routing meaning. A dropped sentence is a behavioral defect even when the body remains byte-complete.

---

Multi-Agent (Sub-Agents)

Current Codex releases enable subagent workflows by default. Codex only spawns subagents when the operator or parent agent explicitly asks it to do so. Subagents inherit the parent sandbox policy and live runtime overrides.

Agent Roles

Codex ships with these built-in roles:

Role	Purpose
default	General-purpose fallback
worker	Execution-focused implementation
explorer	Read-heavy codebase exploration

Custom agents live as standalone TOML files under $HOME/.codex/agents/ for personal agents or .codex/agents/ for project-scoped agents. Each custom agent file must define name, description, and developer_instructions. Optional fields such as nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config inherit from the parent session when omitted.

Global subagent limits stay in the [agents] section of config.toml:

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

[agents.reviewer]
description = "Code review specialist"
config_file = "codex-reviewer.toml"

agents.max_threads defaults to 6; agents.max_depth defaults to 1, which allows direct child agents but prevents deeper recursive fan-out.

Batch Processing

spawn_agents_on_csv processes batches of similar tasks:

Parameter	Description
csv_path	Source CSV file
instruction	Worker prompt template with {column_name} placeholders
id_column	Stable identifiers
output_schema	Fixed JSON structure for worker results
output_csv_path	Destination CSV containing row metadata and results
max_concurrency	Parallel worker limit
max_runtime_seconds	Worker timeout

Workers call report_agent_job_result exactly once.

sqlite_home controls where Codex stores the SQLite-backed state used for agent jobs and exported results.

Codex Built-in Tools

Tools available inside a Codex agent session:

Tool	Purpose
read_file	Read file contents
list_dir	List directory contents
glob_file_search	Find files by pattern
apply_patch	Apply file edits (diff-based)
rg	Ripgrep search
git	Git operations
Shell/terminal tool	Shell command execution
spawn_agent	Create a focused sub-agent
send_input	Send follow-up input to a sub-agent
wait_agent	Wait for one or more sub-agents
close_agent	Stop a stuck or no-longer-needed sub-agent

Claude → Codex Primitive Mapping

Claude Code	Codex Equivalent	Converter Action
Read tool	read_file	Map
Edit tool	apply_patch	Map
Grep tool	rg	Map
Glob tool	glob_file_search	Map
Agent(subagent_type="Explore")	Explorer agent role	Map
Skill(skill="name")	$name invocation	Map
TaskCreate / TaskList / TaskUpdate	No equivalent (todo_write/update_plan not available — empirically verified)	Strip
TeamCreate / TeamDelete	No equivalent	Strip
SendMessage	send_input for brief follow-up only	Rewrite or strip
EnterPlanMode / ExitPlanMode	No equivalent	Strip
EnterWorktree	No equivalent	Strip
context.window	No equivalent	Strip from frontmatter
context.sections.exclude	No equivalent	Strip from frontmatter
context.intel_scope	Deprecated — ignored, no reader	Does not exist
disable-model-invocation: true	agents/openai.yaml → policy.allow_implicit_invocation: false	Map policy; strip from frontmatter

Unmapped Claude-only primitives produce broken instructions in Codex.

disable-model-invocation controls automatic skill selection. Stripping it without mapping the invocation policy changes behavior. Codex supports the equivalent explicit-only policy while keeping the field out of portable SKILL.md frontmatter.

---

Converter Requirements

When generating Codex skills from source skills:

1. Strip all non-Codex frontmatter — emit only name + description, preserving the complete source description as the activation catalog signal and mapping disable-model-invocation: true into agents/openai.yaml policy
2. Map Claude tools to Codex tools — Read→read_file, Edit→apply_patch, Grep→rg, Glob→glob_file_search
3. Rewrite Skill(skill="X") to $X — Codex uses dollar-prefix invocation
4. Strip ALL task/team primitives — TaskCreate, TaskList, TeamCreate, SendMessage (none have working Codex equivalents as direct tool calls — todo_write/update_plan empirically unavailable, and send_input is follow-up-only)
5. Fix paths — avoid host-specific installed-skill paths; use repository-relative links in shipped instructions
6. Rewrite reference files — .md files in references/ pass through codex_rewrite_text() during copy
7. Preserve skill body — the SKILL.md body (instructions) is the skill's value; keep it functional

---

Validation Criteria

A Codex-conformant skill must:

1. Have frontmatter with only name and description
2. Contain no Claude-only primitive names (TaskCreate, TeamCreate, SendMessage, etc.)
3. Contain no Claude-specific paths and no dependency on one host's installed-skill root
4. Have valid agents/openai.yaml if present
5. Not reference non-existent Codex features (context controls, plan mode, etc.)

---

Generated inventories

skills/<name>/SKILL.md metadata owns the skill inventory and dependency graph. Run scripts/regen-all.sh after changing it. The CLI command surface is a separate executable projection generated from Cobra; no handwritten CLI-to-skill map is maintained.

---

Codex Skill Maintenance

Codex is a first-class runtime in this repo.

• skills/<name>/SKILL.md is the canonical behavior contract.
• skills-codex-overrides/<name>/ is the Codex-specific tailoring layer.
• skills-codex-overrides/catalog.json is the machine-readable treatment map for the full catalog.
• skills-codex/<name>/ is the generated checked-in Codex runtime artifact.

Editing an EXISTING parity skill regenerates its Codex twin — not just hashes. make regen-all / scripts/codex-sync.sh refresh parity-only twins from skills/<name>/ whenever their generated body, prompt, or mirrored references drift. scripts/regen-codex-hashes.sh remains the bookkeeping step after content is current. Manual edits under skills-codex/<name>/ are reserved for bespoke skills or deliberate Codex-only divergence recorded in skills-codex-overrides/catalog.json; otherwise fix the source skill or the codex-sync transform/template and regenerate.

The current catalog has no bespoke or pointer twins. Every live Codex package is a generated parity projection of skills/<name>/SKILL.md plus its linked local files. scripts/codex-sync.sh owns those packages; manual edits under skills-codex/<name>/ are drift and will be overwritten.

skills-codex-overrides/catalog.json remains the explicit treatment registry. If a future runtime-specific implementation is genuinely necessary, declare it there before editing a twin and add focused parity tests in the same change. Do not create an undocumented exception or a second skill inventory.

When a skill change affects Codex behavior, phrasing, orchestration, or UX:

1. Update the source skill under skills/ when the shared contract changes.

2. For parity-only skills, update source or the codex-sync transform/template and regenerate. Update skills-codex/<name>/SKILL.md directly only when the Codex runtime copy is bespoke, or update skills-codex-overrides/<name>/ when the Codex experience should differ from Claude.

   • Prompt/operator-layer changes belong in skills-codex-overrides/<name>/prompt.md.
   • Durable Codex-only body rewrites belong in skills-codex-overrides/<name>/SKILL.md.

3. Run the semantic audit if the checked-in Codex body looks suspicious:

   bash scripts/audit-codex-parity.sh
   # or target one skill
   bash scripts/audit-codex-parity.sh --skill <name>
   

4. Validate the checked-in Codex artifacts:

   bash scripts/audit-codex-parity.sh
   bash scripts/validate-codex-override-coverage.sh
   bash scripts/validate-codex-generated-artifacts.sh --scope worktree
   bash scripts/validate-headless-runtime-skills.sh
   python3 scripts/check-cathedral-cut-conformance.py
   

Think of skills/ as the shared contract, skills-codex-overrides/ as the durable Codex-only tailoring layer, and skills-codex/ as the checked-in Codex artifact shipped to users.