Official agent skill

AWS Step Functions

Build workflows with AWS Step Functions state machines using the JSONata query language.

OfficialApache-2.0Auto-check passedData & Analytics

Install AWS Step Functions

skills CLI

$ npx skills add awslabs/agent-plugins --skill aws-step-functions -a claude-code

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

GitHub CLI

$ gh skill install awslabs/agent-plugins aws-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/awslabs/agent-plugins.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/aws-serverless/skills/aws-step-functions .claude/skills/aws-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/

Paste into Claude Code

Install the "aws-step-functions" agent skill from https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions into .claude/skills/aws-step-functions/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aws-step-functions", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add awslabs/agent-plugins --skill aws-step-functions -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install awslabs/agent-plugins aws-step-functions --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/awslabs/agent-plugins.git skills-src && mkdir -p .agents/skills && cp -r skills-src/plugins/aws-serverless/skills/aws-step-functions .agents/skills/aws-step-functions && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "aws-step-functions" agent skill from https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions into .agents/skills/aws-step-functions/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aws-step-functions", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add awslabs/agent-plugins --skill aws-step-functions -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install awslabs/agent-plugins aws-step-functions --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/awslabs/agent-plugins.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/plugins/aws-serverless/skills/aws-step-functions .cursor/skills/aws-step-functions && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "aws-step-functions" agent skill from https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions into .cursor/skills/aws-step-functions/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aws-step-functions", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/awslabs/agent-plugins.git --path plugins/aws-serverless/skills/aws-step-functions

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add awslabs/agent-plugins --skill aws-step-functions -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install awslabs/agent-plugins aws-step-functions --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/awslabs/agent-plugins.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/plugins/aws-serverless/skills/aws-step-functions .gemini/skills/aws-step-functions && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "aws-step-functions" agent skill from https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions into .gemini/skills/aws-step-functions/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aws-step-functions", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install awslabs/agent-plugins aws-step-functions

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add awslabs/agent-plugins --skill aws-step-functions -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/awslabs/agent-plugins.git skills-src && mkdir -p .github/skills && cp -r skills-src/plugins/aws-serverless/skills/aws-step-functions .github/skills/aws-step-functions && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "aws-step-functions" agent skill from https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions into .github/skills/aws-step-functions/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aws-step-functions", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add awslabs/agent-plugins --skill aws-step-functions -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install awslabs/agent-plugins aws-step-functions --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/awslabs/agent-plugins.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/plugins/aws-serverless/skills/aws-step-functions .opencode/skills/aws-step-functions && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "aws-step-functions" agent skill from https://github.com/awslabs/agent-plugins/tree/main/plugins/aws-serverless/skills/aws-step-functions into .opencode/skills/aws-step-functions/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aws-step-functions", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: aws-step-functions
GitHub stars: 915
Token cost: ~1.9k tokens
SKILL.md length: 648 words
Files: 16 (incl. references)
Skills in repo: 33
Repo updated: Oct 5, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

Build workflows with AWS Step Functions state machines using the JSONata query language.

Tasks that involve Data cleaning
SKILL.md covers Overview, When to Load Reference Files, Quick Reference and Best Practices, plus 2 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

AWS Step Functions is an agent skill from awslabs/agent-plugins, published by the product's own GitHub organization. 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.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 17 other files, including reference files (for example `examples/compensation-saga-pattern.asl.json`, `examples/express-standard-handoff.asl.json` and `examples/human-in-the-loop-with-timeout-escalation.asl.json`).

It sits in Data & Analytics, covering Data cleaning. It works with Amazon Web Services and Amazon DynamoDB. The repository describes itself as: Agent Plugins for AWS equip AI coding agents with the skills to help you architect, deploy, and operate on AWS. The licence is Apache-2.0.

When your agent uses it

Tasks that involve Data cleaning

Example prompts

“/aws-step-functions”

What it can do on your machine

Read from SKILL.md and the folder at commit da51970. 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
No scripts in the folder and no shell commands in SKILL.md (its code samples are json).
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):
- states-language.net
- docs.jsonata.org
- 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

AWS Step Functions loads about 1.9k tokens when it runs, and up to ~20k if it reads all its reference files. Until then it costs about 76 tokens; SKILL.md has 648 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~76
When it runs · the whole SKILL.md, loaded when a task matches: ~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~20k

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 awslabs/agent-plugins at commit da51970, republished under its Apache-2.0 licence (© awslabs). 648 words, ~1,897 tokens.

Download SKILL.mdSave it as .claude/skills/aws-step-functions/SKILL.md (or your agent's skills folder). This skill also uses 15 other files; get the full folder from GitHub.

name: aws-step-functions
description: 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.
argument-hint: [what workflow are you building?]

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

	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.

Show full SKILL.md (288 more words)Show less

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:

json

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

Or per-state to migrate from JSONPath incrementally:

json

{ "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

SKILL.md and 15 other files (references) in plugins/aws-serverless/skills/aws-step-functions of awslabs/agent-plugins.

SKILL.md
examples/compensation-saga-pattern.asl.json
examples/express-standard-handoff.asl.json
examples/human-in-the-loop-with-timeout-escalation.asl.json
examples/nested-map-parallel-structures.asl.json
examples/polling-loop-wait-check-choice.asl.json
examples/scatter-gather-with-partial-results.asl.json
examples/semaphore-concurrency-lock.asl.json
references/architecture-patterns.md
references/asl-state-types.md
references/error-handling.md
references/migrating-from-jsonpath-to-jsonata.md
references/processing-state-inputs-and-outputs.md
references/service-integrations.md
references/transforming-data.md
references/validation-and-testing.md

Open the folder on GitHubat commit da51970

Compare with similar skills

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

AWS Step Functions compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
AWS Step Functions this skillawslabs/agent-plugins	915	—	~1.9k	Automated safety check: Pass	Apache-2.0	2 days ago
AWS Step Functionsaws/agent-toolkit-for-aws	2.8k	—	~3.4k	Automated safety check: Pass	Apache-2.0	today
AWS Storageaws/agent-toolkit-for-aws	2.8k	—	~5.8k	Automated safety check: Pass	Apache-2.0	today
AWS Architecture Diagramvidanov/aws-architecture-diagram-skill	159	—	~4.4k	Automated safety check: Pass	MIT	4 days ago
AWS SDK JS V3 Usageaws/agent-toolkit-for-aws	2.8k	—	~2.2k	Automated safety check: Pass	Apache-2.0	today
Querying AWS Sagemaker Catalogaws/agent-toolkit-for-aws	2.8k	—	~2.6k	Automated safety check: Pass	Apache-2.0	today

Similar skills

AWS Step Functions
aws/agent-toolkit-for-aws
Official
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).
2.8k GitHub stars~3.4k tokensUpdated today
Backend & APIsAuto-check passed
AWS Storage
aws/agent-toolkit-for-aws
Official
Selects, investigates, and compares AWS object, file, and block storage services, and answers cost, performance, configuration, security, and troubleshooting questions about storage services.
2.8k GitHub stars~5.8k tokensUpdated today
DatabasesAuto-check passed
AWS Architecture Diagram
vidanov/aws-architecture-diagram-skill
Always use when user asks to create, generate, or build an AWS architecture diagram, cloud infrastructure diagram, or system diagram with AWS services.
159 GitHub stars~4.4k tokensUpdated 4 days ago
DevOps & CloudAuto-check passed
AWS SDK JS V3 Usage
aws/agent-toolkit-for-aws
Official
AWS SDK for JavaScript v3 development patterns. An agent skill from aws/agent-toolkit-for-aws.
2.8k GitHub stars~2.2k tokensUpdated today
DatabasesAuto-check passed
Querying AWS Sagemaker Catalog
aws/agent-toolkit-for-aws
Official
Runs SQL analytics on SageMaker Catalog asset metadata tables exported as Apache Iceberg in S3 Tables.
2.8k GitHub stars~2.6k tokensUpdated today
Data & AnalyticsAuto-check passed
AWS Database
aws/agent-toolkit-for-aws
Official
Routes any task involving AWS databases — choosing, comparing, recommending, getting started with, or operating a database — to the correct service-specific skill.
2.8k GitHub stars~2k tokensUpdated today
DatabasesAuto-check passed

Questions about AWS Step Functions

What does AWS Step Functions do?

Build workflows with AWS Step Functions state machines using the JSONata query language. AWS Step Functions is an agent skill from awslabs/agent-plugins, published by the product's own GitHub organization. Build workflows with AWS Step Functions state machines using the JSONata query language.

When should I use AWS Step Functions?

AWS Step Functions fits situations like: tasks that involve Data cleaning.

How do I install AWS Step Functions in Claude Code?

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

How do I install AWS Step Functions in Codex?

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

Can I use AWS 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 awslabs/agent-plugins --skill aws-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/aws-step-functions, .gemini/skills/aws-step-functions, .github/skills/aws-step-functions and .opencode/skills/aws-step-functions in your project.

What does AWS Step Functions need to run?

SKILL.md names no scripts, command-line tools or credentials: AWS Step Functions is instructions for the agent only.

Does AWS Step Functions access the network?

SKILL.md names 3 domains. As links in the text: states-language.net, docs.jsonata.org and docs.aws.amazon.com. This is read from the text; nothing was executed.

Is AWS 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 AWS Step Functions use?

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

How many tokens does AWS Step Functions use?

About 1.9k tokens (SKILL.md is roughly 7.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 18k tokens, read only when the agent opens those files.

What are the alternatives to AWS Step Functions?

Skills that share tags, products or a category with AWS Step Functions: AWS Step Functions (aws/agent-toolkit-for-aws, 2.8k stars), AWS Storage (aws/agent-toolkit-for-aws, 2.8k stars), AWS Architecture Diagram (vidanov/aws-architecture-diagram-skill, 159 stars) and AWS SDK JS V3 Usage (aws/agent-toolkit-for-aws, 2.8k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains AWS Step Functions?

awslabs (a GitHub organization, an official publisher) maintains it in awslabs/agent-plugins, which has 915 GitHub stars. The repository holds 33 skills in this directory. The repository was last updated on October 5, 2026.

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

Install AWS Step Functions

Facts

At a glance

What it does

When your agent uses it

Example prompts

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

AWS Step Functions

Overview

When to Load Reference Files

Quick Reference

Standard vs Express Workflows

Setting the State Machine Query Language

Best Practices

Troubleshooting

Common Errors

Resources

Files

Compare with similar skills

Similar skills

More from awslabs/agent-plugins

Related

Questions about AWS Step Functions