{"id":"b9e8c50e-1304-408c-8b75-900d83cef0b6","shortId":"kAWa2Y","kind":"skill","title":"step-functions","tagline":"AWS Step Functions workflow orchestration with state machines. Use when designing workflows, implementing error handling, configuring parallel execution, integrating with AWS services, or debugging executions.","description":"# AWS Step Functions\n\nAWS Step Functions is a serverless orchestration service that lets you build and run workflows using state machines. Coordinate multiple AWS services into business-critical applications.\n\n## Table of Contents\n\n- [Core Concepts](#core-concepts)\n- [Common Patterns](#common-patterns)\n- [CLI Reference](#cli-reference)\n- [Best Practices](#best-practices)\n- [Troubleshooting](#troubleshooting)\n- [References](#references)\n\n## Core Concepts\n\n### Workflow Types\n\n| Type | Description | Pricing |\n|------|-------------|---------|\n| **Standard** | Long-running, durable, exactly-once | Per state transition |\n| **Express** | High-volume, short-duration | Per execution (time + memory) |\n\n### State Types\n\n| State | Description |\n|-------|-------------|\n| **Task** | Execute work (Lambda, API call) |\n| **Choice** | Conditional branching |\n| **Parallel** | Execute branches concurrently |\n| **Map** | Iterate over array |\n| **Wait** | Delay execution |\n| **Pass** | Pass input to output |\n| **Succeed** | End successfully |\n| **Fail** | End with failure |\n\n### Amazon States Language (ASL)\n\nJSON-based language for defining state machines.\n\n## Common Patterns\n\n### Simple Lambda Workflow\n\n```json\n{\n  \"Comment\": \"Process order workflow\",\n  \"StartAt\": \"ValidateOrder\",\n  \"States\": {\n    \"ValidateOrder\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:us-east-1:123456789012:function:ValidateOrder\",\n      \"Next\": \"ProcessPayment\"\n    },\n    \"ProcessPayment\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:us-east-1:123456789012:function:ProcessPayment\",\n      \"Next\": \"FulfillOrder\"\n    },\n    \"FulfillOrder\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:us-east-1:123456789012:function:FulfillOrder\",\n      \"End\": true\n    }\n  }\n}\n```\n\n### Create State Machine\n\n**AWS CLI:**\n\n```bash\naws stepfunctions create-state-machine \\\n  --name OrderWorkflow \\\n  --definition file://workflow.json \\\n  --role-arn arn:aws:iam::123456789012:role/StepFunctionsRole \\\n  --type STANDARD\n```\n\n**boto3:**\n\n```python\nimport boto3\nimport json\n\nsfn = boto3.client('stepfunctions')\n\ndefinition = {\n    \"Comment\": \"Order workflow\",\n    \"StartAt\": \"ProcessOrder\",\n    \"States\": {\n        \"ProcessOrder\": {\n            \"Type\": \"Task\",\n            \"Resource\": \"arn:aws:lambda:...\",\n            \"End\": True\n        }\n    }\n}\n\nresponse = sfn.create_state_machine(\n    name='OrderWorkflow',\n    definition=json.dumps(definition),\n    roleArn='arn:aws:iam::123456789012:role/StepFunctionsRole',\n    type='STANDARD'\n)\n```\n\n### Start Execution\n\n```python\nimport boto3\nimport json\n\nsfn = boto3.client('stepfunctions')\n\nresponse = sfn.start_execution(\n    stateMachineArn='arn:aws:states:us-east-1:123456789012:stateMachine:OrderWorkflow',\n    name='order-12345',\n    input=json.dumps({\n        'order_id': '12345',\n        'customer_id': 'cust-789',\n        'items': [{'product_id': 'prod-1', 'quantity': 2}]\n    })\n)\n\nexecution_arn = response['executionArn']\n```\n\n### Choice State (Conditional Logic)\n\n```json\n{\n  \"StartAt\": \"CheckOrderValue\",\n  \"States\": {\n    \"CheckOrderValue\": {\n      \"Type\": \"Choice\",\n      \"Choices\": [\n        {\n          \"Variable\": \"$.total\",\n          \"NumericGreaterThan\": 1000,\n          \"Next\": \"HighValueOrder\"\n        },\n        {\n          \"Variable\": \"$.priority\",\n          \"StringEquals\": \"rush\",\n          \"Next\": \"RushOrder\"\n        }\n      ],\n      \"Default\": \"StandardOrder\"\n    },\n    \"HighValueOrder\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:...:function:ProcessHighValue\",\n      \"End\": true\n    },\n    \"RushOrder\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:...:function:ProcessRush\",\n      \"End\": true\n    },\n    \"StandardOrder\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:...:function:ProcessStandard\",\n      \"End\": true\n    }\n  }\n}\n```\n\n### Parallel Execution\n\n```json\n{\n  \"StartAt\": \"ProcessInParallel\",\n  \"States\": {\n    \"ProcessInParallel\": {\n      \"Type\": \"Parallel\",\n      \"Branches\": [\n        {\n          \"StartAt\": \"UpdateInventory\",\n          \"States\": {\n            \"UpdateInventory\": {\n              \"Type\": \"Task\",\n              \"Resource\": \"arn:aws:lambda:...:function:UpdateInventory\",\n              \"End\": true\n            }\n          }\n        },\n        {\n          \"StartAt\": \"SendNotification\",\n          \"States\": {\n            \"SendNotification\": {\n              \"Type\": \"Task\",\n              \"Resource\": \"arn:aws:lambda:...:function:SendNotification\",\n              \"End\": true\n            }\n          }\n        },\n        {\n          \"StartAt\": \"UpdateAnalytics\",\n          \"States\": {\n            \"UpdateAnalytics\": {\n              \"Type\": \"Task\",\n              \"Resource\": \"arn:aws:lambda:...:function:UpdateAnalytics\",\n              \"End\": true\n            }\n          }\n        }\n      ],\n      \"Next\": \"Complete\"\n    },\n    \"Complete\": {\n      \"Type\": \"Succeed\"\n    }\n  }\n}\n```\n\n### Map State (Iteration)\n\n```json\n{\n  \"StartAt\": \"ProcessItems\",\n  \"States\": {\n    \"ProcessItems\": {\n      \"Type\": \"Map\",\n      \"ItemsPath\": \"$.items\",\n      \"MaxConcurrency\": 10,\n      \"Iterator\": {\n        \"StartAt\": \"ProcessItem\",\n        \"States\": {\n          \"ProcessItem\": {\n            \"Type\": \"Task\",\n            \"Resource\": \"arn:aws:lambda:...:function:ProcessItem\",\n            \"End\": true\n          }\n        }\n      },\n      \"ResultPath\": \"$.processedItems\",\n      \"End\": true\n    }\n  }\n}\n```\n\n### Error Handling\n\n```json\n{\n  \"StartAt\": \"ProcessWithRetry\",\n  \"States\": {\n    \"ProcessWithRetry\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:...:function:Process\",\n      \"Retry\": [\n        {\n          \"ErrorEquals\": [\"Lambda.ServiceException\", \"Lambda.TooManyRequestsException\"],\n          \"IntervalSeconds\": 2,\n          \"MaxAttempts\": 6,\n          \"BackoffRate\": 2\n        },\n        {\n          \"ErrorEquals\": [\"States.Timeout\"],\n          \"IntervalSeconds\": 5,\n          \"MaxAttempts\": 3,\n          \"BackoffRate\": 1.5\n        }\n      ],\n      \"Catch\": [\n        {\n          \"ErrorEquals\": [\"CustomError\"],\n          \"ResultPath\": \"$.error\",\n          \"Next\": \"HandleCustomError\"\n        },\n        {\n          \"ErrorEquals\": [\"States.ALL\"],\n          \"ResultPath\": \"$.error\",\n          \"Next\": \"HandleAllErrors\"\n        }\n      ],\n      \"End\": true\n    },\n    \"HandleCustomError\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"arn:aws:lambda:...:function:HandleCustom\",\n      \"End\": true\n    },\n    \"HandleAllErrors\": {\n      \"Type\": \"Fail\",\n      \"Error\": \"ProcessingFailed\",\n      \"Cause\": \"An error occurred during processing\"\n    }\n  }\n}\n```\n\n## CLI Reference\n\n### State Machine Management\n\n| Command | Description |\n|---------|-------------|\n| `aws stepfunctions create-state-machine` | Create state machine |\n| `aws stepfunctions update-state-machine` | Update definition |\n| `aws stepfunctions delete-state-machine` | Delete state machine |\n| `aws stepfunctions list-state-machines` | List state machines |\n| `aws stepfunctions describe-state-machine` | Get details |\n\n### Executions\n\n| Command | Description |\n|---------|-------------|\n| `aws stepfunctions start-execution` | Start execution |\n| `aws stepfunctions stop-execution` | Stop execution |\n| `aws stepfunctions describe-execution` | Get execution details |\n| `aws stepfunctions list-executions` | List executions |\n| `aws stepfunctions get-execution-history` | Get execution history |\n\n## Best Practices\n\n### Design\n\n- **Keep states focused** — one purpose per state\n- **Use meaningful state names**\n- **Implement comprehensive error handling**\n- **Use Parallel for independent tasks**\n- **Use Map for batch processing**\n\n### Performance\n\n- **Use Express workflows** for high-volume, short tasks\n- **Set appropriate timeouts**\n- **Limit Map concurrency** to avoid throttling\n- **Use SDK integrations** when possible (avoid Lambda wrapper)\n\n### Reliability\n\n- **Retry transient errors**\n- **Catch and handle specific errors**\n- **Use idempotent operations**\n- **Enable X-Ray tracing**\n\n### Cost Optimization\n\n- **Use Express for short workflows** (< 5 minutes)\n- **Combine related operations** to reduce transitions\n- **Use Wait states** instead of Lambda delays\n\n## Troubleshooting\n\n### Execution Failed\n\n```bash\n# Get execution history\naws stepfunctions get-execution-history \\\n  --execution-arn arn:aws:states:us-east-1:123456789012:execution:MyWorkflow:exec-123 \\\n  --query 'events[?type==`TaskFailed` || type==`ExecutionFailed`]'\n```\n\n### Lambda Timeout\n\n**Causes:**\n- Lambda running too long\n- Task timeout too short\n\n**Fix:**\n\n```json\n{\n  \"Type\": \"Task\",\n  \"Resource\": \"arn:aws:lambda:...\",\n  \"TimeoutSeconds\": 300,\n  \"HeartbeatSeconds\": 60\n}\n```\n\n### State Stuck\n\n**Check:**\n- Task state waiting for callback\n- Wait state not yet elapsed\n- Activity worker not responding\n\n### Invalid State Machine\n\n```bash\n# Validate definition\naws stepfunctions validate-state-machine-definition \\\n  --definition file://workflow.json\n```\n\n## References\n\n- [Step Functions Developer Guide](https://docs.aws.amazon.com/step-functions/latest/dg/)\n- [Step Functions API Reference](https://docs.aws.amazon.com/step-functions/latest/apireference/)\n- [Step Functions CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/stepfunctions/)\n- [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html)","tags":["step","functions","aws","agent","skills","itsmostafa","agent-skills","agentic-ai","claude-code","claude-skills","codex","coding-agents"],"capabilities":["skill","source-itsmostafa","skill-step-functions","topic-agent-skills","topic-agentic-ai","topic-aws","topic-claude-code","topic-claude-skills","topic-codex","topic-coding-agents"],"categories":["aws-agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/itsmostafa/aws-agent-skills/step-functions","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add itsmostafa/aws-agent-skills","source_repo":"https://github.com/itsmostafa/aws-agent-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1085 github stars · SKILL.md body (9,360 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-03T00:52:59.249Z","embedding":null,"createdAt":"2026-04-18T21:55:48.598Z","updatedAt":"2026-05-03T00:52:59.249Z","lastSeenAt":"2026-05-03T00:52:59.249Z","tsv":"'-1':332 '-123':770 '-12345':318 '-789':327 '/cli/latest/reference/stepfunctions/)':853 '/step-functions/latest/apireference/)':846 '/step-functions/latest/dg/)':839 '/step-functions/latest/dg/concepts-amazon-states-language.html)':859 '1':186,202,218,312,765 '1.5':520 '10':468 '1000':354 '12345':323 '123456789012':187,203,219,246,288,313,766 '2':334,508,512 '3':518 '300':797 '5':516,728 '6':510 '60':799 'activ':813 'amazon':151,854 'api':123,842 'applic':58 'appropri':688 'arn':180,196,212,242,243,270,285,306,336,369,380,391,415,429,443,477,498,540,758,759,793 'array':135 'asl':154 'avoid':694,701 'aw':4,24,29,32,52,181,197,213,227,230,244,271,286,307,370,381,392,416,430,444,478,499,541,565,574,582,591,600,611,618,625,633,640,750,760,794,823 'backoffr':511,519 'base':157 'bash':229,746,820 'batch':675 'best':77,80,649 'best-practic':79 'boto3':250,253,296 'boto3.client':257,300 'branch':127,130,407 'build':43 'busi':56 'business-crit':55 'call':124 'callback':807 'catch':521,708 'caus':552,779 'check':802 'checkordervalu':345,347 'choic':125,339,349,350 'cli':72,75,228,558,849 'cli-refer':74 'combin':730 'command':563,609 'comment':169,260 'common':67,70,163 'common-pattern':69 'complet':451,452 'comprehens':664 'concept':63,66,87 'concurr':131,692 'condit':126,341 'configur':19 'content':61 'coordin':50 'core':62,65,86 'core-concept':64 'cost':721 'creat':224,233,568,571 'create-state-machin':232,567 'critic':57 'cust':326 'custom':324 'customerror':523 'debug':27 'default':363 'defin':160 'definit':238,259,281,283,581,822,829,830 'delay':137,742 'delet':585,588 'delete-state-machin':584 'describ':603,628 'describe-execut':627 'describe-state-machin':602 'descript':91,118,564,610 'design':14,651 'detail':607,632 'develop':835 'docs.aws.amazon.com':838,845,852,858 'docs.aws.amazon.com/cli/latest/reference/stepfunctions/)':851 'docs.aws.amazon.com/step-functions/latest/apireference/)':844 'docs.aws.amazon.com/step-functions/latest/dg/)':837 'docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html)':857 'durabl':97 'durat':110 'east':185,201,217,311,764 'elaps':812 'enabl':716 'end':145,148,222,273,374,385,396,420,434,448,482,486,534,545 'error':17,488,525,531,550,554,665,707,712 'errorequ':504,513,522,528 'event':772 'exact':99 'exactly-onc':98 'exec':769 'execut':21,28,112,120,129,138,293,304,335,399,608,615,617,622,624,629,631,637,639,644,647,744,748,754,757,767 'execution-arn':756 'executionarn':338 'executionfail':776 'express':104,679,724 'fail':147,549,745 'failur':150 'fix':788 'focus':654 'fulfillord':207,208,221 'function':3,6,31,34,188,204,220,372,383,394,418,432,446,480,501,543,834,841,848 'get':606,630,643,646,747,753 'get-execution-histori':642,752 'guid':836 'handl':18,489,666,710 'handleallerror':533,547 'handlecustom':544 'handlecustomerror':527,536 'heartbeatsecond':798 'high':106,683 'high-volum':105,682 'highvalueord':356,365 'histori':645,648,749,755 'iam':245,287 'id':322,325,330 'idempot':714 'implement':16,663 'import':252,254,295,297 'independ':670 'input':141,319 'instead':739 'integr':22,698 'intervalsecond':507,515 'invalid':817 'item':328,466 'itemspath':465 'iter':133,457,469 'json':156,168,255,298,343,400,458,490,789 'json-bas':155 'json.dumps':282,320 'keep':652 'lambda':122,166,182,198,214,272,371,382,393,417,431,445,479,500,542,702,741,777,780,795 'lambda.serviceexception':505 'lambda.toomanyrequestsexception':506 'languag':153,158,856 'let':41 'limit':690 'list':594,597,636,638 'list-execut':635 'list-state-machin':593 'logic':342 'long':95,783 'long-run':94 'machin':11,49,162,226,235,278,561,570,573,579,587,590,596,599,605,819,828 'manag':562 'map':132,455,464,673,691 'maxattempt':509,517 'maxconcurr':467 'meaning':660 'memori':114 'minut':729 'multipl':51 'myworkflow':768 'name':236,279,316,662 'next':190,206,355,361,450,526,532 'numericgreaterthan':353 'occur':555 'one':655 'oper':715,732 'optim':722 'orchestr':8,38 'order':171,261,317,321 'orderworkflow':237,280,315 'output':143 'parallel':20,128,398,406,668 'pass':139,140 'pattern':68,71,164 'per':101,111,657 'perform':677 'possibl':700 'practic':78,81,650 'price':92 'prioriti':358 'process':170,502,557,676 'processeditem':485 'processhighvalu':373 'processingfail':551 'processinparallel':402,404 'processitem':460,462,471,473,481 'processord':264,266 'processpay':191,192,205 'processrush':384 'processstandard':395 'processwithretri':492,494 'prod':331 'product':329 'purpos':656 'python':251,294 'quantiti':333 'queri':771 'ray':719 'reduc':734 'refer':73,76,84,85,559,832,843,850 'relat':731 'reliabl':704 'resourc':179,195,211,269,368,379,390,414,428,442,476,497,539,792 'respond':816 'respons':275,302,337 'resultpath':484,524,530 'retri':503,705 'role':241 'role-arn':240 'role/stepfunctionsrole':247,289 'rolearn':284 'run':45,96,781 'rush':360 'rushord':362,376 'sdk':697 'sendnotif':423,425,433 'serverless':37 'servic':25,39,53 'set':687 'sfn':256,299 'sfn.create':276 'sfn.start':303 'short':109,685,726,787 'short-dur':108 'simpl':165 'skill' 'skill-step-functions' 'source-itsmostafa' 'specif':711 'standard':93,249,291 'standardord':364,387 'start':292,614,616 'start-execut':613 'startat':173,263,344,401,408,422,436,459,470,491 'state':10,48,102,115,117,152,161,175,225,234,265,277,308,340,346,403,410,424,438,456,461,472,493,560,569,572,578,586,589,595,598,604,653,658,661,738,761,800,804,809,818,827,855 'statemachin':314 'statemachinearn':305 'states.all':529 'states.timeout':514 'step':2,5,30,33,833,840,847 'step-funct':1 'stepfunct':231,258,301,566,575,583,592,601,612,619,626,634,641,751,824 'stop':621,623 'stop-execut':620 'stringequ':359 'stuck':801 'succeed':144,454 'success':146 'tabl':59 'task':119,178,194,210,268,367,378,389,413,427,441,475,496,538,671,686,784,791,803 'taskfail':774 'throttl':695 'time':113 'timeout':689,778,785 'timeoutsecond':796 'topic-agent-skills' 'topic-agentic-ai' 'topic-aws' 'topic-claude-code' 'topic-claude-skills' 'topic-codex' 'topic-coding-agents' 'total':352 'trace':720 'transient':706 'transit':103,735 'troubleshoot':82,83,743 'true':223,274,375,386,397,421,435,449,483,487,535,546 'type':89,90,116,177,193,209,248,267,290,348,366,377,388,405,412,426,440,453,463,474,495,537,548,773,775,790 'updat':577,580 'update-state-machin':576 'updateanalyt':437,439,447 'updateinventori':409,411,419 'us':184,200,216,310,763 'us-east':183,199,215,309,762 'use':12,47,659,667,672,678,696,713,723,736 'valid':821,826 'validate-state-machine-definit':825 'validateord':174,176,189 'variabl':351,357 'volum':107,684 'wait':136,737,805,808 'work':121 'worker':814 'workflow':7,15,46,88,167,172,262,680,727 'workflow.json':239,831 'wrapper':703 'x':718 'x-ray':717 'yet':811","prices":[{"id":"acf5e45c-f095-4b00-abc6-6836703db100","listingId":"b9e8c50e-1304-408c-8b75-900d83cef0b6","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"itsmostafa","category":"aws-agent-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:55:48.598Z"}],"sources":[{"listingId":"b9e8c50e-1304-408c-8b75-900d83cef0b6","source":"github","sourceId":"itsmostafa/aws-agent-skills/step-functions","sourceUrl":"https://github.com/itsmostafa/aws-agent-skills/tree/main/skills/step-functions","isPrimary":false,"firstSeenAt":"2026-04-18T21:55:48.598Z","lastSeenAt":"2026-05-03T00:52:59.249Z"}],"details":{"listingId":"b9e8c50e-1304-408c-8b75-900d83cef0b6","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"itsmostafa","slug":"step-functions","github":{"repo":"itsmostafa/aws-agent-skills","stars":1085,"topics":["agent-skills","agentic-ai","aws","claude-code","claude-skills","codex","coding-agents"],"license":"mit","html_url":"https://github.com/itsmostafa/aws-agent-skills","pushed_at":"2026-04-27T09:45:24Z","description":"AWS Skills for Agents","skill_md_sha":"6b7e67495b83edb21547683f124de30bb649a585","skill_md_path":"skills/step-functions/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/itsmostafa/aws-agent-skills/tree/main/skills/step-functions"},"layout":"multi","source":"github","category":"aws-agent-skills","frontmatter":{"name":"step-functions","description":"AWS Step Functions workflow orchestration with state machines. Use when designing workflows, implementing error handling, configuring parallel execution, integrating with AWS services, or debugging executions."},"skills_sh_url":"https://skills.sh/itsmostafa/aws-agent-skills/step-functions"},"updatedAt":"2026-05-03T00:52:59.249Z"}}