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.
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
- OpenAI Codex Skills
- OpenAI Codex Plugins
- OpenAI Codex Hooks
- OpenAI AGENTS.md guide
- AGENTS.md standard
- Better Plugins examples