/aws-step-functions

name: aws-step-functions
description: "Authors and edits AWS Step Functions state machines: writes Amazon States Language (ASL) in JSONata, and chooses and structures state types (Task, Choice, Map, Parallel, Pass, Wait, Succeed, Fail). Covers ASL syntax, JSONata data transformation and variables, Retry/Catch error handling, service integrations (.sync, waitForTaskToken callbacks), Distributed Map for large-scale S3/CSV processing, saga/compensation patterns, Standard vs Express workflow choice, TestState API unit testing, and migrating state machines from JSONPath to JSONata. Use when the user is building, authoring, debugging, or migrating a Step Functions state machine or ASL definition, or orchestrating multi-step workflows with branching, retries, or human-approval callbacks, even if they don't say 'Step Functions.' Do NOT use for general Lambda function code, API Gateway, EventBridge wiring, or SAM/CDK application packaging."
version: 1

AWS Step Functions

Overview

AWS Step Functions uses Amazon States Language (ASL) to define state machines as JSON. With AWS Step Functions, you can create workflows, also called state machines, to build distributed applications, automate processes, orchestrate microservices, and create data and machine learning pipelines.

This skill provides comprehensive guidance for writing state machines in ASL, covering:

• ASL structure and JSONata expression syntax
• Details on the eight available workflow states
• The `$states` reserved variable
• Workflow variables with `Assign`
• Error handling
• AWS Service integration patterns
• Example code for data transformation and architecture
• Validation and testing of state machines
• How to migrate from JSONPath to JSONata

The AWS MCP server is recommended for sandboxed execution and audit logging when following this skill, but all steps use AWS CLI syntax and work without it.

When to Load Reference Files

Load the appropriate reference file based on what the user is working on:

• **ASL structure**, **state types**, **Task**, **Pass**, **Choice**, **Wait**, **Succeed**, **Fail**, **Parallel**, **Map** → see `references/asl-state-types.md`
• **Error handling**, **troubleshooting**, **Retry**, **Catch**, **fallback**, **error codes**, **States.Timeout**, **States.ALL** → see `references/error-handling.md`
• **Service integrations**, **Lambda invoke**, **DynamoDB**, **SNS**, **SQS**, **SDK integrations**, **Resource ARN**, **sync**, **async** → see `references/service-integrations.md`
• **Migrating from JSONPath to JSONata**, **migration**, **JSONPath to JSONata**, **InputPath**, **Parameters**, **ResultSelector**, **ResultPath**, **OutputPath**, **intrinsic functions**, **Iterator**, **payload template** → see `references/migrating-from-jsonpath-to-jsonata.md`
• **Validation**, **linting**, **testing**, **TestState**, **test state**, **mock**, **mocking**, **unit test**, **inspection level**, **DEBUG**, **TRACE**, **validate state**, **test in isolation** → see `references/validation-and-testing.md`
• **Architecture patterns**, **examples**, **polling**, **saga**, **compensation**, **scatter-gather**, **semaphore**, **lock**, **human-in-the-loop**, **escalation**, **Express to Standard** → see `references/architecture-patterns.md`
• **Data transformation**, **JSONata expressions**, **filtering**, **aggregation**, **string operations**, **$reduce**, **$lookup**, **$toMillis**, **$partition**, **$parse**, **$hash**, **$uuid** → see `references/transforming-data.md`
• **State input/output**, **$states**, **Assign**, **Output**, **Arguments**, **variable scope**, **variable limits**, **evaluation order**, **passing data between states** → see `references/processing-state-inputs-and-outputs.md`

Quick Reference

Standard vs Express Workflows

| | Standard | Express | | --------------------------------- | ------------------------------------ | ------------------------------------------- | | **Max duration** | 1 year | 5 minutes | | **Execution semantics** | Exactly-once | At-least-once (async) / At-most-once (sync) | | **Execution history** | Retained 90 days, queryable via API | CloudWatch Logs only | | **Max throughput** | 2,000 exec/sec | 100,000 exec/sec | | **Pricing model** | Per state transition | Per execution count + duration | | **`.sync` / `.waitForTaskToken`** | Supported | Not supported | | **Best for** | Auditable, non-idempotent operations | High-volume, idempotent event processing |

**Choose Standard** for: payment processing, order fulfillment, compliance workflows, anything that must never execute twice.

**Choose Express** for: IoT data ingestion, streaming transformations, mobile backends, high-throughput short-lived processing.

> **When recommending Express, the single limitation you must always state — even for fire-and-forget / high-throughput pipelines — is that Express does NOT support `.sync` or `.waitForTaskToken`** (no callbacks, no nested `.sync` waits, no human-approval or job-completion waits). Also note: 5-minute max duration, no queryable execution history (CloudWatch Logs only), and at-least-once (async) / at-most-once (sync) execution — so non-idempotent work can run twice. If any of these matter, choose Standard (exactly-once, up to 1 year, full history).

Setting the State Machine Query Language

JSONata is the preferred way to reference and transform data in ASL. It replaces the five JSONPath I/O fields (`InputPath`, `Parameters`, `ResultSelector`, `ResultPath`, `OutputPath`) with just two: `Arguments` (inputs) and `O