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:

code

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:

markdown

---
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:

json

{"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

code


### 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):

markdown

### 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:

yaml

# 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

bash

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:

yaml

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

code

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)