Agent skill

Step Functions

by itsmostafa in itsmostafa/aws-agent-skills

AWS Step Functions workflow orchestration with state machines.

MITAuto-check passedDevelopment

Install Step Functions

skills CLI
$ npx skills add itsmostafa/aws-agent-skills --skill step-functions -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install itsmostafa/aws-agent-skills step-functions --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/itsmostafa/aws-agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/step-functions .claude/skills/step-functions && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
step-functions
GitHub stars
1.2k
Token cost
~2.4k tokens
SKILL.md length
338 words
Files
2
Skills in repo
17
Repo updated
First seen
Licence
MIT

At a glance

AWS Step Functions workflow orchestration with state machines.

  • Designing workflows
  • SKILL.md covers Table of Contents, Core Concepts, Common Patterns and CLI Reference, plus 3 more sections
  • Calls aws
  • Implementing error handling

What it does

Step Functions is an agent skill from itsmostafa/aws-agent-skills. 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.

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `workflow-patterns.md`).

It sits in Development, covering Error handling. It works with Amazon Web Services. The repository describes itself as: AWS Skills for Agents. The licence is MIT.

When your agent uses it

  • Designing workflows
  • Implementing error handling
  • Configuring parallel execution
  • Integrating with AWS services

Example prompts

  • “/step-functions”

Requirements

  • Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit e786d25. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • aws

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • docs.aws.amazon.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Step Functions loads about 2.4k tokens when it runs. Until then it costs about 56 tokens; SKILL.md has 338 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~56
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from itsmostafa/aws-agent-skills at commit e786d25, republished under its MIT licence (© itsmostafa). 338 words, ~2,427 tokens.

Download SKILL.mdSave it as .claude/skills/step-functions/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
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.
last_updated
2026-01-07
doc_source
https://docs.aws.amazon.com/step-functions/latest/dg/

AWS Step Functions

AWS 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.

Table of Contents

Core Concepts

Workflow Types
TypeDescriptionPricing
StandardLong-running, durable, exactly-oncePer state transition
ExpressHigh-volume, short-durationPer execution (time + memory)
State Types
StateDescription
TaskExecute work (Lambda, API call)
ChoiceConditional branching
ParallelExecute branches concurrently
MapIterate over array
WaitDelay execution
PassPass input to output
SucceedEnd successfully
FailEnd with failure
Amazon States Language (ASL)

JSON-based language for defining state machines.

Common Patterns

Simple Lambda Workflow
json
{
  "Comment": "Process order workflow",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:ValidateOrder",
      "Next": "ProcessPayment"
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:ProcessPayment",
      "Next": "FulfillOrder"
    },
    "FulfillOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FulfillOrder",
      "End": true
    }
  }
}
Create State Machine

AWS CLI:

bash
aws stepfunctions create-state-machine \
  --name OrderWorkflow \
  --definition file://workflow.json \
  --role-arn arn:aws:iam::123456789012:role/StepFunctionsRole \
  --type STANDARD

boto3:

python
import boto3
import json

sfn = boto3.client('stepfunctions')

definition = {
    "Comment": "Order workflow",
    "StartAt": "ProcessOrder",
    "States": {
        "ProcessOrder": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:...",
            "End": True
        }
    }
}

response = sfn.create_state_machine(
    name='OrderWorkflow',
    definition=json.dumps(definition),
    roleArn='arn:aws:iam::123456789012:role/StepFunctionsRole',
    type='STANDARD'
)
Start Execution
python
import boto3
import json

sfn = boto3.client('stepfunctions')

response = sfn.start_execution(
    stateMachineArn='arn:aws:states:us-east-1:123456789012:stateMachine:OrderWorkflow',
    name='order-12345',
    input=json.dumps({
        'order_id': '12345',
        'customer_id': 'cust-789',
        'items': [{'product_id': 'prod-1', 'quantity': 2}]
    })
)

execution_arn = response['executionArn']
Choice State (Conditional Logic)
json
{
  "StartAt": "CheckOrderValue",
  "States": {
    "CheckOrderValue": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.total",
          "NumericGreaterThan": 1000,
          "Next": "HighValueOrder"
        },
        {
          "Variable": "$.priority",
          "StringEquals": "rush",
          "Next": "RushOrder"
        }
      ],
      "Default": "StandardOrder"
    },
    "HighValueOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessHighValue",
      "End": true
    },
    "RushOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessRush",
      "End": true
    },
    "StandardOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessStandard",
      "End": true
    }
  }
}
Parallel Execution
json
{
  "StartAt": "ProcessInParallel",
  "States": {
    "ProcessInParallel": {
      "Type": "Parallel",
      "Branches": [
        {
          "StartAt": "UpdateInventory",
          "States": {
            "UpdateInventory": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:UpdateInventory",
              "End": true
            }
          }
        },
        {
          "StartAt": "SendNotification",
          "States": {
            "SendNotification": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:SendNotification",
              "End": true
            }
          }
        },
        {
          "StartAt": "UpdateAnalytics",
          "States": {
            "UpdateAnalytics": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:UpdateAnalytics",
              "End": true
            }
          }
        }
      ],
      "Next": "Complete"
    },
    "Complete": {
      "Type": "Succeed"
    }
  }
}
Map State (Iteration)
json
{
  "StartAt": "ProcessItems",
  "States": {
    "ProcessItems": {
      "Type": "Map",
      "ItemsPath": "$.items",
      "MaxConcurrency": 10,
      "Iterator": {
        "StartAt": "ProcessItem",
        "States": {
          "ProcessItem": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:...:function:ProcessItem",
            "End": true
          }
        }
      },
      "ResultPath": "$.processedItems",
      "End": true
    }
  }
}
Error Handling
json
{
  "StartAt": "ProcessWithRetry",
  "States": {
    "ProcessWithRetry": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:Process",
      "Retry": [
        {
          "ErrorEquals": ["Lambda.ServiceException", "Lambda.TooManyRequestsException"],
          "IntervalSeconds": 2,
          "MaxAttempts": 6,
          "BackoffRate": 2
        },
        {
          "ErrorEquals": ["States.Timeout"],
          "IntervalSeconds": 5,
          "MaxAttempts": 3,
          "BackoffRate": 1.5
        }
      ],
      "Catch": [
        {
          "ErrorEquals": ["CustomError"],
          "ResultPath": "$.error",
          "Next": "HandleCustomError"
        },
        {
          "ErrorEquals": ["States.ALL"],
          "ResultPath": "$.error",
          "Next": "HandleAllErrors"
        }
      ],
      "End": true
    },
    "HandleCustomError": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:HandleCustom",
      "End": true
    },
    "HandleAllErrors": {
      "Type": "Fail",
      "Error": "ProcessingFailed",
      "Cause": "An error occurred during processing"
    }
  }
}

CLI Reference

State Machine Management
CommandDescription
aws stepfunctions create-state-machineCreate state machine
aws stepfunctions update-state-machineUpdate definition
aws stepfunctions delete-state-machineDelete state machine
aws stepfunctions list-state-machinesList state machines
aws stepfunctions describe-state-machineGet details
Executions
CommandDescription
aws stepfunctions start-executionStart execution
aws stepfunctions stop-executionStop execution
aws stepfunctions describe-executionGet execution details
aws stepfunctions list-executionsList executions
aws stepfunctions get-execution-historyGet execution history

Best Practices

Design
  • Keep states focused — one purpose per state
  • Use meaningful state names
  • Implement comprehensive error handling
  • Use Parallel for independent tasks
  • Use Map for batch processing
Performance
  • Use Express workflows for high-volume, short tasks
  • Set appropriate timeouts
  • Limit Map concurrency to avoid throttling
  • Use SDK integrations when possible (avoid Lambda wrapper)
Reliability
  • Retry transient errors
  • Catch and handle specific errors
  • Use idempotent operations
  • Enable X-Ray tracing
Cost Optimization
  • Use Express for short workflows (< 5 minutes)
  • Combine related operations to reduce transitions
  • Use Wait states instead of Lambda delays

Troubleshooting

Execution Failed
bash
# Get execution history
aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:us-east-1:123456789012:execution:MyWorkflow:exec-123 \
  --query 'events[?type==`TaskFailed` || type==`ExecutionFailed`]'
Lambda Timeout

Causes:

  • Lambda running too long
  • Task timeout too short

Fix:

json
{
  "Type": "Task",
  "Resource": "arn:aws:lambda:...",
  "TimeoutSeconds": 300,
  "HeartbeatSeconds": 60
}
State Stuck

Check:

  • Task state waiting for callback
  • Wait state not yet elapsed
  • Activity worker not responding
Invalid State Machine
bash
# Validate definition
aws stepfunctions validate-state-machine-definition \
  --definition file://workflow.json

References

© itsmostafa, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/step-functions of itsmostafa/aws-agent-skills.

  • SKILL.md
  • workflow-patterns.md

Open the folder on GitHubat commit e786d25

Compare with similar skills

Step Functions next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Step Functions compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Step Functions this skillitsmostafa/aws-agent-skills1.2k—~2.4kAutomated safety check: PassMIT
AWS Lambda Durable Functionsawslabs/agent-plugins915—~2.3kAutomated safety check: PassApache-2.0
AWS Lambda Durable Functionsaws/agent-toolkit-for-aws2.8k—~2.3kAutomated safety check: PassApache-2.0
Mole Bug Patternstw93/Mole70k—~2kAutomated safety check: PassGPL-3.0
Native Data FetchingCherryHQ/cherry-studio-app4k6 repos~2.9kAutomated safety check: NotesMIT
Rust Best Practicesfarm-fe/farm5.6k3 repos~1.1kAutomated safety check: PassMIT

Similar skills

  • AWS Lambda Durable Functions

    awslabs/agent-plugins

    Official

    Build resilient, long-running, multi-step applications with AWS Lambda durable functions with automatic state persistence, retry logic, and orchestration for long-running executions.

    915 GitHub stars~2.3k tokensUpdated yesterday
    Backend & APIsAuto-check passed
  • AWS Lambda Durable Functions

    aws/agent-toolkit-for-aws

    Official

    Builds resilient, long-running, multi-step applications with AWS Lambda durable functions with automatic state persistence, retry logic, and orchestration for long-running executions.

    2.8k GitHub stars~2.3k tokensUpdated today
    Backend & APIsAuto-check passed
  • A catalog of recurring bug shapes in the Mole Mac cleaner, used to review safety-sensitive diffs for deletion safety, unbounded commands, shell traps and weak tests.

    70k GitHub stars~2k tokensUpdated today
    DevelopmentAuto-check passed
  • Native Data Fetching

    CherryHQ/cherry-studio-app

    A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.

    4k GitHub starsUsed in 6 repos~2.9k tokens
    DevelopmentAuto-check: notes
  • Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook.

    5.6k GitHub starsUsed in 3 repos~1.1k tokens
    DevelopmentAuto-check passed
  • Validates arguments of exported R functions with the standalone check_* type checkers from rlang, in tidyverse style with clear error messages.

    5.1k GitHub starsUsed in 1 repo~2.3k tokens
    DevelopmentAuto-check passed

More from itsmostafa/aws-agent-skills

All 17 skills in this repo
  • Cognito

    itsmostafa/aws-agent-skills

    AWS Cognito user authentication and authorization service. An agent skill from itsmostafa/aws-agent-skills.

    1.2k GitHub starsUsed in 1 repo~2.3k tokens
    Auto-check passed
  • API Gateway

    itsmostafa/aws-agent-skills

    AWS API Gateway for REST and HTTP API management. An agent skill from itsmostafa/aws-agent-skills.

    1.2k GitHub stars~2.2k tokensUpdated 4 days ago
    Auto-check passed
  • Bedrock

    itsmostafa/aws-agent-skills

    AWS Bedrock foundation models for generative AI. An agent skill from itsmostafa/aws-agent-skills.

    1.2k GitHub stars~4.9k tokensUpdated 4 days ago
    Auto-check passed
  • Cloudformation

    itsmostafa/aws-agent-skills

    AWS CloudFormation infrastructure as code for stack management.

    1.2k GitHub stars~2.5k tokensUpdated 4 days ago
    Auto-check passed
  • Cloudwatch

    itsmostafa/aws-agent-skills

    AWS CloudWatch monitoring for logs, metrics, alarms, and dashboards.

    1.2k GitHub stars~3.5k tokensUpdated 4 days ago
    Auto-check passed
  • Dynamodb

    itsmostafa/aws-agent-skills

    AWS DynamoDB NoSQL database for scalable data storage. An agent skill from itsmostafa/aws-agent-skills.

    1.2k GitHub stars~2.5k tokensUpdated 4 days ago
    Auto-check passed

Categories

Questions about Step Functions

What does Step Functions do?

AWS Step Functions workflow orchestration with state machines. Step Functions is an agent skill from itsmostafa/aws-agent-skills. AWS Step Functions workflow orchestration with state machines.

When should I use Step Functions?

Step Functions fits situations like: designing workflows; implementing error handling; configuring parallel execution; integrating with AWS services.

How do I install Step Functions in Claude Code?

Run `npx skills add itsmostafa/aws-agent-skills --skill step-functions -a claude-code`. Or copy the skill folder (skills/step-functions in itsmostafa/aws-agent-skills) into .claude/skills/step-functions in your project. Claude Code loads it when a task matches its description.

How do I install Step Functions in Codex?

Run `npx skills add itsmostafa/aws-agent-skills --skill step-functions -a codex`. Or copy the skill folder (skills/step-functions in itsmostafa/aws-agent-skills) into .agents/skills/step-functions in your project. Codex loads it when a task matches its description.

Can I use Step Functions in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add itsmostafa/aws-agent-skills --skill step-functions -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/step-functions, .gemini/skills/step-functions, .github/skills/step-functions and .opencode/skills/step-functions in your project.

What does Step Functions need to run?

Going by SKILL.md and its folder, Step Functions needs the command-line tools its instructions call (aws). Our summary lists: Python 3.

Does Step Functions access the network?

SKILL.md names 1 domain. As links in the text: docs.aws.amazon.com. This is read from the text; nothing was executed.

Is Step Functions safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Step Functions use?

Step Functions is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Step Functions use?

About 2.4k tokens (SKILL.md is roughly 9.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Step Functions?

Skills that share tags, products or a category with Step Functions: AWS Lambda Durable Functions (awslabs/agent-plugins, 915 stars), AWS Lambda Durable Functions (aws/agent-toolkit-for-aws, 2.8k stars), Mole Bug Patterns (tw93/Mole, 70k stars) and Native Data Fetching (CherryHQ/cherry-studio-app, 4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Step Functions?

itsmostafa (a GitHub user) maintains it in itsmostafa/aws-agent-skills, which has 1,162 GitHub stars. The repository holds 17 skills in this directory. The repository was last updated on October 5, 2026.

Source: itsmostafa/aws-agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.