command-to-subagent

Converting Commands to Subagents

Overview

Extract execution logic from a command into a dedicated subagent, keeping only the user-facing workflow (preview, confirmation) in the command. This reduces recipe context by isolating API/MCP complexity.

When to Use

• Command has heavy MCP or API call logic
• Want to reduce token usage in a recipe
• Need to isolate execution complexity from user workflow
• Command follows preview → confirm → execute pattern

Quick Reference

Component	Location	Contains
Command	commands/{name}.md	User workflow (preview, confirm, dispatch)
Subagent	agents/{name}.md	Execution logic (MCP calls, API operations)
Recipe	recipes.yml	Subagent registration

Conversion Steps

Step 1: Identify the Split Point

Find where user interaction ends and execution begins:

User workflow (COMMAND):     Execution (SUBAGENT):
├─ Parse input               ├─ API/MCP calls
├─ Validate/lookup           ├─ Error handling
├─ Show preview              ├─ Response formatting
├─ Handle revisions          └─ Return structured result
└─ Dispatch on confirm

Split at confirmation - everything after "send it" / "post it" goes to subagent.

Step 2: Create the Subagent File

Location: rules/{domain}/agents/{name}.md

Structure:

---
description: Instructions for the {name} subagent when dispatched
alwaysApply: true
requires:
  - ../common.md        # Shared patterns
  - ../../accounts.md   # If needs user lookups
---
# {Name} Subagent - EXECUTION REQUIRED

## ⚠️ CRITICAL: You MUST Execute

**Your ONLY job is to {action}.** If you complete with "0 tool uses", you have FAILED.

## Input Format

You will receive a prompt like:
{show expected input structure}

## Execution Steps

### Step 1: {First action}
{MCP/API call with example}

### Step 2: {Next action}
...

### Step N: Return Result

**On success:**
```json
{"status": "success", "field": "value"}

On error:

{"status": "error", "error": "message", "step": "which failed"}

Failure Conditions

❌ FAILED if you:

• Complete with "0 tool uses"
• Return without executing
• Ask clarifying questions

✅ SUCCESS if you:

• Execute all required steps
• Return structured result