document-python-direct-exec

Direct Python Execution for Spreadsheet and Document Tasks

When to Use This Skill

Use direct run_shell with Python scripts for structured document operations when:

• Spreadsheets: Reading or writing complex Excel files with multiple sheets, applying formulas, formatting, or data transformations
• PDFs: Generating PDF checklists, reports, invoices, or forms with precise layout control
• Documents: Creating Word documents, HTML reports, or other structured output formats
• Complex Operations: The task involves multiple steps that could exceed agent step limits
• Precision Needed: You need precise control over error handling, debugging, and library imports

Why Direct Execution?

The shell_agent tool can:

• Hit maximum step limits on complex multi-step operations
• Produce unexplained errors on formatting operations
• Fail on intricate reads/writes due to iterative parsing
• Fail to parse heredoc syntax correctly, causing 'unknown error' failures

Direct run_shell with Python is more reliable because it:

• Executes in a single step with no iteration limits
• Provides clearer, immediate error messages
• Handles complex operations without step constraints
• Gives full control over library imports and execution flow
• Writing scripts to .py files first avoids shell_agent parsing issues with heredocs

How to Use

Recommended Pattern: Write Script to File First

For complex multi-line scripts, especially when using shell_agent as executor:

# Step 1: Write the Python script to a file
cat > process_document.py << 'EOF'
# Your document/spreadsheet code here
EOF

# Step 2: Execute the script
python3 process_document.py

Alternative Pattern: Inline Heredoc (Simple Scripts Only)

For short, simple scripts when NOT using shell_agent as the executor:

python3 << 'EOF'
# Your code here
EOF

Spreadsheet Examples

Example 1: Read and Transform Excel Data

import pandas as pd

# Load data from specific sheet
df = pd.read_excel('input.xlsx', sheet_name='Revenue')

# Apply transformations
df['Net_Revenue'] = df['Gross_Revenue'] * (1 - df['Tax_Rate'])

# Save results
df.to_excel('output.xlsx', index=False, sheet_name='Processed')