Code Executor Skill

Overview

This skill teaches you (Main Claude Code) how to efficiently handle multi-tool MCP workflows by launching a subagent that writes and executes code to compose MCP tool calls.

Architecture

Main Context (YOU - no MCP servers configured)
    ↓
    Recognize multi-tool MCP workflow needed
    ↓
    Launch subagent via Task tool
    ↓
Subagent Context (has MCP servers configured)
    ↓
    Write TypeScript/Python code
    ↓
    Execute code via Bash (deno/python)
    ↓
    Code calls multiple MCP tools via local MCP client
    ↓
    Return results to YOU (main context)

Why This Architecture?

Problem: Loading all MCP tool schemas into your main context causes token bloat (141k tokens for 47 tools).

Solution:

YOU (main) have NO MCP servers → no token bloat
Subagent has MCP servers → isolated context
Subagent writes code that calls multiple tools
Results return to you

Benefits:

✅ 98% token reduction in main context
✅ Multi-tool composition in single execution
✅ Complex logic, loops, data transformations
✅ Subagent context disposed after task

When to Use This Pattern

✅ Launch Subagent With This Skill When:

Multi-tool MCP workflows (3+ MCP tool calls needed)
- Example: "List files, read each one, aggregate data, store in database"
- Example: "Fetch from multiple APIs, merge results, write report"
Complex data processing across MCP tools
- Example: "Read database records, enrich with API data, filter, store results"
- Example: "Parse all JSON files in directory, validate, deduplicate, insert to DB"
Conditional tool selection
- Example: "Try primary API, fallback to secondary if it fails, then cache"
- Example: "Route to different storage backends based on file size"
Parallel MCP operations
- Example: "Fetch from 5 different APIs simultaneously"
- Example: "Process multiple files in parallel"
Retry logic and error recovery
- Example: "Retry database query with exponential backoff"
- Example: "Try multiple data sources until one succeeds"

❌ Don't Use This Pattern When:

Single simple MCP tool call - Just call the tool directly
No MCP tools needed - Use regular task planning
UI/user interaction required - Use slash commands
Simple sequential operations - Regular tool calls are clearer

How to Launch a Subagent

When you identify a multi-tool MCP workflow, use the Task tool to launch a subagent:

Task({
  subagent_type: "general-purpose",
  prompt: `You have access to MCP servers with the following tools:
  - mcp__filesystem__readFile, writeFile, listDirectory
  - mcp__database__query, insert, update
  - [list the relevant tools for this task]

  Task: [Describe the multi-tool workflow clearly]

  Instructions:
  1. Reference the cached script pattern from scripts/[relevant-script].ts
  2. Write TypeScript code that:
     - Imports: import { callMCPTool } from '../../lib/mcp-client.ts';
     - Calls MCP tools using callMCPTool('mcp__server__tool', params)
     - Processes and transforms data as needed
     - Returns summary of results
  3. Execute the code via Bash with MCP_CONFIG_PATH set:
     MCP_CONFIG_PATH=~/.claude/subagent-mcp.json deno run --allow-read --allow-run --allow-env /tmp/script.ts
  4. Return the execution results

  Use the pattern from: [specify cached script that matches]
  - scripts/typescript/multi-tool-workflow.ts (sequential pipeline)
  - scripts/typescript/parallel-execution.ts (concurrent operations)
  - scripts/typescript/error-recovery.ts (retry logic)
  - scripts/typescript/file-processing.ts (batch file ops)
  - scripts/typescript/conditional-logic.ts (dynamic tool selection)
  - scripts/typescript/data-aggregation.ts (multi-source merging)

  Expected output: [What you need back from the subagent]`
})

Cached Script Patterns

The skill includes 12 proven script patterns (6 TypeScript + 6 Python) in the scripts/ directory. Always reference these when launching subagents:

TypeScript Patterns

scripts/typescript/multi-tool-workflow.ts
- Sequential 5-step pipeline: Fetch → Transform → Validate → Store → Report
- Use for: Data processing pipelines where each step depends on previous
scripts/typescript/parallel-execution.ts
- Concurrent operations with Promise.all and Promise.allSettled
- Use for: Fetching from multiple sources simultaneously
scripts/typescript/error-recovery.ts
- Retry logic with exponential backoff, fallback strategies
- Use for: Unreliable APIs, failover patterns
scripts/typescript/file-processing.ts
- Batch file operations: list → filter → process → aggregate
- Use for: Processing multiple files, generating reports
scripts/typescript/conditional-logic.ts
- Dynamic tool selection based on runtime data
- Use for: Routing, adaptive workflows, decision trees
scripts/typescript/data-aggregation.ts
- Fetch from multiple sources, transform to common format, merge
- Use for: Combining data from multiple databases/APIs

Python Patterns

Same patterns available in scripts/python/:

multi_tool_workflow.py
parallel_execution.py
error_recovery.py
file_processing.py
conditional_logic.py
data_aggregation.py

Subagent Task Prompt Template

Use this template when launching subagents:

Task({
  subagent_type: "general-purpose",
  prompt: `You are a subagent with access to MCP servers. Write code to complete this task.

  ## Available MCP Tools
  [List the MCP servers/tools available - you should know these from your configuration]
  - mcp__filesystem__readFile, writeFile, listDirectory
  - mcp__database__query, insert
  - [etc...]

  ## Task
  [Clear description of what needs to be done]

  ## Instructions

  1. **Reference Cached Pattern**
     Use the pattern from: scripts/typescript/[most-similar-script].ts
     - This script shows: [what pattern it demonstrates]
     - Adapt it for: [how to modify for this task]

  2. **Write TypeScript Code**
     \`\`\`typescript
     import { callMCPTool } from '../../lib/mcp-client.ts';

     // [Step-by-step comments of what the code should do]
     \`\`\`

  3. **Tool Call Format**
     - Format: callMCPTool('mcp__<server>__<tool>', { params })
     - Example: callMCPTool('mcp__filesystem__readFile', { path: '/data/file.json' })

  4. **Execute Code**
     Run via Bash with MCP_CONFIG_PATH set:
     \`\`\`bash
     MCP_CONFIG_PATH=~/.claude/subagent-mcp.json deno run --allow-read --allow-run --allow-env /tmp/your-script.ts
     \`\`\`

  5. **Return Results**
     Provide summary of:
     - What was accomplished
     - Number of records/files processed
     - Any errors or warnings
     - Final output data

  ## Expected Output
  [Specify exactly what data/summary you need back]

  ## Error Handling
  - Wrap all MCP calls in try/catch
  - Log errors clearly
  - [Any specific error handling needed]
  `
})

Example: Complete Workflow

User Request

"Read all JSON files in /tmp/data, aggregate the data, and store in database"

Your Response (Main Claude Code)

You recognize this needs:

Multiple filesystem operations (list, read multiple files)
Data processing (parse JSON, aggregate)
Database operation (insert)

You launch subagent:

Task({
  subagent_type: "general-purpose",
  prompt: `You have access to MCP servers with these tools:
  - mcp__filesystem__listDirectory
  - mcp__filesystem__readFile
  - mcp__database__insert

  Task: Read all JSON files in /tmp/data, parse them, aggregate the data, and store in database table 'aggregated_data'.

  Instructions:
  1. Use the pattern from scripts/typescript/file-processing.ts
     - It shows: batch file operations with filtering and aggregation
     - Adapt it to: read JSON files specifically and store results in DB

  2. Write TypeScript code that:
     - Lists files in /tmp/data
     - Filters for .json extension
     - Reads each JSON file
     - Parses and aggregates the data
     - Stores aggregated results in database

  3. Import the MCP client:
     import { callMCPTool } from '../../lib/mcp-client.ts';

  4. Execute via:
     MCP_CONFIG_PATH=~/.claude/subagent-mcp.json deno run --allow-read --allow-run --allow-env /tmp/aggregate-files.ts

  5. Return: Number of files processed and records stored

  Expected output: "Processed X files, stored Y records in database"`
})

Subagent Executes

Reads cached pattern from scripts/typescript/file-processing.ts
Writes adapted code:

import { callMCPTool } from '../../lib/mcp-client.ts';

const files = await callMCPTool('mcp__filesystem__listDirectory', {
  path: '/tmp/data'
});

const jsonFiles = files.filter(f => f.name.endsWith('.json'));
const allData = [];

for (const file of jsonFiles) {
  const content = await callMCPTool('mcp__filesystem__readFile', {
    path: file.path
  });
  allData.push(...JSON.parse(content));
}

const aggregated = {
  total_records: allData.length,
  data: allData,
  timestamp: new Date().toISOString()
};

await callMCPTool('mcp__database__insert', {
  table: 'aggregated_data',
  record: aggregated
});

console.log(`Processed ${jsonFiles.length} files, ${allData.length} records`);

Executes code via Bash
Returns: "Processed 15 files, 1,247 records stored in database"

You Receive Results

You report to user: "✓ Successfully processed 15 JSON files from /tmp/data and stored 1,247 aggregated records in the database."

Tool Naming Convention

Format: mcp__<server>__<tool>

Examples:

mcp__filesystem__readFile
mcp__database__query
mcp__github__createPullRequest
mcp__postgres__insert

The <server> name comes from the subagent's MCP configuration file (.mcp.json or ~/.claude/subagent-mcp.json).

Choosing TypeScript vs Python

TypeScript (Deno):

✅ Strong typing with interfaces
✅ Better for complex data transformations
✅ Native async/await, Promise.all
✅ Faster execution
❌ Requires Deno installed

Python:

✅ More familiar to some developers
✅ Better for data science/ML tasks
✅ Rich standard library
✅ Type hints with TypedDict
❌ Slightly slower

Default recommendation: Use TypeScript unless subagent explicitly needs Python libraries.

MCP Client Library

The subagent uses a local MCP client library to call tools:

TypeScript: lib/mcp-client.ts

import { callMCPTool, callMCPToolsParallel } from '../../lib/mcp-client.ts';

// Single tool call
const result = await callMCPTool('mcp__filesystem__readFile', {
  path: '/data/file.json'
});

// Parallel calls
const [file1, file2, file3] = await callMCPToolsParallel([
  { tool: 'mcp__filesystem__readFile', parameters: { path: '/data/1.json' } },
  { tool: 'mcp__filesystem__readFile', parameters: { path: '/data/2.json' } },
  { tool: 'mcp__filesystem__readFile', parameters: { path: '/data/3.json' } }
]);

Python: lib/mcp_client.py

from lib.mcp_client import call_mcp_tool, call_mcp_tools_parallel

# Single tool call
result = await call_mcp_tool('mcp__filesystem__readFile', {
    'path': '/data/file.json'
})

# Parallel calls
results = await call_mcp_tools_parallel([
    {'tool': 'mcp__filesystem__readFile', 'parameters': {'path': '/data/1.json'}},
    {'tool': 'mcp__filesystem__readFile', 'parameters': {'path': '/data/2.json'}},
    {'tool': 'mcp__filesystem__readFile', 'parameters': {'path': '/data/3.json'}}
])

Templates

For simpler tasks, reference the templates in templates/:

basic-typescript.template.ts - Single tool call skeleton
basic-python.template.py - Single tool call skeleton
multi-tool.template.ts - Multiple tool composition
multi-tool.template.py - Multiple tool composition

Tell the subagent: "Use the pattern from templates/basic-typescript.template.ts"

Error Handling

Always instruct subagents to include error handling:

try {
  const result = await callMCPTool('mcp__database__query', {
    query: 'SELECT * FROM users'
  });
  return { success: true, data: result };
} catch (error) {
  console.error('Database query failed:', error.message);
  return { success: false, error: error.message };
}

Best Practices

When Launching Subagents

Be specific about tools available
- List the exact MCP tools the subagent has access to
- Don't assume subagent knows your MCP configuration
Reference cached patterns
- Always point to the most similar cached script
- Explain how to adapt it for the current task
Specify execution command
- CRITICAL: Set MCP_CONFIG_PATH=~/.claude/subagent-mcp.json before command
- Include the full deno run or python command
- Include required permissions: --allow-read --allow-run --allow-env
- Example: MCP_CONFIG_PATH=~/.claude/subagent-mcp.json deno run --allow-read --allow-run --allow-env script.ts
Define expected output clearly
- What data you need back
- What format (summary, full data, counts, etc.)
Include error handling instructions
- How to handle failures
- Whether to fail-fast or continue on errors

When Subagent Writes Code

(These are instructions for the subagent, but you should know them to guide effectively)

Always import MCP client first

import { callMCPTool } from '../../lib/mcp-client.ts';

Use proper tool name format
- Format: mcp__<server>__<tool>
- Match exactly to MCP configuration
Handle errors gracefully
- Try/catch around all MCP calls
- Log errors clearly
- Return error status
Process data efficiently
- Use parallel calls when possible (Promise.all, asyncio.gather)
- Stream large datasets
- Aggregate early to reduce memory
Return useful summaries
- Include counts, timestamps
- Report errors/warnings
- Provide actionable results

Debugging

If subagent task fails:

Check MCP configuration
- Is the tool available in subagent's .mcp.json?
- Is the server running?
Verify tool name format
- Correct format: mcp__server__tool
- Match to actual server name in config
Check MCP_CONFIG_PATH is set
- CRITICAL: Bash execution must set MCP_CONFIG_PATH=~/.claude/subagent-mcp.json
- Without this, MCP client won't find server configuration
- Verify config file exists: ls -la ~/.claude/subagent-mcp.json
Check permissions
- Deno needs: --allow-read --allow-run --allow-env
- MCP servers may have restricted access
Review generated code
- Did subagent import MCP client correctly?
- Are tool names formatted properly?
- Is error handling present?
Check execution output
- Look at stdout/stderr from Bash execution
- MCP errors appear in output

Security Considerations

Subagent has code execution - Review generated code before execution in sensitive contexts
MCP servers access resources - Configure MCP with least privilege
Filesystem access - Limit allowed paths in MCP server configuration
Database access - Use read-only connections where possible
Network access - MCP servers can make network requests

Documentation References

Setup: See SUBAGENT_SETUP.md for configuration
TypeScript: See TYPESCRIPT_GUIDE.md for patterns
Python: See PYTHON_GUIDE.md for patterns
Examples: See EXAMPLES.md for complete use cases
API Reference: See REFERENCE.md for MCP client API

Summary

You are Main Claude Code. When you encounter a multi-tool MCP workflow:

✅ Recognize the pattern - Multiple MCP tools needed, complex logic
✅ Launch subagent - Use Task tool with clear instructions
✅ Reference cached scripts - Point to most similar pattern
✅ Specify tools available - List MCP servers/tools explicitly
✅ Define expected output - What you need back from subagent
✅ Receive results - Subagent executes code and returns summary
✅ Report to user - Present results clearly

Key principle: You orchestrate, subagent executes. Keep your main context clean, let subagents handle the heavy MCP lifting.