---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-codex-primitives-field-guide"
title: "Codex Primitive Field Guide"
---

# Codex Primitive Field Guide

> 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](https://developers.openai.com/codex/skills)

## 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

```text
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

- [OpenAI Codex Skills](https://developers.openai.com/codex/skills)
- [OpenAI Codex Plugins](https://developers.openai.com/codex/plugins)
- [OpenAI Codex Hooks](https://developers.openai.com/codex/hooks)
- [OpenAI AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)
- [AGENTS.md standard](https://agents.md/)
- [Better Plugins examples](https://github.com/johnlindquist/better-plugins/tree/main/plugins)

## Related principles

- [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)
- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)

## Original references

- [Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-07.html)
- [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html)
