shinpr/sub-agents

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)

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
permission: safe-edit
---

# 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.

Frontmatter fields:

| Field | Values | Description | |-------|--------|-------------| | run-agent | codex, claude, cursor-agent, gemini | Which CLI executes this agent | | permission | read-only, safe-edit (default), yolo | Approval/sandbox level the sub-agent runs with |

permission levels (mapped per-CLI by the skill):

• read-only — investigation only, no edits/writes
• safe-edit — auto-approve edits in workspace, suppress prompts (default)
• yolo — bypass all approvals and sandboxing

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 |