AutoGineer
Generated banner for AWS Step Functions
Generated logo for AWS Step Functions

AWS Step Functions

AWS LabsOfficialPublished by AWS Labs

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Build workflows with AWS Step Functions state machines using the JSONata query language. Covers Amazon States Language (ASL) structure, state types, variables, data transformation, error handling, AWS service integration, and migrating from the JSONPath to the JSONata query language.
— the description by AWS Labs

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides comprehensive documentation and patterns for defining workflows in AWS Step Functions. It focuses on the Amazon States Language (ASL) and the use of JSONata for data transformation and logic. The skill covers the eight core state types, error handling, service integrations, and best practices for migrating from legacy JSONPath to JSONata. It also includes architectural patterns such as the Saga pattern, polling loops, and semaphore locks to help developers design robust distributed applications.

What it does

  • Explains ASL structure and the eight available state types.
  • Provides syntax guidance for JSONata expressions in state machines.
  • Details error handling strategies using Retry and Catch blocks.
  • Outlines patterns for AWS service integrations like Lambda, DynamoDB, and SQS.
  • Offers architectural templates for common workflow challenges.
  • Provides instructions for migrating existing state machines from JSONPath to JSONata.

When to use it

  • When designing distributed applications or orchestrating microservices on AWS.
  • When building data or machine learning pipelines that require automated processes.
  • When implementing complex logic like retries, error handling, or branching in cloud workflows.
  • When transitioning state machine definitions to use JSONata for data transformation.

Advantages

  • Centralized reference for ASL syntax and JSONata expressions.
  • Includes ready-to-use architectural patterns for common distributed system problems.
  • Clear guidance on state input/output management and variable assignment.
  • Provides comparative analysis between Standard and Express workflow types.

Usage examples

“How do I implement a retry policy in a Task state?”
The agent provides the syntax for the Retry field, explaining how to define error codes, interval seconds, and max attempts within an ASL Task state.
“Show me how to use JSONata to transform output in a Pass state.”
The agent provides a code example demonstrating the use of the Output field with JSONata expressions to format data dynamically.
“What is the difference between Standard and Express workflows?”
The agent returns a comparison table detailing differences in execution duration, throughput, pricing, and history retention.
“How do I migrate my state machine from JSONPath to JSONata?”
The agent explains the replacement of JSONPath fields like InputPath and ResultPath with the new Arguments and Output fields, and provides migration steps.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/awslabs/aws-step-functions/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip aws-step-functions.zip -d .agents/skills

Documentation by AWS Labs

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

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

  • Deployment, SAM, CloudFormation, IaC, DefinitionSubstitutions, X-Ray tracing, logging → see the aws-serverless-deployment skill or deploy-on-aws plugin

Quick Reference

Standard vs Express Workflows
StandardExpress
Max duration1 year5 minutes
Execution semanticsExactly-onceAt-least-once (async) / At-most-once (sync)
Execution historyRetained 90 days, queryable via APICloudWatch Logs only
Max throughput2,000 exec/sec100,000 exec/sec
Pricing modelPer state transitionPer execution count + duration
.sync / .waitForTaskTokenSupportedNot supported
Best forAuditable, non-idempotent operationsHigh-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.

Setting the State Machine Query Language

JSONata is the modern, 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 Output.

Enable at the top level to apply to all states:

{ "QueryLanguage": "JSONata", "StartAt": "...", "States": {...} }

Or per-state to migrate from JSONPath incrementally:

{ "Type": "Task", "QueryLanguage": "JSONata", ... }

JSONPath is still supported and is the default if QueryLanguage is omitted — existing state machines do not need to be migrated.

Best Practices

  • Set "QueryLanguage": "JSONata" at the top level for new state machines unless the user wants to use JSONPath

  • Keep Output minimal — only include what the state immediately after the current state needs

  • Use Assign to store variables needed in later states instead of threading it through Output

  • Use $states.input to reference original state input

  • Remember: Assign and Output are evaluated in parallel — variable assignments in Assign are NOT available in Output of the same state

  • All JSONata expressions must produce a defined value — $data.nonExistentField throws States.QueryEvaluationError

  • Use $states.context.Execution.Input to access the original workflow input from any state

  • Save state machine definitions with .asl.json extension when working outside the console

  • Prefer the optimized Lambda integration (arn:aws:states:::lambda:invoke) over the SDK integration

Troubleshooting

Common Errors

  • States.QueryEvaluationError — JSONata expression failed. Check for type errors, undefined fields, or out-of-range values.

  • Mixing JSONPath fields with JSONata fields in the same state.

  • Using $ or $$ at the top level of a JSONata expression — use $states.input instead.

  • Forgetting {% %} delimiters around JSONata expressions — the string will be treated as a literal.

  • Assigning variables in Assign and expecting them in Output of the same state — new values only take effect in the next state.

  • Reference references/validation-and-testing.md and references/error-handling.md for detailed troubleshooting information.

Resources

Files

references/transforming-data.md

Data Transformation Patterns

JSONata Expression Syntax

JSONata expressions are written inside {% %} delimiters in string values:

"Output": "{% $states.input.customer.name %}"
"TimeoutSeconds": "{% $timeout %}"
"Condition": "{% $states.input.age >= 18 %}"

Rules:

  • The string must start with {% (no leading spaces) and end with %} (no trailing spaces).

  • Not all fields accept JSONata — Type and Resource must be constant strings.

  • JSONata expressions can appear in string values within objects and arrays at any nesting depth.

  • A string without {% %} is treated as a literal value.

  • All string literals inside JSONata expressions must use single quotes ('text'), not double quotes. The expression is already inside a JSON double-quoted string, so double quotes would break the JSON.

  • Complex logic is wrapped in ( expr1; expr2; ...; finalExpr ) where semicolons separate sequential expressions and the last expression is the return value.

  • You cannot use $ or $$ at the top level.

  • You cannot use unqualified field names at top level.

  • Use $parse() instead $eval for deserializing JSON strings.

  • Expressions must produce a defined value because JSON cannot represent undefined.

String Quoting
"Output": "{% 'Hello ' & $states.input.name %}"
"Condition": "{% $states.input.status = 'active' %}"

Never use double quotes inside the expression:

❌  "Output": "{% "Hello" %}"
✓  "Output": "{% 'Hello' %}"
Local Variable Binding with :=

Use := inside ( ... ) blocks to bind intermediate values within a single JSONata expression. Semicolons separate each binding, and the last expression is the return value:

"Output": "{% ( $subtotal := $sum($states.input.items.price); $tax := $subtotal * 0.1; $discount := $exists($couponValue) ? $couponValue : 0; {'subtotal': $subtotal, 'tax': $tax, 'discount': $discount, 'total': $subtotal + $tax - $discount} ) %}"

You can also define local helper functions:

"Assign": {
  "summary": "{% ( $formatPrice := function($amt) { '$' & $formatNumber($amt, '#,##0.00') }; $subtotal := $sum($states.input.items.price); {'itemCount': $count($states.input.items), 'subtotal': $formatPrice($subtotal), 'total': $formatPrice($subtotal * 1.1)} ) %}"
}

Local variables bound with := exist only within the ( ... ) block. They do not affect state machine variables. To persist values across states, use the Assign field.

Filtering Arrays
"Output": {
  "expensiveItems": "{% $states.input.items[price > 100] %}"
}
Aggregation
"Output": {
  "total": "{% $sum($states.input.items.price) %}",
  "average": "{% $average($states.input.items.price) %}",
  "count": "{% $count($states.input.items) %}"
}
String Operations
"Output": {
  "fullName": "{% $states.input.firstName & ' ' & $states.input.lastName %}",
  "upper": "{% $uppercase($states.input.name) %}",
  "trimmed": "{% $trim($states.input.rawInput) %}"
}
Object Merging
"Output": "{% $merge([$states.input, {'processedAt': $now(), 'status': 'complete'}]) %}"
Building Lookup Maps with $reduce

Use $reduce to transform an array into a key-value object:

"Assign": {
  "priceByProduct": "{% $reduce($states.input.items, function($acc, $item) { $merge([$acc, {$item.productId: $item.price}]) }, {}) %}"
}

Given [{"productId": "A1", "price": 10}, {"productId": "B2", "price": 25}], this produces {"A1": 10, "B2": 25}.

Dynamic Key Access with $lookup

Use $lookup to access an object property by a variable key:

"Output": {
  "price": "{% $lookup($priceByProduct, $states.input.productId) %}"
}

This is essential when you've built a mapping object with $reduce and need to retrieve values dynamically. Standard dot notation ($priceByProduct.someKey) only works with literal key names.

Conditional Values
"Output": {
  "tier": "{% $states.input.total > 1000 ? 'gold' : 'standard' %}",
  "discount": "{% $exists($states.input.coupon) ? 0.1 : 0 %}"
}
Array Membership with in and Concatenation with $append

Test if a value exists in an array with in:

"Condition": "{% $states.input.status in ['pending', 'processing', 'shipped'] %}"

Concatenate arrays with $append:

"Assign": {
  "allIds": "{% $append($states.input.orderIds, $states.input.returnIds) %}"
}
Array Mapping
"Output": {
  "names": "{% $states.input.users.(firstName & ' ' & lastName) %}"
}
Generating UUIDs and Random Values
"Assign": {
  "requestId": "{% $uuid() %}",
  "randomValue": "{% $random() %}"
}
Partitioning Arrays
"Assign": {
  "batches": "{% $partition($states.input.items, 10) %}"
}
Parsing JSON Strings
"Assign": {
  "parsed": "{% $parse($states.input.jsonString) %}"
}
Hashing
"Assign": {
  "hash": "{% $hash($states.input.content, 'SHA-256') %}"
}
Timestamp Comparison with $toMillis

JSONata timestamps are strings, so you can't compare them directly with < or >. Use $toMillis to convert to numeric milliseconds:

"Condition": "{% $toMillis($states.input.orderDate) > $toMillis($states.input.cutoffDate) %}"

Useful for sorting timestamps, calculating durations, or finding the most recent entry:

"Assign": {
  "ageMinutes": "{% $round(($toMillis($now()) - $toMillis($states.input.createdAt)) / 60000, 2) %}",
  "mostRecent": "{% $sort($states.input.timestamps, function($a, $b) { $toMillis($a) < $toMillis($b) })[0] %}"
}

Step Functions Built-in functions

FunctionPurpose
$partition(array, size)Partition array into chunks
$range(start, end, step)Generate array of values
$hash(data, algorithm)Calculate hash (MD5, SHA-1, SHA-256, SHA-384, SHA-512)
$random([seed])Random number 0 ≤ n < 1, optional seed
$uuid()Generate v4 UUID
$parse(jsonString)Deserialize JSON string

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
AWS Labs
Publisher
AWS Labs (Official)
Source
awslabs/agent-plugins · plugins/aws-serverless/skills/aws-step-functions · commit fbefb37
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • NOTICE (added by AutoGineer from NOTICE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by AWS Labs.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-step-functions.zip