Excel Generator

⚠️ Multi-Turn Session Rule (CRITICAL)

When the user's request is a continuation of a previous Excel task, you MUST use the --session parameter.

How to detect a continuation task:

• User says: "continue", "modify", "optimize", "adjust", "based on the previous...", "improve the last one..."
• User references previous output: "that report", "the previous Excel", "the analysis above"
• User asks for changes to existing work: "add a chart", "change to purple", "add a column"

How to use session_id:

1. Look for the previous task's output: 💡 To continue this conversation, use: --session xxx
2. Add --session xxx to the command:

python3 scripts/excel_api_client.py "user's follow-up request" \
  --session abc123def456 \
  --language zh-CN \
  --log-path "$EXCEL_LOG" \
  > /dev/null 2>&1 &

⛔ If you don't pass --session, the agent will start fresh and lose all previous context!

🚫 CRITICAL: DO NOT READ USER FILES

NEVER use the read tool on user-provided files (Excel, PDF, CSV, images, etc.).

The backend agent will read and process files itself. You only need to:

1. Upload files using the CLI script --files parameter
2. Pass the user's query directly without modification

Reading files wastes time and causes timeouts. Just upload and let the backend handle everything.

⚠️ IMPORTANT: Background Execution with Progress Monitoring

Excel tasks take 5-25 minutes. You MUST run the script in background and poll the log every 5 seconds to keep the UI responsive and avoid timeouts.

Step 1: Start script in background

EXCEL_LOG=/tmp/excel_$(date +%s).log

python3 scripts/excel_api_client.py "user query" \
  --files "/path/to/file1.xlsx" "/path/to/file2.pdf" \
  --language zh-CN \
  --log-path "$EXCEL_LOG" \
  > /dev/null 2>&1 &

echo "Log: $EXCEL_LOG"

Step 2: Monitor progress (REQUIRED)

STRICT RULES — no exceptions:

1. Poll every 60 seconds by calling exec tool repeatedly. Excel tasks take 10-25 minutes.
2. Only show the LAST TASK PROGRESS UPDATE. Do NOT output full log or summarize it.
3. NEVER restart the task. The Excel agent handles errors internally and will auto-recover.
4. Ignore all errors in the log (e.g., ❌, Missing parameter, jupyter_execute errors). These are normal — the agent will retry automatically.

Every 60 seconds, run this exact sequence (call exec tool each time, do NOT use while loop):

# Step 1: Wait 60 seconds
sleep 60
# Step 2: Check progress
echo "=== Progress Update ==="
grep -A8 "TASK PROGRESS UPDATE" "$EXCEL_LOG" | tail -10
# Step 3: Check if done
grep -E "\[DONE\]|All done" "$EXCEL_LOG" | tail -1

• If log contains [DONE] or ✅ All done! → stop polling, read final output with tail -30 "$EXCEL_LOG", then deliver results.
• If NOT done → report progress to user, then call exec tool again with the same command after 60 seconds.
• Repeat until done — you must keep calling exec tool every 60 seconds until you see [DONE] or All done.

Rules

• Call exec tool repeatedly — do NOT use a while loop (it blocks output). Call exec every 60 seconds yourself.
• NEVER restart the task even if you see errors. The agent handles errors internally.
• Do NOT summarize or interpret the log — just show the raw TASK PROGRESS UPDATE block.

What to report to user

CRITICAL: Output ONLY the current status. Do NOT repeat or accumulate previous status messages. Each update should be a single, fresh line.

After each log read, output ONLY ONE LINE showing the current status:

[Main stage] | [current action] | Elapsed: Xs

Example (output only this single line, nothing else):

Data Processing | Generating charts | Elapsed: 120s

Map TASK PROGRESS UPDATE to main stages:

Example status updates:

Loading data | Reading Excel files | Elapsed: 30s
Data analysis | Processing stock data | Elapsed: 90s
Generating report | Creating HTML analysis | Elapsed: 180s

Do NOT:

• Output tail -50 or full log content
• Mention errors or heartbeat messages
• Restart the task for any reason
• Repeat or accumulate previous status messages — each update must be fresh, not appended to previous ones

A professional skill for generating and updating high-quality Excel files using a sophisticated backend service with AI-powered data analysis, charting, formula validation, and report generation capabilities.

Authentication (Required First)

Before using this skill, authentication must be completed. Run the auth script first:

# Authenticate: checks env token / cached token / browser login
python3 <skill-dir>/scripts/skywork_auth.py || exit 1

Token priority:

1. Environment variable SKYBOT_TOKEN → if set, use directly
2. Cached token file ~/.skywork_token → validate via API, if valid, use it
3. No valid token → opens browser for login, polls until complete, saves token

IMPORTANT - Login URL handling: If script output contains a line starting with [LOGIN_URL], you MUST immediately send that URL to the user in a clickable message (e.g. "Please open this link to log in: <url>"). The user may be in an environment where the browser cannot open automatically, so always surface the login URL.

When to Use This Skill

Use this skill when the user wants to:

• Create Excel files from scratch with data, formulas, charts, and professional formatting
• Analyze existing data files (Excel, CSV, PDF) and generate summary reports or visualizations
• Update or transform Excel files (add calculations, charts, pivot tables, formatting)
• Generate data-driven reports - outputs can be Excel (.xlsx) or professional HTML reports for viewing/sharing
• Perform complex data analysis requiring pandas, numpy, or statistical operations
• Create dashboards or visualizations with charts, conditional formatting, and styled tables
• Extract and structure data from uploaded documents into Excel format
• Search the web for data - the agent can search for real-time information to include in generated outputs (no external search tools required from your side)

Output Format

The agent supports multiple output formats:

• Excel (.xlsx) - for data manipulation and editing
• HTML reports - for viewing and sharing

The backend agent automatically chooses the appropriate format based on the user's request. Just pass the user's natural language request directly.

The backend service is particularly powerful for tasks that benefit from specialized Excel knowledge, formula validation, and visual quality assurance.

How It Works

The skill uses a ReAct agent loop that:

1. Accepts user requests via natural language (in English or Chinese)
2. Processes uploaded files (Excel, CSV, PDF) if provided
3. Streams real-time progress showing LLM reasoning and tool execution
4. Executes specialized tools like jupyter_execute for data manipulation, validate_excel_formulas, validate_excel_charts, etc.
5. Produces output files in /workspace/output/ (automatically registered for download)
6. Supports multi-turn conversations for iterative refinement

⚠️ IMPORTANT: Preserve User's Original Query (Strict No-Rewrite Policy)

When sending requests to the Excel Agent:

• Keep the user's original query exactly as-is - do NOT rewrite, expand, or reinterpret the query
• Pass the query as-is to the backend agent, which has its own understanding capabilities
• Only TWO modifications are allowed:
  1. Time info: For tim