jackspace/claudeskillz/checkpoint-workflow-builder

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Build resumable state-machine workflows with checkpoint patterns, progress preservation, and automatic recovery for complex multi-phase operations that need to survive interruptions, timeouts, and failures.

Install

npx vskill@latest install jackspace/claudeskillz/checkpoint-workflow-builder

SKILL.md

Checkpoint Workflow Builder

Design and implement fault-tolerant workflows that can resume from any point of failure.

Overview

Complex workflows often fail mid-execution due to:

  • Network timeouts
  • System crashes
  • Resource exhaustion
  • External service failures
  • User interruptions

This skill teaches you to build workflows that:

  • Save progress at key checkpoints
  • Resume from last successful state
  • Handle partial failures gracefully
  • Provide clear progress visibility
  • Enable manual intervention points

When to Use

Use this skill when:

  • Building multi-phase data pipelines
  • Implementing long-running migration scripts
  • Creating deployment workflows
  • Processing large batches of items
  • Orchestrating multi-system operations
  • Building ETL (Extract, Transform, Load) workflows
  • Implementing saga patterns for distributed systems
  • Creating user-facing wizards with save/resume

Core Concepts

State Machine Pattern
┌─────────┐
│  INIT   │
└────┬────┘
     │
     ▼
┌────────────┐
│  DOWNLOAD  │
└─────┬──────┘
      │
      ▼
┌────────────┐
│  PROCESS   │
└─────┬──────┘
      │
      ▼
┌────────────┐
│  VALIDATE  │
└─────┬──────┘
      │
      ▼
┌────────────┐
│  FINALIZE  │
└─────┬──────┘
      │
      ▼
┌────────────┐
│  COMPLETE  │
└────────────┘

Each state:

  • Has clear entry conditions
  • Performs specific operations
  • Saves checkpoint before transition
  • Can be resumed independently

Basic Implementation

Simple State Machine
bash
#!/bin/bash
# state-machine.sh - Basic resumable workflow
 
STATE_FILE=".workflow_state"
 
# Read current state (default: INIT)
CURRENT_STATE=$(cat "$STATE_FILE" 2>/dev/null || echo "INIT")
 
echo "Current state: $CURRENT_STATE"
 
case "$CURRENT_STATE" in
    INIT)
        echo "=== Phase 1: Initialization ==="
 
        # Initialize workspace
        mkdir -p workspace
        mkdir -p results
 
        # Download dependencies
        echo "Setting up environment..."
 
        # Save next state
        echo "DOWNLOAD" > "$STATE_FILE"
        echo "✓ Initialization complete"
        echo "Run again to continue"
        ;;
 
    DOWNLOAD)
        echo "=== Phase 2: Download Data ==="
 
        # Download data files
        echo "Downloading data..."
        # curl -o workspace/data.zip https://example.com/data.zip
 
        # Verify download
        if [ -f "workspace/data.zip" ]; then
            echo "EXTRACT" > "$STATE_FILE"
            echo "✓ Download complete"
            echo "Run again to continue"
        else
            echo "✗ Download failed - fix and run again"
            exit 1
        fi
        ;;
 
    EXTRACT)
        echo "=== Phase 3: Extract Data ==="
 
        # Extract files
        echo "Extracting data..."
        # unzip workspace/data.zip -d workspace/
 
        echo "PROCESS" > "$STATE_FILE"
        echo "✓ Extraction complete"
        echo "Run again to continue"
        ;;
 
    PROCESS)
        echo "=== Phase 4: Process Data ==="
 
        # Process data
        echo "Processing data..."
        # ./process_data.sh workspace/ results/
 
        echo "VALIDATE" > "$STATE_FILE"
        echo "✓ Processing complete"
        echo "Run again to continue"
        ;;
 
    VALIDATE)
        echo "=== Phase 5: Validate Results ==="
 
        # Validate results
        echo "Validating results..."
        # ./validate.sh results/
 
        if [ $? -eq 0 ]; then
            echo "FINALIZE" > "$STATE_FILE"
            echo "✓ Validation passed"
            echo "Run again to finalize"
        else
            echo "✗ Validation failed"
            echo "Fix issues and change state to PROCESS to reprocess"
            exit 1
        fi
        ;;
 
    FINALIZE)
        echo "=== Phase 6: Finalize ==="
 
        # Cleanup and finalize
        echo "Finalizing workflow..."
        # mv results/ final/
        # rm -rf workspace/
 
        echo "COMPLETE" > "$STATE_FILE"
        echo "✓ Workflow complete!"
        ;;
 
    COMPLETE)
        echo "=== Workflow Already Complete ==="
        echo "Results available in: final/"
        ;;
 
    *)
        echo "✗ Unknown state: $CURRENT_STATE"
        echo "Reset with: echo 'INIT' > $STATE_FILE"
        exit 1
        ;;
esac
Enhanced with Progress Tracking
bash
#!/bin/bash
# enhanced-state-machine.sh - With detailed progress
 
STATE_FILE=".workflow_state"
PROGRESS_FILE=".workflow_progress.json"
 
# Initialize progress tracking
init_progress() {
    cat > "$PROGRESS_FILE" << EOF
{
  "current_state": "INIT",
  "started_at": "$(date -Iseconds)",
  "updated_at": "$(date -Iseconds)",
  "phases": {
    "INIT": {"status": "pending", "started": null, "completed": null},
    "DOWNLOAD": {"status": "pending", "started": null, "completed": null},
    "PROCESS": {"status": "pending", "started": null, "completed": null},
    "VALIDATE": {"status": "pending", "started": null, "completed": null},
    "FINALIZE": {"status": "pending", "started": null, "completed": null}
  }
}
EOF
}
 
# Update progress
update_progress() {
    local state="$1"
    local status="$2"  # "running", "completed", "failed"
 
    local timestamp="$(date -Iseconds)"
 
    if [ ! -f "$PROGRESS_FILE" ]; then
        init_progress
    fi
 
    jq --arg state "$state" \
       --arg status "$status" \
       --arg timestamp "$timestamp" \
       '.current_state = $state |
        .updated_at = $timestamp |
        .phases[$state].status = $status |
        (.phases[$state].started //= $timestamp) |
        (if $status == "completed" then .phases[$state].completed = $timestamp else . end)' \
       "$PROGRESS_FILE" > "$PROGRESS_FILE.tmp"
 
    mv "$PROGRESS_FILE.tmp" "$PROGRESS_FILE"
}
 
# Show progress
show_progress() {
    if [ ! -f "$PROGRESS_FILE" ]; then
        echo "No progress file found"
        return
    fi
 
    echo "=== Workflow Progress ==="
    echo ""
    jq -r '.phases | to_entries | .[] |
        "[\(.value.status | ascii_upcase)] \(.key)" +
        (if .value.started then " (started: " + .value.started + ")" else "" end)' \
        "$PROGRESS_FILE"
    echo ""
    echo "Current: $(jq -r '.current_state' $PROGRESS_FILE)"
    echo "Updated: $(jq -r '.updated_at' $PROGRESS_FILE)"
}
 
# Workflow implementation
run_workflow() {
    CURRENT_STATE=$(cat "$STATE_FILE" 2>/dev/null || echo "INIT")
 
    # Show progress before executing
    show_progress
 
    case "$CURRENT_STATE" in
        INIT)
            update_progress "INIT" "running"
            echo "Initializing..."
            # ... initialization logic ...
            update_progress "INIT" "completed"
            echo "DOWNLOAD" > "$STATE_FILE"
            ;;
 
        DOWNLOAD)
            update_progress "DOWNLOAD" "running"
            echo "Downloading..."
            # ... download logic ...
            update_progress "DOWNLOAD" "completed"
            echo "PROCESS" > "$STATE_FILE"
            ;;
 
        # ... other states ...
    esac
}
 
run_workflow

Advanced Patterns

Pattern 1: Batched Checkpoint
bash
#!/bin/bash
# batched-checkpoint.sh - Process items with batch checkpoints
 
ITEMS_FILE="items.txt"
CHECKPOINT_FILE=".batch_checkpoint"
BATCH_SIZE=10
 
# Load checkpoint
if [ -f "$CHECKPOINT_FILE" ]; then
    LAST_COMPLETED=$(cat "$CHECKPOINT_FILE")
    echo "Resuming from item $LAST_COMPLETED"
else
    LAST_COMPLETED=0
fi
 
TOTAL_ITEMS=$(wc -l < "$ITEMS_FILE")
ITEMS_PROCESSED=0
 
# Process in batches
tail -n +$((LAST_COMPLETED + 1)) "$ITEMS_FILE" | while read -r item; do
    # Process item
    echo "Processing: $item"
    process_item "$item"
 
    ITEMS_PROCESSED=$((ITEMS_PROCESSED + 1))
 
    # Checkpoint every batch
    if [ $((ITEMS_PROCESSED % BATCH_SIZE)) -eq 0 ]; then
        CURRENT_POSITION=$((LAST_COMPLETED + ITEMS_PROCESSED))
        echo "$CURRENT_POSITION" > "$CHECKPOINT_FILE"
 
        echo "Checkpoint: $CURRENT_POSITION/$TOTAL_ITEMS"
 
        # Optional: Break for timeout management
        if [ $((ITEMS_PROCESSED)) -ge $((BATCH_SIZE * 5)) ]; then
            echo "Processed 5 batches ($(($BATCH_SIZE * 5)) items)"
            echo "Run again to continue"
            exit 0
        fi
    fi
done
 
# Final checkpoint
echo "$TOTAL_ITEMS" > "$CHECKPOINT_FILE"
echo "✓ All items processed!"
Pattern 2: Rollback Support
bash
#!/bin/bash
# rollback-workflow.sh - State machine with rollback
 
STATE_FILE=".state"
ROLLBACK_DIR=".rollback"
 
mkdir -p "$ROLLBACK_DIR"
 
# Save rollback point
save_rollback() {
    local state="$1"
    local timestamp=$(date +%s)
 
    tar -czf "$ROLLBACK_DIR/${state}_${timestamp}.tar.gz" workspace/ 2>/dev/null || true
    echo "${state}_${timestamp}" > "$ROLLBACK_DIR/latest"
}
 
# Perform rollback
rollback() {
    local rollback_point="$1"
 
    if [ -z "$rollback_point" ]; then
        rollback_point=$(cat "$ROLLBACK_DIR/latest" 2>/dev/null)
    fi
 
    if [ -z "$rollback_point" ] || [ ! -f "$ROLLBACK_DIR/${rollback_point}.tar.gz" ]; then
        echo "✗ No rollback point found"
        exit 1
    fi
 
    echo "Rolling back to: $rollback_point"
 
    # Restore from backup
    rm -rf workspace/
    tar -xzf "$ROLLBACK_DIR/${rollback_point}.tar.gz"
 
    # Set state
    STATE=$(echo "$rollback_point" | cut -d'_' -f1)
    echo "$STATE" > "$STATE_FILE"
 
    echo "✓ Rolled back to state: $STATE"
}
 
# In workflow
case "$CURRENT_STATE" in
    DOWNLOAD)
        save_rollback "PRE_DOWNLOAD"
        # ... download logic ...
        ;;
 
    PROCESS)
        save_rollback "PRE_PROCESS"
        # ... process logic ...
        ;;
esac
Pattern 3: Parallel Phase Execution
bash
#!/bin/bash
# parallel-phases.sh - Execute independent phases in parallel
 
STATE_FILE=".parallel_state.json"
 
# Initialize parallel state
init_parallel_state() {
    cat > "$STATE_FILE" << EOF
{
  "phase_a": "pending",
  "phase_b": "pending",
  "phase_c": "pending",
  "finalize": "pending"
}
EOF
}
 
# Update phase status
update_phase() {
    local phase="$1"
    local status="$2"
 
    jq --arg phase "$phase" --arg status "$status" \
       '.[$phase] = $status' "$STATE_FILE" > "$STATE_FILE.tmp"
    mv "$STATE_FILE.tmp" "$STATE_FILE"
}
 
# Check if all phases complete
all_phases_complete() {
    local incomplete=$(jq -r '[.phase_a, .phase_b, .phase_c] | map(select(. != "completed")) | length' "$STATE_FILE")
    [ "$incomplete" -eq 0 ]
}
 
# Execute phase
execute_phase() {
    local phase="$1"
    local current_status=$(jq -r ".$phase" "$STATE_FILE")
 
    if [ "$current_status" = "completed" ]; then
        echo "$phase: Already complete"
        return 0
    fi
 
    echo "$phase: Running"
    update_phase "$phase" "running"
 
    # Phase-specific logic
    case "$phase" in
        phase_a)
            # Independent task A
            task_a
            ;;
        phase_b)
            # Independent task B
            task_b
            ;;
        phase_c)
            # Independent task C
            task_c
            ;;
    esac
 
    if [ $? -eq 0 ]; then
        update_phase "$phase" "completed"
        echo "$phase: Completed"
    else
        update_phase "$phase" "failed"
        echo "$phase: Failed"
        return 1
    fi
}
 
# Main workflow
[ ! -f "$STATE_FILE" ] && init_parallel_state
 
# Run independent phases
execute_phase "phase_a"
execute_phase "phase_b"
execute_phase "phase_c"
 
# Check if ready for finalization
if all_phases_complete; then
    finalize_status=$(jq -r '.finalize' "$STATE_FILE")
 
    if [ "$finalize_status" != "completed" ]; then
        echo "All phases complete. Finalizing..."
        finalize
        update_phase "finalize" "completed"
        echo "✓ Workflow complete!"
    fi
else
    echo "Some phases incomplete. Run again to retry."
fi

Real-World Examples

Example 1: Database Migration Workflow
bash
#!/bin/bash
# db-migration-workflow.sh
 
STATE_FILE=".migration_state"
MIGRATION_LOG="migration.log"
 
log() {
    echo "[$(date -Iseconds)] $1" | tee -a "$MIGRATION_LOG"
}
 
CURRENT_STATE=$(cat "$STATE_FILE" 2>/dev/null || echo "INIT")

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
12
Repository forks
4
7-day trend score
13

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 30 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/jackspace/claudeskillz/checkpoint-workflow-builder/badge)](https://verified-skill.com/skills/jackspace/claudeskillz/checkpoint-workflow-builder)

Something wrong with this skill or its page? Tell us.