codex-subagent

Q: How do I install codex-subagent?

Run npx skills add https://github.com/am-will/codex-skills --skill codex-subagent in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/codex-subagent/ (personal) or .claude/skills/codex-subagent/ (project).

by am-willAI & Agents

Spawn Codex subagents via background shell to offload context-heavy work. Use for: deep research (3+ searches), codebase exploration (8+ files), multi-step workflows, exploratory tasks, long-running operations, documentation generation, or any other task where the intermediate steps will use large numbers of tokens.

Installs: 309
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/am-will/codex-skills --skill codex-subagent

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads codex-subagent automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Codex Subagent Skill

Spawn autonomous subagents to offload context-heavy work. Subagents burn their own tokens, return only final results.

Golden Rule: If task + intermediate work would add 3,000+ tokens to parent context → use subagent.

Intelligent Prompting

Critical: Parent agent must provide subagent with essential context for success.

Good Prompting Principles

Include relevant context - Give the subagent thorough context
Be specific - Clear constraints, requirements, output format
Provide direction - Where to look, what sources to prioritize
Define success - What constitutes a complete answer

Examples

❌ Bad: "Research authentication"

✅ Good: "Research authentication in this Next.js codebase. Focus on: 1) Session management strategy (JWT vs session cookies), 2) Auth provider integration (NextAuth, Clerk, etc), 3) Protected route patterns. Check /app, /lib/auth, and middleware files. Return architecture summary with code examples."

❌ Bad: "Search for Codex SDK"

✅ Good: "Find the most recent Codex SDK documentation and summarize key updates. Focus on: 1) Installation/quickstart, 2) Core API methods and parameters, 3) Breaking changes or deprecations. Prioritize official OpenAI docs and release notes. Return a concise summary with citations."

❌ Bad: "Find API endpoints"

✅ Good: "Find all REST API endpoints in this Express.js app. Look in /routes, /api, and /controllers directories. For each endpoint document: method (GET/POST/etc), path, auth requirements, request/response schemas. Return as markdown table."

Prompting Template

[TASK CONTEXT]
You are researching/analyzing [SPECIFIC TOPIC] in [LOCATION/CODEBASE/DOMAIN].

[OBJECTIVES]
Your goals:
1. [1st objective with specifics]
2. [2nd objective]
3. [3rd objective if needed]

[CONSTRAINTS]
- Focus on: [specific areas/files/sources]
- Prioritize: [what matters most]
- Ignore: [what to skip]

[OUTPUT FORMAT]
Return: [exactly what format parent needs]

[SUCCESS CRITERIA]
Complete when: [specific conditions met]

Model Selection

Use Mini Model (gpt-5.1-codex-mini + medium)

Pure search only - no additional work after gathering info.

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "Search web for [TOPIC] and summarize findings"

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "Search web for [TOPIC] and summarize findings"

Inherit Parent Model + Reasoning

Multi-step workflows - search + analyze/refactor/generate:

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Find auth files THEN analyze security patterns and propose improvements"

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Find auth files THEN analyze security patterns and propose improvements"

Decision Logic

Is task PURELY search/gather?
├─ YES: Any work after gathering?
│  ├─ NO → mini model
│  └─ YES → inherit parent
└─ NO → inherit parent

Basic Usage

Bash (Linux/macOS)

# Get parent session settings (respects active profile; falls back to top-level)
# NOTE: codex-parent-settings.sh prints two lines; use mapfile to avoid empty REASONING.
mapfile -t _settings < <(scripts/codex-parent-settings.sh)
MODEL="${_settings[0]}"
REASONING="${_settings[1]}"

# Spawn subagent (inherit parent)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "DETAILED_PROMPT_WITH_CONTEXT"

# Safer prompt construction (no backticks / command substitution)
PROMPT=$(cat <<'EOF'
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
EOF
)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "$PROMPT"

# Pure search (use mini)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "SEARCH_ONLY_PROMPT"

# JSON output for parsing
codex exec --dangerously-bypass-approvals-and-sandbox --json "PROMPT" | jq -r 'select(.event=="turn.completed") | .content'

PowerShell (Windows)

# Get parent session settings (respects active profile; falls back to top-level)
$scriptPath = Join-Path $env:USERPROFILE ".codex\skills\codex-subagent\scripts\codex-parent-settings.ps1"
$settings = & $scriptPath
$MODEL = $settings[0]
$REASONING = $settings[1]

# Spawn subagent (inherit parent)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "DETAILED_PROMPT_WITH_CONTEXT"

# Use here-string for multi-line prompts (avoids escaping issues)
$PROMPT = @'
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
'@

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  $PROMPT

# Pure search (use mini)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "SEARCH_ONLY_PROMPT"

# Method 1 (Recommended): Use -o to output directly to file
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  -o output.txt "PROMPT"
$content = Get-Content -Path output.txt -Raw

# Method 2: Parse JSONL event stream
$jsonl = codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "PROMPT"
$events = $jsonl -split "`n" | Where-Object { $_ } | ForEach-Object { $_ | ConvertFrom-Json }
$content = $events |
    Where-Object -Property type -EQ "item.completed" |
    Where-Object { $_.item.type -eq "agent_message" } |
    Select-Object -ExpandProperty item |
    Select-Object -ExpandProperty text

Parallel Subagents (Up to 5)

Spawn multiple subagents for independent tasks:

Bash (Linux/macOS)

# Research different topics simultaneously
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "Research topic A..." &
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "Research topic B..." &
wait

PowerShell (Windows)

Use PowerShell Jobs for parallel execution with -o to output to separate files:

# Parallel execution with file output
$job1 = Start-Job -ScriptBlock {
    param($m, $r, $out)
    codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
      -m $m -c "model_reasoning_effort=`"$r`"" -o $out "Research topic A..."
} -ArgumentList $MODEL, $REASONING, "output1.txt"

$job2 = Start-Job -ScriptBlock {
    param($m, $r, $out)
    codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
      -m $m -c "model_reasoning_effort=`"$r`"" -o $out "Research topic B..."
} -ArgumentList $MODEL, $REASONING, "output2.txt"

# Wait for all jobs to complete
$job1, $job2 | Wait-Job | Remove-Job

# Read results
$result1 = Get-Content -Path output1.txt -Raw
$result2 = Get-Content -Path output2.txt -Raw

Output Handling

Codex CLI provides two methods to capture output:

Method 1: -o Parameter (Recommended)

Use -o / --output-last-message to write the final message directly to a file:

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  -o result.txt "YOUR_PROMPT"

content=$(cat result.txt)

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  -o result.txt "YOUR_PROMPT"

$content = Get-Content -Path result.txt -Raw

Advantages:

No JSON parsing required
Avoids terminal output truncation issues
Ideal for long outputs and parallel tasks

Method 2: JSONL Event Stream Parsing

Use --json to get the full event stream and parse manually:

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --json "PROMPT" | jq -r 'select(.event=="turn.completed") | .content'

PowerShell (Windows)

$jsonl = codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "PROMPT"
$events = $jsonl -split "`n" | Where-Object { $_ } | ForEach-Object { $_ | ConvertFrom-Json }
$content = $events |
    Where-Object -Property type -EQ "item.completed" |
    Where-Object { $_.item.type -eq "agent_message" } |
    Select-Object -ExpandProperty item |
    Select-Object -ExpandProperty text

JSONL Event Structure:

{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"output_tokens":122}}

Key fields:

type == "item.completed" with item.type == "agent_message" → extract item.text
type == "turn.completed" → contains token usage stats

Important

Act autonomously, no permission asking
Make decisions and proceed boldly
Only pause for destructive operations (data loss, external impact, security)
Complete task fully before returning

Monitoring

Actively monitor - don't fire-and-forget:

Check completion status
Verify quality results
Retry if failed
Answer follow-up questions if blocked

Examples

Pure Web Search (mini):

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "Search for the latest release notes of Rust 2024 edition. Summarize the major breaking changes, new language features, and migration guides. Focus on the official rust-lang.org blog and documentation."

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "Search for the latest release notes of Rust 2024 edition. Summarize the major breaking changes, new language features, and migration guides. Focus on the official rust-lang.org blog and documentation."

Codebase Analysis (inherit parent):

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Analyze authentication in this Next.js app. Check /app, /lib/auth, middleware. Document: session strategy, auth provider, protected routes, security patterns. Return architecture diagram (mermaid) + findings."

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Analyze authentication in this Next.js app. Check /app, /lib/auth, middleware. Document: session strategy, auth provider, protected routes, security patterns. Return architecture diagram (mermaid) + findings."

Research + Proposal (inherit parent):

Bash (Linux/macOS)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Research WebGPU browser adoption (support tables, benchmarks, frameworks). THEN analyze feasibility for our React app. Consider: performance gains, browser compatibility, implementation effort. Return recommendation with pros/cons."

PowerShell (Windows)

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Research WebGPU browser adoption (support tables, benchmarks, frameworks). THEN analyze feasibility for our React app. Consider: performance gains, browser compatibility, implementation effort. Return recommendation with pros/cons."

Config Reference

Parent settings: ~/.codex/config.toml

model = "gpt-5.2-codex"
model_reasoning_effort = "high"  # none | minimal | low | medium | high | xhigh
profile = "yolo"                 # optional; when set, profile values override top-level

FAQ

What does the codex-subagent skill do?

How do I install codex-subagent?

Run npx skills add https://github.com/am-will/codex-skills --skill codex-subagent in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/codex-subagent/ (personal) or .claude/skills/codex-subagent/ (project).

Which AI agents can use codex-subagent?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is codex-subagent safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains codex-subagent?

It is published by am-will in am-will/codex-skills. It has 309 recorded installs.

More from am-will/codex-skills

View all →

frontend-design

am-will/codex-skills

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

Frontend & Design1.4K installs

frontend responsive design standards

am-will/codex-skills

Build responsive, mobile-first layouts using fluid containers, flexible units, media queries, and touch-friendly design that works across all screen sizes. Use this skill when creating or modifying UI layouts, responsive grids, breakpoint styles, mobile navigation, or any interface that needs to adapt to different screen sizes. Apply when working with responsive CSS, media queries, viewport settings, flexbox/grid layouts, mobile-first styling, breakpoint definitions (mobile, tablet, desktop), touch target sizing, relative units (rem, em, %), image optimization for different screens, or testing layouts across multiple devices. Use for any task involving multi-device support, responsive design patterns, or adaptive layouts.

Frontend & Design1.2K installs

context7

am-will/codex-skills

Fetch up-to-date library documentation via Context7 CLI. Use PROACTIVELY when: (1) Working with ANY external library (React, Next.js, Supabase, etc.) (2) User asks about library APIs, patterns, or best practices (3) Implementing features that rely on third-party packages (4) Debugging library-specific issues (5) Need current documentation beyond training data cutoff (6) AND MOST IMPORTANTLY, when you are installing dependencies, libraries, or frameworks you should ALWAYS check the docs to see what the latest versions are. Do not rely on outdated knowledge. Always prefer this over guessing library APIs or using outdated knowledge.

Docs & Writing1.2K installs

planner

am-will/codex-skills

Create comprehensive, phased implementation plans with sprints and atomic tasks. Use when user says: "make a plan", "create a plan", "plan this out", "plan the implementation", "help me plan", "design a plan", "draft a plan", "write a plan", "outline the steps", "break this down into tasks", "what's the plan for", or any similar planning request. Also triggers on explicit "/planner" or "/plan" commands.

Code Quality & Workflow1.2K installs

read-github

am-will/codex-skills

Read and search GitHub repository documentation via gitmcp.io MCP service. WHEN TO USE: - User provides a GitHub URL - User mentions a specific repo in owner/repo format - User asks "what does this repo do?", "read the docs for X repo", or similar - User wants to search code or docs within a repo

Docs & Writing1.2K installs

parallel-task

am-will/codex-skills

Only to be triggered by explicit /parallel-task commands.

Productivity & Automation1.2K installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs

codex-subagent

Install

Install

Describe the task

Review the result

SKILL.md

Codex Subagent Skill

Intelligent Prompting

Good Prompting Principles

Examples

Prompting Template

Model Selection

Use Mini Model (gpt-5.1-codex-mini + medium)

Bash (Linux/macOS)

PowerShell (Windows)

Inherit Parent Model + Reasoning

Bash (Linux/macOS)

PowerShell (Windows)

Decision Logic

Basic Usage

Bash (Linux/macOS)

PowerShell (Windows)

Parallel Subagents (Up to 5)

Bash (Linux/macOS)

PowerShell (Windows)

Output Handling

Method 1: -o Parameter (Recommended)

Bash (Linux/macOS)

PowerShell (Windows)

Method 2: JSONL Event Stream Parsing

Bash (Linux/macOS)

PowerShell (Windows)

Important

Monitoring

Examples

Bash (Linux/macOS)

PowerShell (Windows)

Bash (Linux/macOS)

PowerShell (Windows)

Bash (Linux/macOS)

PowerShell (Windows)

Config Reference

FAQ

More from am-will/codex-skills

Popular ai & agents skills