Sub-Agents - External CLI AI Task Delegation

Spawns external CLI AIs (codex, claude, cursor-agent, glm, kimi, grok, antigravity, gemini, opencode, command-code) as isolated sub-agents with dedicated context.

Workflow: discover available definitions, select one from the user request, execute it, and handle the JSON response.

Resources

• [runsubagent.py](scripts/runsubagent.py) - Main execution script
• [codex.md](references/codex.md) - Read before first execution from Codex; covers permissions and timeout

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

Interpreting User Requests

Extract parameters from user's natural language request:

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](references/codex.md) for exact JSON parameter format.

Workflow

Step 1: List Available Agents

Always list agents first to discover available definitions:

{SKILL_DIR}/scripts/run_subagent.py --list

Output:

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

When the user provides an agent name, select it if it appears in the result. If it is absent, report the available definitions and wait for a selection. When the result is empty, provide the Agent Definition Format below and wait for the user to add a definition.

When the user leaves the agent selection open:

Step 2: Execute Agent

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

Append --cli <backend> when the user specifies a backend. Append --timeout <milliseconds> when the user specifies a timeout.

Step 3: Handle Response

Parse JSON output and check status field:

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

By status:

For configuration or credential errors, retry after the required external configuration has changed.

If execution fails because run-agent is missing, retry with --cli set to the current client's backend.

By exit_code (when status is error):

Agent Definition Location

To customize: export SUBAGENTSDIR=/custom/path

Agent Definition Format

Place .md files in .agents/ directory:

---
run-agent: claude
model: sonnet
permission: safe-edit
---

# Agent Name

Brief description of agent's purpose.

## Task
What this agent does.

## Output Format
How results should be structured.

run-agent supplies the backend. Pass --cli only as an explicit one-run override; execution fails with a corrective error when neither is specified.

Frontmatter fields: