Skip to content
Skills Library
AI & agents · Automation

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.

Repository
cuecards ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Resources
  2. CLI-Specific Notes
  3. Interpreting User Requests
  4. When to Use This Skill
  5. Important: Permission and Timeout
  6. Workflow
  7. Parameters
  8. Agent Definition Location
  9. Agent Definition Format
  10. CLI Selection Priority
Original SKILL.md headings · 173 lines, 754 words
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

RepositoryScoreLicence
This page · opencue/cuecards100MIT
opencue/cuecards100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.