agent-development

name	agent-development
description	Use when the user wants to design Codex agent equivalents (specialized workers/profiles/prompt files), define triggering conditions, or build reusable agent prompts and validation tools.

Agent Development (Codex)

Overview

Codex CLI does not auto-discover "agent" files the way Claude plugins do. To recreate agent behavior in Codex, combine:

• Prompt files that define the agent's role and workflow.
• Codex config profiles to set model/sandbox/approval defaults.
• Skills that describe when to use the agent and how to launch it.
• Worker processes (codex-subagent, codex exec, or worker-dispatch) for isolated execution.

This skill standardizes an agent card format (YAML frontmatter + prompt body) and shows how to run it with Codex.

Agent Card Format (Codex Convention)

Store agent prompts in agents/<agent-name>.md. Frontmatter is metadata for humans and validators; Codex does not read it automatically.

Required fields:

• name (kebab-case identifier)
• description (when to use this agent)

Recommended fields:

• profile (Codex config profile name)
• model (override model)
• sandbox_mode and approval_policy (safety defaults)
• tools (advisory list of tools; use sandbox/approval to enforce)

Example:

---
name: pr-reviewer
description: Use this agent when the user asks for a code review or to audit a pull request.
profile: review-worker
model: gpt-5.2-codex
sandbox_mode: workspace-write
approval_policy: on-request
tools: ["Read", "Grep", "Bash"]
---

You are a senior PR reviewer...

Running an Agent

Preferred (subagent runner):

codex-subagent pr-reviewer <<'EOF'
[Provide task context and scope here.]
EOF

Fallback (manual codex exec):

awk 'BEGIN{c=0} /^---$/{c++; next} c>=2 {print}' agents/pr-reviewer.md | codex exec -p review-worker -

Profiles as Agent Defaults

Define per-agent profiles in ~/.codex/config.toml:

[profiles.review-worker]
model = "gpt-5.2-codex"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Profiles capture the model and safety settings that Claude agents used to embed in frontmatter.

Triggering (Codex Equivalent)

To make agent usage automatic, create a skill describing the trigger and invocation. The skill body should instruct how to run the agent card or spawn a worker.

Example trigger entry:

description: Use when the user asks for a PR review or code audit; run the pr-reviewer agent card.

See references/triggering-examples.md.

Validation

Use scripts/validate-agent.sh to validate agent cards for required fields and prompt length.

References

• references/system-prompt-design.md for prompt structure
• references/triggering-examples.md for trigger phrasing
• references/agent-creation-system-prompt.md for AI-assisted agent card generation
• examples/agent-creation-prompt.md for a complete prompt template
• examples/complete-agent-examples.md for full agent card examples