codex-cli

Compatibility: Codex CLI (SKILL.md)

Claim (Tier B, narrow). An MDA-compiled SKILL.md whose frontmatter stays inside the agentskills.io v1 envelope subset is discovered and parsed by Codex CLI when installed at the documented discovery paths. name, description, body, and the agentskills.io v1 envelope (including allowed-tools) survive the round-trip from .mda source to runtime ingest.

Claim (negative). Codex CLI's official documentation lists name and description as the only top-level frontmatter fields. Beyond those, agentskills.io v1 envelope fields (license, compatibility, allowed-tools, metadata) are inherited from the upstream standard; MDA v1.0 emits this subset. Anything Codex CLI honors outside agentskills.io v1 is undocumented in the public skills page and is out of MDA v1.0 scope.

Last verified: 2026-05-26 against @markdown-ai/cli@1.1.3, Codex CLI 0.133.0.

Directory contents

• source.mda — dedicated MDA source for this kit (do not reuse for unrelated examples)
• build/SKILL.md — reproducible compile output
• verify.sh — structural verification, no live install needed
• install.sh — optional live install to ~/.agents/skills/mda-compat-codex-cli/SKILL.md
• uninstall.sh — removes the live install
• notes.md — scope, gaps, caveats, graduation criteria

Quick verify (offline, modifies nothing on your system)

./compat/codex-cli/verify.sh

Re-compiles source.mda, validates the output against the SKILL.md JSON Schema, and confirms the envelope subset is intact. Exit 0 means the structural claim holds.

Live verify (writes one file under ~/.agents/skills/)

./compat/codex-cli/install.sh

Copies build/SKILL.md to ~/.agents/skills/mda-compat-codex-cli/SKILL.md. Start (or resume) a Codex CLI session and confirm mda-compat-codex-cli is among the discovered skills.

To remove:

./compat/codex-cli/uninstall.sh

How Codex CLI's loader actually behaves

From the official Codex CLI skills documentation (https://developers.openai.com/codex/skills):

• Skills build on the agentskills.io open agent skills standard.
• Documented top-level frontmatter fields: name, description (both required).
• Discovery paths (in order): project-local .agents/skills/ (walked from cwd up to repo root), user-level ~/.agents/skills/, admin-level /etc/codex/skills/, plus bundled skills.
• Codex CLI follows symlinked skill folders during discovery.
• A skill lives at <dir>/SKILL.md; sibling resources are loaded on demand per agentskills.io v1.

In observed practice on this machine, Codex CLI also discovers skills under ~/.codex/skills/. That path is not enumerated in the public skills documentation. This kit defaults to the documented ~/.agents/skills/ path; if your tree uses ~/.codex/skills/ instead, edit install.sh accordingly.

What MDA emits today (v1.0)

The SKILL.md schema (schemas/frontmatter-skill-md.schema.json) permits these top-level fields, exactly:

Field	Source	Notes
name	author	Required by MDA. Must equal directory name (spec §06-2.1).
description	author	Required by MDA. Required by Codex CLI per docs.
license	author	Optional. Plain agentskills.io v1.
compatibility	author	Optional. Plain agentskills.io v1.
allowed-tools	author	Optional. Plain agentskills.io v1 (experimental upstream).
metadata	author	Optional. metadata.mda.* for MDA extensions, metadata.<vendor>.* reserved for vendor namespaces. Codex CLI does not document reading this namespace today.
integrity	compiler	Optional. Content digest. Codex CLI does not verify.
signatures	compiler/signer	Optional. DSSE envelope. Codex CLI does not verify.

Everything else is rejected by unevaluatedProperties: false.

What MDA does NOT emit today

The Codex CLI public docs do not enumerate top-level fields beyond name and description, so MDA's envelope subset matches the documented surface. One non-standard field observed in the wild (a triggers: array in at least one shipped Codex skill) is not part of agentskills.io v1 and is not authored by MDA v1.0. If Codex CLI adopts further runtime-specific top-level fields (the way Claude Code documents 11 extras), the same v1.1 graduation criterion in docs/v1.0/what-v1.0-does-not-ship.md covers them.

What this kit does NOT claim

• That Codex CLI parses MDA-extended frontmatter (metadata.mda.*, metadata.codex.*, etc.).
• That signed MDA artifacts are verified at load time by Codex CLI.
• That ~/.agents/skills/<name>/SKILL.md is the only discovery path Codex CLI uses. Project-local .agents/skills/<name>/SKILL.md works the same way; this kit just defaults to user-global for convenience.
• That the AGENTS.md target (a separate MDA-emitted file Codex CLI also reads as instructions) is verified by this kit. That belongs in a sibling AGENTS.md compat kit, not here.

Anything stronger belongs in a future Tier-C section, behind explicit runtime opt-in to MDA extensions.