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

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:

markdown
1---
2description: Instructions for the {name} subagent when dispatched
3alwaysApply: true
4requires:
5  - ../common.md        # Shared patterns
6  - ../../accounts.md   # If needs user lookups
7---
8# {Name} Subagent - EXECUTION REQUIRED
9
10## ⚠️ CRITICAL: You MUST Execute
11
12**Your ONLY job is to {action}.** If you complete with "0 tool uses", you have FAILED.
13
14## Input Format
15
16You will receive a prompt like:
17{show expected input structure}
18
19## Execution Steps
20
21### Step 1: {First action}
22{MCP/API call with example}
23
24### Step 2: {Next action}
25...
26
27### Step N: Return Result
28
29**On success:**
30```json
31{"status": "success", "field": "value"}

On error:

json
1{"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):

markdown
1### Step 4: Dispatch Subagent
2
3When user confirms, dispatch the `{subagent_name}` subagent:
4
5Task tool:
6  subagent_type: "{subagent_name}"
7  prompt: |
8    {Action}:
9    - Field1: {value1}
10    - Field2: {value2}
11
12### Step 5: Show Result
13
14Display the subagent's response:
15- On success: ✅ {success message}
16- On error: ❌ {error message}

Step 4: Register in Recipe

Add to recipes.yml:

yaml
1# Subagent recipe (what the subagent gets loaded with)
2{subagent-name}:
3  description: "{Action} (subagent execution)"
4  files:
5    - /path/to/agents/{name}.md
6    - /path/to/common.md
7    - /path/to/accounts.md  # if needed
8  mcp_servers:
9    - {required-mcp}
10
11# Parent recipes that use the command
12{parent-recipe}:
13  files:
14    - /path/to/commands/{name}.md
15  subagents:
16    - name: {subagent_name}  # underscores for Task tool
17      recipe: {subagent-name}  # hyphens for recipe name

Step 5: Sync Config Files

bash
1cp recipes.yml ~/.config/ruly/recipes.yml
2cp 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
1ms-teams-dm:
2  files:
3    - rules/comms/ms-teams/agents/ms-teams-dm.md
4    - rules/comms/ms-teams/common.md
5  mcp_servers:
6    - teams
7
8comms:
9  files:
10    - rules/comms/ms-teams/commands/dm.md
11  subagents:
12    - name: ms_teams_dm
13      recipe: ms-teams-dm

Common Mistakes

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)