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:

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)

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:

By exit_code (when status is error):

Parameters

*Required when not using --list

Agent Definition Location

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.

CLI Selection Priority

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

Common Mistakes