Cloudflare Workflows Skill

Status: Production Ready ✅ Last Updated: 2025-10-22 Production Tested: Yes

---

Auto-Trigger Keywords

Primary Keywords:

• Cloudflare Workflows
• workflows
• durable execution
• WorkflowEntrypoint
• workflow step
• long-running tasks
• multi-step applications

Secondary Keywords:

• step.do
• step.sleep
• step.sleepUntil
• step.waitForEvent
• workflow retries
• workflow state
• NonRetryableError
• workflow events
• workflow bindings
• wrangler workflows

Error-Based Keywords:

• NonRetryableError
• I/O context error
• workflow execution failed
• serialization error
• WorkflowEvent not found
• Cannot perform I/O on behalf of a different request
• workflow stuck running
• payload too large

Framework Keywords:

• Cloudflare Workers
• wrangler
• @cloudflare/workers-types
• cloudflare:workers
• cloudflare:workflows

---

What This Skill Does

This skill provides complete, production-ready knowledge for Cloudflare Workflows - a durable execution framework for building multi-step applications on Workers that:

• Automatically retry failed steps with configurable backoff
• Persist state between steps so workflows survive failures
• Run for hours or days with built-in sleep and scheduling
• Wait for external events to enable human-in-the-loop patterns
• Coordinate between APIs with reliable execution guarantees

Use this skill when:

• Building long-running processes (hours/days)
• Implementing retry logic for reliability
• Creating event-driven workflows
• Scheduling multi-step tasks
• Coordinating between third-party APIs
• Building approval/review workflows
• Processing data pipelines
• Handling webhook orchestration

---

Known Issues Prevented

This skill prevents 5 documented errors with sources:

Error Prevention: 5/5 = 100%

---

Token Efficiency

Why the savings:

• Complete API reference (no searching docs)
• 6 working templates (copy-paste ready)
• All known issues documented with fixes
• Production patterns included
• Retry configuration examples

---

What's Included

SKILL.md (Comprehensive Guide)

• Quick Start (10 minutes to first workflow)
• Complete WorkflowEntrypoint API
• All step methods: do, sleep, sleepUntil, waitForEvent
• Retry configuration (limits, backoff, timeouts)
• Error handling (NonRetryableError, try-catch)
• Triggering workflows (from Workers, HTTP, scheduled)
• State persistence rules
• Wrangler commands
• Production checklist

Templates (6 Files)

1. basic-workflow.ts - Simple 3-step workflow with retries
2. workflow-with-retries.ts - Advanced retry config with exponential/linear/constant backoff
3. scheduled-workflow.ts - Daily/weekly/monthly scheduled workflows
4. workflow-with-events.ts - Event-driven approval flow with timeout
5. worker-trigger.ts - Worker that creates, queries, and manages workflows
6. wrangler-workflows-config.jsonc - Complete configuration example

References

1. common-issues.md - 5 documented errors with sources and solutions
2. workflow-patterns.md - Production patterns (idempotency, error handling, long-running, human-in-loop, chaining, testing, monitoring)

---

Quick Example

Create a workflow:

import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Step 1: Do work (auto-retries on failure)
    const data = await step.do('fetch data', async () => {
      const response = await fetch('https://api.example.com/data');
      return await response.json();
    });

    // Step 2: Wait before next action
    await step.sleep('wait 1 hour', '1 hour');

    // Step 3: Continue workflow
    await step.do('process data', async () => {
      // Process data
      return { processed: true };
    });

    return { status: 'complete' };
  }
}

Trigger from Worker:

const instance = await env.MY_WORKFLOW.create({
  params: { userId: '123' }
});

const status = await instance.status();

---

When to Use This Skill

✅ Use Workflows when:

• Process takes longer than 30 seconds (Workers timeout)
• Need automatic retries with backoff
• Need to sleep/schedule between steps
• Coordinating multiple async operations
• Waiting for external events (webhooks, approvals)
• Building reliable data pipelines
• Orchestrating microservices
• Processing batch jobs over time

❌ Don't use Workflows when:

• Need real-time responses (<100ms)
• Handling simple HTTP requests
• No retry logic needed
• All work completes in <10 seconds
• Need WebSocket connections (use Durable Objects)

---

Latest Versions (Verified 2025-10-22)

{
  "devDependencies": {
    "wrangler": "^4.44.0",
    "@cloudflare/workers-types": "^4.20251014.0",
    "typescript": "^5.9.0"
  }
}

---

Official Documentation

• Workflows Docs: https://developers.cloudflare.com/workflows/
• Get Started: https://developers.cloudflare.com/workflows/get-started/guide/
• Workers API: https://developers.cloudflare.com/workflows/build/workers-api/
• Sleeping & Retrying: https://developers.cloudflare.com/workflows/build/sleeping-and-retrying/
• Events & Parameters: https://developers.cloudflare.com/workflows/build/events-and-parameters/
• Limits: https://developers.cloudflare.com/workflows/reference/limits/
• Pricing: https://developers.cloudflare.com/workflows/platform/pricing/

---

Related Skills

• cloudflare-worker-base - Hono + Vite + Static Assets foundation
• cloudflare-queues - Message queues for async processing
• cloudflare-d1 - D1 serverless SQL database
• cloudflare-kv - KV key-value storage

---

Questions? Issues?

1. Check references/common-issues.md for known errors
2. Review references/workflow-patterns.md for production patterns
3. Use templates in templates/ directory
4. Consult official docs: https://developers.cloudflare.com/workflows/

---

Maintainer: Jeremy Dawes | jeremy@jezweb.net