Codex Primitive Field Guide
AGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.
Skills use progressive disclosure to manage context efficiently.OpenAI Codex Skills docs
Use this when a workflow keeps failing because instructions, tools, and enforcement are all living in the same prompt.
| Primitive | Use when | Codex does | 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.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 agents can follow
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