**Status**: Production Ready ✅ | **Last Verified**: 2025-11-26
/plugin marketplace add secondsky/claude-skills/plugin install cloudflare-workflows@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/common-issues.mdreferences/production-checklist.mdreferences/workflow-patterns.mdreferences/wrangler-commands.mdtemplates/basic-workflow.tstemplates/scheduled-workflow.tstemplates/worker-trigger.tstemplates/workflow-with-events.tstemplates/workflow-with-retries.tstemplates/wrangler-workflows-config.jsoncStatus: Production Ready ✅ | Last Verified: 2025-11-26
Dependencies: cloudflare-worker-base (for Worker setup)
Contents: Quick Start • Core Concepts • Critical Rules • Top Errors • Common Patterns • When to Load References • Limits
Use the Cloudflare Workflows starter template:
npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow
What you get:
src/index.ts:
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
type Env = {
MY_WORKFLOW: Workflow;
};
type Params = {
userId: string;
email: string;
};
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
const { userId, email } = event.payload;
// Step 1: Do work with automatic retries
const result = await step.do('process user', async () => {
return { processed: true, userId };
});
// Step 2: Wait before next step
await step.sleep('wait 1 hour', '1 hour');
// Step 3: Continue workflow
await step.do('send email', async () => {
return { sent: true, email };
});
return { completed: true, userId };
}
}
// Worker to trigger workflow
export default {
async fetch(req: Request, env: Env): Promise<Response> {
const instance = await env.MY_WORKFLOW.create({
params: { userId: '123', email: 'user@example.com' }
});
return Response.json({
id: instance.id,
status: await instance.status()
});
}
};
Template: See templates/basic-workflow.ts for complete example
{
"name": "my-workflow",
"main": "src/index.ts",
"compatibility_date": "2025-10-22",
"workflows": [
{
"binding": "MY_WORKFLOW",
"name": "my-workflow",
"class_name": "MyWorkflow"
}
]
}
Template: See templates/wrangler-workflows-config.jsonc
npm run deploy
Every workflow must extend WorkflowEntrypoint:
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
// Workflow logic here
}
}
Key Points:
Env: Environment bindings (KV, D1, etc.)Params: Typed payload passed when creating workflow instanceevent: Contains id, payload, timestampstep: Methods for durable executionAll workflow work MUST be done in steps for durability:
// step.do - Execute work with automatic retries
await step.do('step name', async () => {
return { result: 'data' };
});
// step.sleep - Wait for duration
await step.sleep('wait', '1 hour');
// step.sleepUntil - Wait until timestamp
await step.sleepUntil('wait until', Date.now() + 3600000);
// step.waitForEvent - Wait for external event
const event = await step.waitForEvent('payment received', 'payment.completed', {
timeout: '30 minutes'
});
CRITICAL: All I/O (fetch, KV, D1, R2) must happen inside step.do() callbacks!
Reference: See references/workflow-patterns.md for all patterns
✅ Perform all I/O inside step.do() - Required for durability ✅ Use named steps - Makes debugging easier ✅ Return JSON-serializable data from steps - Required for state persistence ✅ Use step.sleep() for delays - Don't use setTimeout() ✅ Handle errors explicitly - Use try/catch in step callbacks ✅ Use NonRetryableError for permanent failures - Stops retries
Workflow Patterns: See references/workflow-patterns.md for:
❌ Never do I/O outside step.do() - Will fail with "I/O context" error ❌ Never use setTimeout() or setInterval() - Use step.sleep() instead ❌ Never return non-serializable data - Functions, Promises, etc. will fail ❌ Never hardcode timeouts - Use workflow config ❌ Never ignore NonRetryableError - Indicates permanent failure
Error:
Cannot perform I/O on behalf of a different request
Cause: Performing I/O outside step.do() callback
Solution:
// ❌ WRONG
const data = await fetch('https://api.example.com');
await step.do('use data', async () => {
return data; // Error!
});
// ✅ CORRECT
const data = await step.do('fetch data', async () => {
const response = await fetch('https://api.example.com');
return await response.json();
});
Error:
Cannot serialize workflow state
Cause: Returning non-JSON-serializable data from step
Solution:
// ❌ WRONG
await step.do('process', async () => {
return { fn: () => {} }; // Functions not serializable
});
// ✅ CORRECT
await step.do('process', async () => {
return { result: 'data' }; // JSON-serializable
});
Error: Workflow retries forever on permanent failures
Solution:
import { NonRetryableError } from 'cloudflare:workers';
await step.do('validate', async () => {
if (!isValid) {
throw new NonRetryableError('Invalid input'); // Stop retries
}
return { valid: true };
});
Error:
WorkflowEvent 'payment.completed' not found
Cause: Event name mismatch between waitForEvent and trigger
Solution:
// Workflow waits for event
const event = await step.waitForEvent('wait payment', 'payment.completed', {
timeout: '30 minutes'
});
// Trigger event with EXACT same name
await instance.trigger('payment.completed', { amount: 100 });
Error:
Workflow execution failed: Step timeout exceeded
Cause: Step exceeds maximum CPU time (30 seconds)
Solution:
// ❌ WRONG
await step.do('long task', async () => {
for (let i = 0; i < 1000000; i++) {
// Long computation
}
});
// ✅ CORRECT - Break into smaller steps
for (let i = 0; i < 100; i++) {
await step.do(`batch ${i}`, async () => {
// Process batch
});
}
All Issues: See references/common-issues.md for complete documentation
Basic workflow with steps executing in order. Each step completes before the next begins.
Use cases: Order processing, user onboarding, data pipelines
Load templates/basic-workflow.ts for complete example
Workflow with time delays between steps using step.sleep() or step.sleepUntil().
Use cases: Reminder sequences, scheduled tasks, delayed notifications
Load templates/scheduled-workflow.ts for complete example
Wait for external events with step.waitForEvent(). Always set timeout and handle with NonRetryableError:
const payment = await step.waitForEvent('wait payment', 'payment.completed', {
timeout: '30 minutes'
});
if (!payment) throw new NonRetryableError('Payment timeout');
Load templates/workflow-with-events.ts for complete example
Use NonRetryableError for permanent failures (404), regular Error for transient failures (5xx):
const data = await step.do('fetch', async () => {
const response = await fetch(url);
if (!response.ok) {
if (response.status === 404) throw new NonRetryableError('Not found');
throw new Error('Temporary failure'); // Will retry
}
return await response.json();
});
Load templates/workflow-with-retries.ts for complete example with retry configuration
From Worker: Create instances via env.MY_WORKFLOW.create(), get status with instance.status(), trigger events with instance.trigger().
From Cron: Use scheduled() handler to create workflow instances on schedule.
Load templates/worker-trigger.ts for complete Worker trigger example
Load templates/scheduled-workflow.ts for complete Cron trigger example
references/common-issues.md: Encountering I/O context, serialization, NonRetryableError, event naming, or timeout errors; troubleshooting workflow failures.
references/workflow-patterns.md: Building complex orchestration, approval workflows, idempotency patterns, or circuit breaker patterns.
references/wrangler-commands.md: Need CLI commands for managing workflow instances, debugging stuck workflows, or monitoring production.
references/production-checklist.md: Preparing for deployment, need pre-deployment verification, setting up monitoring/error handling.
templates/: basic-workflow.ts (sequential), scheduled-workflow.ts (delays/sleep), workflow-with-events.ts (waitForEvent), workflow-with-retries.ts (custom retry), worker-trigger.ts (Worker triggers), wrangler-workflows-config.jsonc (Wrangler config)
Key Commands: wrangler workflows create, wrangler workflows instances list/describe/terminate, wrangler deploy
Load references/wrangler-commands.md for complete CLI reference with all workflow management commands, monitoring workflows, and debugging stuck instances.
Workflows automatically persist state between steps. No manual state management needed:
export class StatefulWorkflow extends WorkflowEntrypoint {
async run(event, step) {
// Step 1 result is automatically persisted
const result1 = await step.do('step 1', async () => {
return { data: 'value' };
});
// Even if workflow crashes here, step 1 won't re-run
await step.sleep('wait', '1 hour');
// Step 2 can use step 1's result (still available after sleep)
await step.do('step 2', async () => {
console.log(result1.data); // 'value' - persisted!
});
}
}
Key Points:
| Resource | Limit |
|---|---|
| Step CPU Time | 30 seconds |
| Workflow Duration | 30 days |
| Step Payload Size | 128 KB |
| Workflow Payload Size | 128 KB |
| Steps per Workflow | 1,000 |
| Concurrent Instances | 1,000 per workflow |
| Event Payload Size | 128 KB |
Workarounds:
Example Cost (1M workflow runs):
Solution: Move all I/O into step.do() callbacks → See references/common-issues.md #1
Solution: Return only JSON-serializable data from steps → See references/common-issues.md #2
Solution: Throw NonRetryableError for permanent failures → See references/common-issues.md #3
Solution: Ensure event names match exactly → See references/common-issues.md #4
Solution: Break long computations into smaller steps → See references/common-issues.md #5
10-Point Pre-Deployment Checklist: I/O context isolation, JSON serialization, NonRetryableError usage, event name consistency, step duration limits, error handling, retry configuration, timeouts, workflow naming, and monitoring.
Load references/production-checklist.md for complete checklist with detailed explanations, code examples, verification steps, and deployment workflow.
Workflows: https://developers.cloudflare.com/workflows/ • API Reference: https://developers.cloudflare.com/workflows/reference/ • Examples: https://developers.cloudflare.com/workflows/examples/ • Blog: https://blog.cloudflare.com/cloudflare-workflows/
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.