agent-development

troykelly's avatarfrom troykelly

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.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026
[Prompt Templates and Packaging]

When & Why to Use This Skill

This Claude skill facilitates the design and deployment of specialized Codex agents by standardizing 'agent card' formats. It enables developers to create reusable prompt files with integrated metadata, define precise triggering conditions, and implement validation tools, ensuring a structured and scalable approach to building autonomous AI workers within the Codex ecosystem.

Use Cases

  • Standardizing AI Workflows: Create a library of reusable agent cards (e.g., for code reviews or security audits) with consistent YAML frontmatter for model configurations and safety settings.
  • Automated Agent Execution: Use the codex-subagent runner to trigger specialized workers for isolated tasks, providing clear context and scope through standardized prompt files.
  • Quality Assurance for Prompts: Utilize built-in validation scripts to check agent cards for required metadata fields and optimal prompt length before deployment to ensure consistent performance.
  • Custom Worker Profiles: Define per-agent profiles in configuration files to manage model overrides, sandbox modes, and approval policies for different specialized AI roles.
nameagent-development
descriptionUse 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