sub-agents
/sub-agents
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.
- Author
- opencue ↗
- Repository
- cuecards ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/run_subagent.py
What it does and when to use it
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.
Original author 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.
How it works
- Resources
- CLI-Specific Notes
- Interpreting User Requests
- When to Use This Skill
- Important: Permission and Timeout
- Workflow
- Parameters
- Agent Definition Location
- Agent Definition Format
- CLI Selection Priority
SKILL.md preview
---
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 (Codex, cursor-agent, codex, gemini) as isolated sub-agents with dedicated context.
## Resources
- **[run_subagent.py](scripts/run_subagent.py)** - Main execution script
- **[codex.md](references/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](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](#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](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](references/codex.md) first.
### Step 1: List Available Agents
**Always list agents first** to discover available definitions:
```bash
scripts/run_subagent.py --list
```
Output:
```json
{"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](#agent-definition-format))
3. Re-run `--list` to verify
### Step 2: Execute Agent
```bash
scripts/run_subagent.py \
--agent <name> \
--prompt "<task>" \
--cwd <absolute-path>
```
### Step 3: Handle Response
Parse JSON output and check `status` field:
```json
{"result": "...", "exit_code": 0, "status": "success", "cli": "Codex"}
```
**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 (Codex, 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: `Codex`, `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:
```markdown
---
run-agent: Codex
---
# 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](references/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 |
Files in this package (4)
- SKILL.md 6 KB
- references/codex.md 2 KB
- scripts/agents_sub_skills_1.2.zip 503 KB
- scripts/run_subagent.py 15 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · opencue/cuecards | 100 | MIT |
| opencue/cuecards | 100 | MIT |
Database snapshot: 13.11.2026 · package version 5e0cc688cd9f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100sub-agents-patterns
Sub-agent patterns for parallel and complex tasks. Use when splitting work across Explore/Plan/general-purpose sub-agents or running independent investigations in parallel. - 100subagent-cli
A skill for non-interactively executing external AI agent CLIs in Bash. Provides procedures for delegating coding work via codex exec or cursor-agent. Use when: Use when: delegating complex implementations, code reviews, multi-file batch changes, or launching sub-agents from Bash. - 100create-subagent
Generates single-purpose Claude Code sub-agents for use via the Task tool. Use when creating dedicated sub-agents, scaffolding agent definitions, or generating agents with diagnostics and permissions setup. - 100subagent-creator
Create specialized Claude Code sub-agents with custom system prompts and tool configurations. Use when users ask to create a new sub-agent, custom agent, specialized assistant, or want to configure task-specific AI workflows for Claude Code. - 100subagent-delegation
How to scope, brief and choose sub-agents when delegating work with the Agent tool - named vs forked agents, file ownership boundaries, model selection, and when a fork is the wrong choice. Use when delegating to one or more sub-agents, deciding between a named agent and a fork,… - 100sub-agent-delegation
Delegate work to subagents in the Claude Agent SDK: define them with the agents option (AgentDefinition), restrict their tools, pass the right context in the Agent tool prompt, detect subagent messages, resume subagents, and cap depth, concurrency, and spend. Use this skill when…