sub-agents

name	sub-agents
description	Execute external CLI AIs as isolated sub-agents for task delegation, parallel processing, and context separation. Use when delegating complex multi-step tasks, running parallel investigations, needing fresh context without current conversation history, or leveraging specialized agent definitions. Returns structured JSON with agent output, exit code, and execution status.
allowed-tools	Bash Read

Sub-Agents - External CLI AI Task Delegation

Spawns external CLI AIs (claude, cursor-agent, codex, gemini) as isolated sub-agents with dedicated context.

Resources

• run_subagent.py - Main execution script
• codex.md - Codex-specific setup (permissions, timeout)

Script Path: Use absolute path {SKILL_DIR}/scripts/run_subagent.py where {SKILL_DIR} is the directory containing this SKILL.md file.

CLI-Specific Notes

Check the corresponding reference for your environment:

• Codex: Read references/codex.md BEFORE first execution

Interpreting User Requests

Extract parameters from user's natural language request:

Parameter	Source
--agent	Agent name from user request (see selection rules below)
--prompt	Task instruction part (excluding agent specification)
--cwd	Current working directory (absolute path)

Agent Selection Rules (when user doesn't specify agent name):

1. Run --list to get available agents
2. 0 agents: Inform user no agents available, show setup instructions (see Agent Definition Format)
3. 1 agent: Auto-select without asking
4. 2+ agents: Show list with descriptions, ask user to choose

Example: "Run code-reviewer on src/" → --agent code-reviewer --prompt "Review src/" --cwd $(pwd)

When to Use This Skill

Use sub-agent when ANY of these apply:

• Complex multi-step task (isolated context prevents interference)
• Parallel investigation (multiple agents can run simultaneously)
• Task needs fresh context (sub-agent starts without conversation history)
• Specialized agent definition exists (leverage pre-defined expert prompts)

Important: Permission and Timeout

This script executes external CLIs that require elevated permissions.

Before first execution:

1. Request elevated permissions via your CLI's tool parameters
2. Set tool timeout to match --timeout argument (default: 600000ms)

For Codex CLI (most common permission issues): See references/codex.md for exact JSON parameter format.

Workflow

Step 0: Read CLI-Specific Setup (if applicable)

If you are running on Codex, read references/codex.md first.

Step 1: List Available Agents

Always list agents first to discover available definitions:

scripts/run_subagent.py --list

Output:

{"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}

If agents list is empty:

1. Create {cwd}/.agents/ directory
2. Add agent definition file (see Agent Definition Format)
3. Re-run --list to verify

Step 2: Execute Agent

scripts/run_subagent.py \
  --agent <name> \
  --prompt "<task>" \
  --cwd <absolute-path>

Step 3: Handle Response

Parse JSON output and check status field:

{"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}

By status:

status	Meaning	Action
success	Task completed	Use result directly
partial	Timeout but has output	Review partial result, may need retry
error	Execution failed	Check error field and exit_code, fix and retry

By exit_code (when status is error):

exit_code	Meaning	Resolution
0	Success	-
124	Timeout	Increase --timeout or simplify task
127	CLI not found	Install required CLI (claude, codex, etc.)
1	General error	Check error field in response

Parameters

Parameter	Required	Description
--list	-	List available agents (no other params needed)
--agent	Yes*	Agent definition name from --list
--prompt	Yes*	Task description to delegate
--cwd	Yes*	Working directory (absolute path)
--timeout	No	Timeout ms (default: 600000)
--cli	No	Force CLI: claude, cursor-agent, codex, gemini

*Required when not using --list

Agent Definition Location

Priority	Source	Path
1	Environment variable	$SUB_AGENTS_DIR
2	Default	{cwd}/.agents/

To customize: export SUB_AGENTS_DIR=/custom/path

Agent Definition Format

Place .md files in .agents/ directory:

---
run-agent: claude
---

# Agent Name

Brief description of agent's purpose.

## Task
What this agent does.

## Output Format
How results should be structured.

Critical: The run-agent frontmatter determines which CLI executes the agent. See cli-formats.md for CLI-specific behaviors.

CLI Selection Priority

1. --cli argument (explicit override)
2. Agent definition run-agent frontmatter
3. Auto-detect caller environment
4. Default: codex

Common Mistakes

Mistake	Result	Fix
Skip --list before execution	Agent not found error	Always run --list first
Use relative path for --cwd	Validation fails	Use absolute path
Ignore status field in response	Undetected errors	Always check status before using result
Very long prompts	May exceed CLI limits	Break into smaller tasks