Skills Multi-step Workflow Design

Simple tasks only need one step, but real-world workflows often involve multiple stages.

This article introduces how to break complex tasks into clear steps and organize them into a reliable execution workflow in SKILL.md.

Why explicitly define steps

Claude is very smart, but without explicit step-by-step guidance, it may skip certain stages or execute them in an inconsistent order.

Benefits of explicit steps:

First, it makes Claude's behavior predictable; second, it helps users understand what is happening; third, when errors occur, it is easy to locate which step went wrong.

Basic principles of step design

Principle Description
Each step does only one thing Avoid having one step complete multiple unrelated operations at the same time
Clear inputs and outputs between steps The output of the previous step is the input of the next step, without relying on implicit state
Provide feedback after each step executes Tell the user what this step completed and what the next step is
Allow interruption midway Users can pause or modify parameters at any step

Defining multi-step workflows in SKILL.md

Example

---
name: excel-report-generator
description: >
Generate a formatted Excel report based on the raw data uploaded by the user, including data cleaning,
chart generation, and summary statistics. Trigger when the user needs a data report, Excel output,
or automated statistics.
---

# Excel Report Generator

## Execution Workflow

### Step 1: Read and validate data

1. Check whether the file exists and whether the format is .csv or .xlsx
2. Read the file and output basic information:
- Total rows, total columns
- Data type of each column
- Count of null values
3. If serious issues are found (e.g., the file is empty or the format is unsupported), stop and inform the user

**Output**: Basic data information report (displayed in the conversation)

---

### Step 2: Data cleaning

Run`scripts/clean_data.py`, which performs:
- Remove completely duplicate rows
- Fill null values in numeric columns with0
- Trim leading and trailing spaces from strings

Output the cleaned data to`/home/claude/cleaned_data.csv`

**Output**: Cleaning report (how many rows were removed, how many values were modified)

---

### Step 3: Generate statistical summary

Run`scripts/calc_stats.py`, which calculates:
- Mean, median, and standard deviation of each numeric column
- Trend data grouped by the time column (if a time column exists)

Output to`/home/claude/stats.json`

---

### Step 4: Generate Excel report

Run`scripts/gen_excel.py`, generate an Excel file containing the following:
- Sheet1: cleaned raw data
- Sheet2: statistical summary table
- Sheet3: line chart (if time-series data exists)

Save the final file to`/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**Output**: Call present_files to display the file and provide a download link

---

### Error handling

When any step fails:
1. Display the complete error message
2. Explain possible causes
3. Ask the user whether they want to skip the current step or retry after modifying parameters

How to organize step scripts

Each step of a multi-step workflow can correspond to an independent script file, or be merged into one main script.

Option 1: One script per step (recommended for complex workflows)

excel-report-generator/
├── SKILL.md
└── scripts/
    ├── clean_data.py      # 第二步：数据清洗
    ├── calc_stats.py      # 第三步：统计计算
    └── gen_excel.py       # 第四步：生成报告

Option 2: Single main script (suited for simple workflows)

Example

# File path: scripts/pipeline.py
# Single main script; use the --step parameter to control which step runs

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """Step 2: Data cleaning"""
    print(f"Cleaning data: {input_file}")
    # Actual cleaning logic...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """Step 3: Statistical calculation"""
    print(f"Calculating statistics: {input_file}")
    # Actual statistics logic...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """Step 4: Generate Excel"""
    print(f"Generating Excel report: {output_file}")
    # Actual generation logic...
    return {"status": "success", "output": output_file}

STEPS = {
    "clean": step_clean,
    "stats": step_stats,
    "excel": step_excel,
}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--step",   required=True, choices=STEPS.keys(),
                        help="Step to run: clean / stats / excel")
    parser.add_argument("--input",  required=True, help="Input file path")
    parser.add_argument("--output", required=True, help="Output file path")
    args = parser.parse_args()

    import json
    result = STEPS[args.step](args.input, args.output)
    print(json.dumps(result, ensure_ascii=False, indent=2))

Calling this script in SKILL.md:

Example

# Step 2: Data cleaning
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/example_sales.csv \
  --output /home/claude/cleaned_data.csv

# Step 3: Statistical calculation
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

Dependency checks between steps

When a later step depends on the output files of previous steps, check that the dependent files exist before executing.

Example

# File path: scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
Check whether the prerequisite files of a step have been generated

Parameters:
step_name: Name of the current step (used for error messages)
required_files: List of file paths that must exist

Returns:
True means all dependencies are ready, False means some files are missing
    """
    missing = [f for f in required_files if not os.path.exists(f)]

    if missing:
        print(f"Error: {step_name} is missing prerequisite files:")
        for f in missing:
            print(f"  - {f}")
        print("Please complete the prerequisite steps first.")
        return False

    return True

# Usage example: check prerequisite files before generating Excel in step 4
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("Generate Excel report", deps):
        sys.exit(1)
    print("All prerequisite files are ready, starting to generate the report...")
错误：生成 Excel 报告 缺少前置文件：
  - /home/claude/stats.json
请先完成前置步骤。

In complex workflows, dependencies between steps are easily overlooked. Explicit dependency checks can immediately locate the missing stage when an error occurs, rather than exposing the problem only at the last step.

Other extensions