agent-development

troykelly 的头像作者 troykelly

用于设计Codex代理等效体(专用工作者/配置文件/提示文件)、定义触发条件或构建可重用代理提示和验证工具。

📖 中文导读:用于设计Codex代理等效体(专用工作者/配置文件/提示文件)、定义触发条件或构建可重用代理提示和验证工具。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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