# Sub Agent Patterns

> Sub-Agent Patterns Skill

- Skill: `mmcmedia/sub-agent-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mmcmedia/sub-agent-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mmcmedia/sub-agent-patterns/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: mmcmedia (https://skillmd.com/u/mmcmedia)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/mmcmedia/sub-agent-patterns

---

# Sub-Agent Patterns Skill

Best practices for spawning and managing sub-agents via `sessions_spawn`.

## When to Use

- Task will take >30 minutes
- Need parallel work streams
- Complex coding/building tasks
- Overnight autonomous work
- Want to avoid context pollution in main session

## Agent Routing

**Choose the right agent for the task:**

| Task Type | Agent | Why |
|-----------|-------|-----|
| Simple file edits, quick lookups | `haiku` | Fast, cheap |
| Standard work, research, docs | `sonnet` | Good balance |
| Complex coding, multi-file changes | `codex` | Specialized, uses reasoning |
| Strategic/multi-domain analysis | `opus` | Most capable (expensive, use sparingly) |

**Default:** `sonnet` unless specific reason for another.

**Overnight dev builds:** Always use `codex` - won't get distracted.

## Spawn Template

```javascript
sessions_spawn({
  agentId: 'codex',  // or haiku, sonnet, opus
  task: `[CONTEXT]
  Brief background on what this is for.
  
  [TASK]
  Specific deliverable(s) expected.
  
  [SUCCESS CRITERIA]
  - Criterion 1
  - Criterion 2
  
  [FILES TO CREATE/MODIFY]
  - /path/to/file1
  - /path/to/file2
  
  [WHEN COMPLETE]
  Use sessions_send to main session with:
  '✅ [task name] complete. Files: [list]. Ready for QA.'
  
  [IF BLOCKED]
  Use sessions_send to main session with:
  '❌ [task name] blocked: [reason]. Need: [what you need]'`,
  label: 'descriptive-label',
  runTimeoutSeconds: 7200  // 2 hours, adjust as needed
})
```

## Always Log Spawns

**Log to:** `/projects/subagent-tracking/SPAWN-LOG.md`

Entry format:
```markdown
## YYYY-MM-DD HH:MM - [label]
- **Agent:** codex/sonnet/haiku/opus
- **Task:** Brief description
- **Status:** SPAWNED / RUNNING / COMPLETED / FAILED
- **Session Key:** [from spawn response]
- **Notes:** [any issues or outcomes]
```

## Monitoring Sub-Agents

### Check Status
```javascript
sessions_list({ kinds: ['spawn'], activeMinutes: 120 })
```

### Get History
```javascript
sessions_history({ sessionKey: 'the-session-key', limit: 20 })
```

### Send Message
```javascript
sessions_send({ sessionKey: 'the-session-key', message: 'Status update?' })
```

## Common Patterns

### 1. Overnight Build

```javascript
// Before McKinzie sleeps
sessions_spawn({
  agentId: 'codex',
  task: `Build [feature] for [project].
  
  Requirements:
  - [req 1]
  - [req 2]
  
  Start from: /projects/[project]/
  
  When done, update SESSION_STATE.md with completion status
  and use sessions_send to notify main session.`,
  label: 'overnight-feature-build',
  runTimeoutSeconds: 14400  // 4 hours
})
```

### 2. Research Task

```javascript
sessions_spawn({
  agentId: 'sonnet',
  task: `Research [topic] for McKinzie.
  
  Sources to check:
  - [source 1]
  - [source 2]
  
  Output: Create /projects/[project]/research/[topic].md
  
  Include: Executive summary, key findings, recommendations.`,
  label: 'research-[topic]',
  runTimeoutSeconds: 3600
})
```

### 3. Quick Parallel Task

```javascript
// When you need something done while continuing main work
sessions_spawn({
  agentId: 'haiku',
  task: `Update [file] with [specific change].
  
  Just do this one thing and confirm when done.`,
  label: 'quick-edit',
  runTimeoutSeconds: 600
})
```

## Sub-Agent Rules

### DO:
- Give complete context (sub-agent has no memory of main session)
- Specify exact deliverables
- Include file paths
- Set appropriate timeout
- Log all spawns to SPAWN-LOG.md
- Check on long-running agents periodically

### DON'T:
- Assume sub-agent knows anything about prior work
- Spawn multiple agents for tightly coupled tasks
- Forget to verify completed work
- Let agents run indefinitely without monitoring

## Verification Checklist

After sub-agent completes:

- [ ] Check the files were actually created/modified
- [ ] Run/test the code if applicable
- [ ] Update SPAWN-LOG.md with completion status
- [ ] Update kanban card if relevant
- [ ] Notify McKinzie if significant

## Watchdog Script

Run periodically to check sub-agent health:
```bash
/Users/mmcassistant/clawd/scripts/subagent-watchdog.sh
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Agent seems stuck | Check `sessions_history` for errors |
| Agent finished but no output | Verify file paths were correct |
| Agent keeps asking questions | Give more context in initial task |
| Task too big, keeps timing out | Break into smaller sub-tasks |

## Last Updated

Feb 2, 2026 - Initial skill creation