Codex Primitive Field Guide

AGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.

Original source pages and recordings require authorized access. The full article text here is public.

AGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.

Use this when a workflow keeps failing because instructions, tools, and enforcement are all living in the same prompt.

Skills use progressive disclosure to manage context efficiently.

OpenAI Codex Skills docs

Choose the right mechanism

Mechanism Use when Agent responsibility Artifact
AGENTS.md Stable repo or directory rules Setup, commands, conventions, done criteria Short instruction file near the code
Skill Reusable workflow with judgment Browser proof, release notes, Oracle handoff .agents/skills/<name>/SKILL.md
Plugin Shareable installable bundle Team workflow with skills, MCP, apps, hooks .codex-plugin/plugin.json plus bundled folders
Hook Lifecycle enforcement Prompt injection, tool policy, Stop receipt gate hooks/hooks.json plus small scripts
MCP External systems and context Browser, Figma, docs, DB, SaaS tools .mcp.json plus tool policy
Goal mode Long-running objective Research, plan, implement, verify loop .goals/<task>.md plus receipts

Agent-ready prompt

Create a Codex primitive map for this repo.
Read AGENTS.md, package scripts, existing skills/plugins/hooks, and MCP config first.
For each repeated workflow, decide whether it belongs in AGENTS.md, a skill, a plugin, a hook, MCP, or a goal file.
Write .notes/codex-primitives/decision.md with the decision, files to create, verification command, and rollback path.

Applied stories

Next.js monorepo guardrails

Role: Platform lead

Agents keep running the wrong tests and claiming UI work is done without proof.

Agent brief: Ask Codex to create a root AGENTS.md under 120 lines, copy commands from package scripts or CI, and add browser-proof expectations for UI work.

Done when:

  • AGENTS.md exists
  • Commands match real scripts
  • Codex can summarize loaded instructions
  • No one-off task details

Browser proof skill

Role: SaaS frontend engineer

Every UI fix needs the same route, viewport, action, console, screenshot, and command receipt.

Agent brief: Ask Codex to create .agents/skills/browser-proof-saas/SKILL.md with clear trigger and non-trigger language.

Done when:

  • SKILL.md has name/description
  • Proof schema is included
  • Smoke prompt exists
  • Skill says when not to use it

Checkout Stop-hook gate

Role: Checkout owner

Agents stop after one validation fix instead of proving cart to confirmation.

Agent brief: Ask Codex to scaffold a local plugin with a Stop hook that continues until checkout test and browser receipts exist.

Done when:

  • Manifest validates
  • Hook simulator covers missing/success/cap
  • Receipts are named
  • No global install before simulation

Tips and gotchas

  • Keep AGENTS.md short. Put workflow machinery in skills/plugins/hooks.
  • Treat a skill as guidance, not enforcement. Move deterministic checks to hooks.
  • Use current Codex Stop-hook behavior: return decision: "block" with a reason to continue the turn.
  • Installing a plugin does not automatically make plugin hooks trusted. Teach users to review and trust hook definitions.
  • Use MCP for external stateful systems; use local package scripts for repo-local tests and builds.

References

Source references