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

### Step 3: Update the Command

Remove execution logic, add subagent dispatch:

**Before (inline execution):**
```markdown
### Step 4: Send Message
mcp__teams__send_chat_message with:
- chatId: ...

After (dispatch to subagent):

### Step 4: Dispatch Subagent

When user confirms, dispatch the `{subagent_name}` subagent:

Task tool:
  subagent_type: "{subagent_name}"
  prompt: |
    {Action}:
    - Field1: {value1}
    - Field2: {value2}

### Step 5: Show Result

Display the subagent's response:
- On success: ✅ {success message}
- On error: ❌ {error message}

Step 4: Register in Recipe

Add to recipes.yml:

# Subagent recipe (what the subagent gets loaded with)
{subagent-name}:
  description: "{Action} (subagent execution)"
  files:
    - /path/to/agents/{name}.md
    - /path/to/common.md
    - /path/to/accounts.md  # if needed
  mcp_servers:
    - {required-mcp}

# Parent recipes that use the command
{parent-recipe}:
  files:
    - /path/to/commands/{name}.md
  subagents:
    - name: {subagent_name}  # underscores for Task tool
      recipe: {subagent-name}  # hyphens for recipe name

Step 5: Sync Config Files

cp recipes.yml ~/.config/ruly/recipes.yml
cp recipes.yml ~/Projects/chezmoi/config/ruly/recipes.yml

Example: MS Teams DM

Before: dm.md had all Teams MCP logic inline

After:

• commands/dm.md - Preview workflow, dispatches on "send it"
• agents/ms-teams-dm.md - Teams MCP execution

Recipe registration:

ms-teams-dm:
  files:
    - rules/comms/ms-teams/agents/ms-teams-dm.md
    - rules/comms/ms-teams/common.md
  mcp_servers:
    - teams

comms:
  files:
    - rules/comms/ms-teams/commands/dm.md
  subagents:
    - name: ms_teams_dm
      recipe: ms-teams-dm

Common Mistakes

| Mistake | Fix | |---------|-----| | Subagent asks questions | Add "EXECUTION REQUIRED" header, forbid questions | | Subagent returns without acting | Add "0 tool uses = FAILED" warning | | Missing MCP server in recipe | Subagent can't call APIs without mcp_servers | | Forgot to sync config files | Always sync to ~/.config/ruly/ and chezmoi | | Using wrong name format | Recipe names: hyphens. Task tool names: underscores |

Directory Convention

rules/{domain}/
├── common.md           # Shared patterns
├── commands/
│   └── {name}.md       # User-facing command
└── agents/
    └── {name}.md       # Subagent execution

• commands/ = User-invocable via /command-name
• agents/ = Dispatched programmatically (not user-invocable)