stepfunctions-express-deployer
Provisions Step Functions Express Workflows with production defaults: Express-vs-Standard decision (5-min cap, at-least-once vs exactly-once, per-invocation vs per-transition pricing), sync (RequestResponse) vs async invocation, CloudWatch Logs configuration (ALL / ERROR / FATAL / OFF levels and INCLUDE_DATA / EXCLUDE_DATA), IAM least-privilege execution role, EventBridge scheduling, Distributed Map and Inline Map fan-out, Express-compatible service integrations (.sync, AWS SDK direct calls), idempotency for at-least-once delivery, observability (metrics, X-Ray, CloudWatch alarms). Emits READY_TO_DEPLOY / PREREQUISITES_MISSING with copy-pasteable stepfunctions / logs / events / iam CLI. Use when provisioning an Express workflow, migrating high-volume Standard workloads to Express, configuring sync invocation from API Gateway, or hardening logging. Triggers: Express workflow, create state machine EXPRESS, sync express, async express, EventBridge Step Functions, Step Functions logging, Distributed Map Express.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-24
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- stepfunctions-express-deployer
- license
- Apache-2.0
- metadata
- { "tags": "aws, step-functions, express-workflow, state-machine, sync-execution, logging, eventbridge, deploy, app-integration", "phase": "1", "author": "Jacky Chan — AWS Community Builder", "domain": "aws-cloudops", "family": "AppIntegration", "version": "0.1.0", "keywords": "aws, step-functions, stepfunctions, express-workflow, state-machine, asl, amazon-states-language, sync-execution, requestresponse, async-execution, cloudwatch-logs, include-data, exclude-data, eventbridge, distributed-map, inline-map, sync-integration, waitfortasktoken, idempotency, at-least-once, iam-execution-role, x-ray, cloudops, deploy", "task_type": "deploy", "complexity": "high", "entry_point": "false", "skill_class": "capability", "when_to_use": "Provisioning a new Step Functions Express Workflow, deciding between Express and Standard (5-min cap, at-least-once semantics, per-invocation pricing), configuring sync (RequestResponse) vs async invocation, attaching a CloudWatch Logs log group with the correct level (ALL / ERROR / FATAL / OFF) and INCLUDE_DATA / EXCLUDE_DATA exposure, scheduling recurring Express executions via EventBridge, using Distributed Map or Inline Map with Express, using .sync service integrations (Glue, Batch, ECS, SageMaker), or hardening idempotency for at-least-once delivery. Do NOT invoke for Standard workflows that run >5 minutes or use .waitForTaskToken (use stepfunctions-statemachine-deployer), or for troubleshooting execution failures (use stepfunctions-execution-troubleshooter).", "dependencies": "aws-orchestrator", "requires_llm": "true", "verdict_shape": "READY_TO_DEPLOY | PREREQUISITES_MISSING", "lifecycle_status": "active", "invocation_schema": "Input: either (a) a workflow name + ASL definition (or requirements to derive one) + sync/async invocation mode, or (b) a Standard-to-Express migration spec (existing state machine ARN + compatibility check), or (c) an EventBridge-scheduled Express spec (schedule expression + execution role). Output: deterministic EXPRESS_WORKFLOW / VERDICT / CHECKLIST / VERIFICATION_COMMANDS block per the STRICT output contract, where VERDICT is READY_TO_DEPLOY or PREREQUISITES_MISSING.", "supports_pipeline": "true", "activation_triggers": "Express workflow, create Express state machine, Step Functions EXPRESS, sync express execution, start-sync-execution, async express, Express workflow logging, Step Functions CloudWatch Logs, INCLUDE_DATA, EXCLUDE_DATA, EventBridge Step Functions, Distributed Map Express, Standard-to-Express migration, Express idempotency" }
- description
- Provisions Step Functions Express Workflows with production defaults: Express-vs-Standard decision (5-min cap, at-least-once vs exactly-once, per-invocation vs per-transition pricing), sync (RequestResponse) vs async invocation, CloudWatch Logs configuration (ALL / ERROR / FATAL / OFF levels and INCLUDE_DATA / EXCLUDE_DATA), IAM least-privilege execution role, EventBridge scheduling, Distributed Map and Inline Map fan-out, Express-compatible service integrations (.sync, AWS SDK direct calls), idempotency for at-least-once delivery, observability (metrics, X-Ray, CloudWatch alarms). Emits READY_TO_DEPLOY / PREREQUISITES_MISSING with copy-pasteable stepfunctions / logs / events / iam CLI. Use when provisioning an Express workflow, migrating high-volume Standard workloads to Express, configuring sync invocation from API Gateway, or hardening logging. Triggers: Express workflow, create state machine EXPRESS, sync express, async express, EventBridge Step Functions, Step Functions logging, Distributed Map Express.
- compatibility
- Agent runtime that reads SKILL.md (Claude Code, Cursor, Windsurf, Codex, Gemini). Live provisioning uses AWS CLI v2 with stepfunctions (create-state-machine, update-state-machine, describe-state-machine, start-sync-execution, start-execution, validate-state-machine-definition), logs (create-log-group, put-retention-policy), events (put-rule, put-targets), iam (create-role, attach-role-policy, put-role-policy), and cloudformation / terraform aws_sfn_state_machine equivalents.
02 资源文件 21
- 参考文档eval/test-cases.yaml6.4 KB
- 参考文档evals/baselines/express-distributed-map-logging.md1.2 KB
- 参考文档evals/baselines/express-idempotency-for-at-least-once.md1.2 KB
- 参考文档evals/baselines/missing-logging-on-async.md1.1 KB
- 参考文档evals/baselines/standard-migration-waitfortasktoken.md1.1 KB
- 参考文档evals/baselines/sync-apigateway-timeout-alignment.md1.0 KB
- 参考文档evals/eval_config.yaml1.9 KB
- 参考文档evals/evals.json12.9 KB
- 参考文档evals/prompts/express-distributed-map-logging.md884 B
- 参考文档evals/prompts/express-idempotency-for-at-least-once.md689 B
- 参考文档evals/prompts/missing-logging-on-async.md515 B
- 参考文档evals/prompts/standard-migration-waitfortasktoken.md621 B
- 参考文档evals/prompts/sync-apigateway-timeout-alignment.md668 B
- 参考文档example/README.md7.8 KB
- 参考文档references/advanced-patterns.md5.9 KB
- 参考文档references/diagnostic-commands.md1.6 KB
- 参考文档references/express-asl-patterns.md7.9 KB
- 参考文档references/iam-and-logging-templates.md8.2 KB
- 参考文档references/scheduling-and-observability.md1.7 KB
- 参考文档references/worked-examples.md2.5 KB
- 参考文档skill.usf.yaml4.5 KB
03 SKILL.md 正文
Step Functions Express Workflows Deployer
What this skill does
Provisions Step Functions Express Workflows and surrounding
primitives (CloudWatch Logs with correct level and data-exposure,
IAM least-privilege execution role, EventBridge scheduling,
Distributed Map configuration, idempotency guard for at-least-once
delivery) with production defaults. The skill walks a 9-step
procedure, surfaces the silent-failure modes unique to Express
(most dangerous: .waitForTaskToken is rejected at create-time,
but operators migrating from Standard discover this only on deploy;
logging is NOT enabled by default, so async Express executions are
invisible after the 5-minute history window; the at-least-once
delivery model means non-idempotent Lambda handlers can double-
execute on retries). The single most common incident this skill
prevents: an operator migrates a high-volume Standard workflow to
Express for cost savings, the migration drops CloudWatch Logs, and
the first failed execution is invisible — no alarm, no log, and the
5-minute execution history has already rolled over.
Quick navigation
| Section | What it covers | When to read it |
|---|---|---|
| Quick reference | Provisioning summary (9 steps), verdict thresholds | Before any operation |
| Activation keywords | Phrases that route to this skill | Disambiguating routing |
| Reasoning framework | Why Express is a cost + semantics decision | Choosing Express vs Standard |
| Dependency graph | Which configs silently no-op without their prerequisite | Debugging "logs are empty" |
| Expert heuristic | waitForTaskToken block; at-least-once idempotency; sync API Gateway timeouts | Pre-empt incidents |
| Prerequisites | What to verify before emitting any command | Avoid PREREQUISITES_MISSING rework |
| 9-step procedure | The actual provisioning with copy-pasteable CLI | Executing the deploy |
| NEVER (top 5) | Hard rules that prevent silent exposure / data-plane bugs | Review before deploy |
| STRICT output contract | Required EXPRESS_WORKFLOW / VERDICT / CHECKLIST / VERIFICATION_COMMANDS block | Formatting the response |
| Recent AWS features | Express + Distributed Map, AWS SDK direct calls | Stay current |
Quick reference — provisioning summary (9 steps)
| Step | Action | Reversible? | Key risk if skipped |
|---|---|---|---|
| 1 | Confirm Express-vs-Standard decision (5-min cap, at-least-once, cost model) | — | wrong type = 100x cost or 5-min timeout |
| 2 | Verify workflow duration fits in the 5-minute Express cap | Yes | sync API Gateway returns 500; async retried mid-flight |
| 3 | Verify all service integrations are Express-compatible (NO .waitForTaskToken) |
Yes | create-state-machine API silently rejects the definition |
| 4 | Define the ASL with Express-compatible patterns (Distributed Map, .sync, AWS SDK) | Yes | — |
| 5 | Create the IAM execution role with least-privilege | Yes | over-broad states:* on * |
| 6 | Configure logging (CloudWatch Logs + level + INCLUDE_DATA/EXCLUDE_DATA) | Yes | async executions invisible after 5-min history |
| 7 | Choose sync (RequestResponse) vs async invocation mode | Yes | sync API Gateway timeout misalignment |
| 8 | Configure EventBridge scheduling + observability (X-Ray, CloudWatch alarms) | Yes | silent failures with no alarm |
| 9 | Verify every configuration item against actual state + emit checklist | — | silent no-ops |
Critical ordering constraints: Express-vs-Standard decision
first (every downstream choice depends on the type); duration
budget before ASL definition (a workflow that exceeds 5 minutes
cannot be Express); integration compatibility before the IAM role
(.waitForTaskToken rejected at create-time even with a valid
role); logging configuration before the first execution (without
logging, async Express executions are invisible after the 5-minute
history rolls over); sync-vs-async choice before the caller
integration (API Gateway sync requires timeout alignment to ≤ 29s
to avoid 504). Rationale and the silent-failure table are below.
Activation keywords
Express workflow, create Express state machine, Step Functions EXPRESS, sync express execution, start-sync-execution, async express, Express workflow logging, Step Functions CloudWatch Logs, INCLUDE_DATA, EXCLUDE_DATA, FATAL / ERROR / ALL levels, EventBridge Step Functions target, Distributed Map Express, Inline Map Express, Standard-to-Express migration, at-least-once Step Functions, Express idempotency, Express sync API Gateway, .sync integration Express, AWS SDK integration, X-Ray tracing Step Functions.
Invocation contract (hard requirement)
When this skill is invoked with an Express Workflow provisioning
request, the agent MUST respond with the checklist defined in
§"STRICT output contract" using the literal all-caps labels
EXPRESS_WORKFLOW:, VERDICT:, CHECKLIST:, and
VERIFICATION_COMMANDS:. Do NOT preface the checklist with prose,
headings, or disclaimers — emit the block as the first lines of the
response. This contract is what assertion-based evals and downstream
provisioning pipelines rely on; deviating from the literal labels
breaks automation silently.
Reasoning framework (why the Express decision matters)
Full detail moved verbatim to references/advanced-patterns.md - load on demand. Summary: full Express-vs-Standard reasoning prose; every branch is preserved in the Decision tree below.
Dependency graph (silent-failure table)
| Configuration | Hard dependencies (API error without) | Silent failure mode (returns 200, does nothing) | Enables downstream |
|---|---|---|---|
| Express state machine | unique name; valid ASL | .waitForTaskToken in ASL → API rejects with definition-validation error; operators misread as IAM error and keep re-applying |
— |
| CloudWatch Logs log group | log group exists in same account + region | log group ARN omitted at create-time → executions do not log; 5-min history rolls over and failure is invisible | observability |
| Log level (ALL / ERROR / FATAL / OFF) | log group attached | level set to OFF or FATAL only → execution-level errors invisible; operator sees empty log group | debuggability |
| INCLUDE_DATA / EXCLUDE_DATA | log group attached | EXCLUDE_DATA on a workflow that takes PII inputs → traces show only metadata, blocking RCA (or inverse: INCLUDE_DATA on PII → compliance violation) | input/output visibility |
| IAM execution role | trust policy allows states.<region>.amazonaws.com |
trust policy missing service principal → AccessDenied on first execution; not surfaced at create-time |
service integrations |
| Sync execution (start-sync-execution) | state machine type EXPRESS | calling start-sync-execution on a Standard state machine → error; but a caller using start-execution on Express works (just async) | API Gateway / direct sync |
| EventBridge target | execution role for EventBridge to assume | target without role → rule fires, no execution; EventBridge shows Invocations = 1, Step Functions shows Executions = 0 | scheduled recurring runs |
| Distributed Map | state machine type EXPRESS or STANDARD; IAM allows read on ItemReader source | Map state on Express with > 10,000-item fan-out hits 5-min cap → workflow fails mid-iteration with no progress signal | large-scale fan-out |
| .sync integration | supported service (Glue, Batch, ECS, SageMaker) | unsupported service in Resource ARN → API rejects; misread as syntax error | run-job-and-wait |
| AWS SDK integration | IAM allows the underlying SDK action | IAM allows lambda:InvokeFunction but the SDK integration calls lambda:UpdateFunctionCode → runtime AccessDenied |
direct API calls (no Lambda) |
The four silent-failure rows are the ones a baseline model misses. Missing logging, wrong log level, EXCLUDE_DATA on debugging inputs, and missing EventBridge target role all return success or wrong-shaped errors. Only Step 9 verification catches the gap.
Expert heuristic: the waitForTaskToken Express block
Full detail moved verbatim to references/advanced-patterns.md - load on demand. Summary: the complete waitForTaskToken migration-trap analysis and remedies.
Expert heuristic: at-least-once idempotency
Full detail moved verbatim to references/advanced-patterns.md - load on demand. Summary: the complete at-least-once idempotency pattern with ASL example.
Expert heuristic: sync API Gateway timeout misalignment
Full detail moved verbatim to references/advanced-patterns.md - load on demand. Summary: the complete sync API Gateway timeout misalignment analysis.
Prerequisites (verify before provisioning)
| Prerequisite | Why it matters | How to verify |
|---|---|---|
| Workflow duration fits in 5 min | Express caps at 5 min; sync API Gateway caps at 29s | estimate from longest task * longest retry; validate-state-machine-definition does NOT check this |
Workflow does NOT use .waitForTaskToken |
Express rejects it at create-time | grep ASL for :waitForTaskToken |
| IAM execution role trust policy | service principal must be states.<region>.amazonaws.com |
aws iam get-role --role-name <ROLE> |
| CloudWatch Logs log group exists (recommended) | Express execution history rolls over after 5 min | aws logs describe-log-groups --log-group-name-prefix /aws/states/<NAME> |
| Caller can assume the role (cross-account) | Cross-account callers need their own permission | caller identity policy check |
| EventBridge rule exists (scheduled) | Scheduled Express requires an EventBridge rule + target role | aws events describe-rule --name <RULE> |
| AWS region supports Express | Express is available in all commercial regions | aws stepfunctions list-state-machines --region <REGION> |
If any prerequisite is missing, output VERDICT: PREREQUISITES_MISSING
and cite the specific gap.
9-step provisioning procedure
Step 1 — Confirm Express-vs-Standard decision
Verify Express is the correct type. Use this decision table:
| If your workload… | Use |
|---|---|
| Runs > 5 minutes per execution | STANDARD |
Uses .waitForTaskToken (callbacks) |
STANDARD |
| Needs exactly-once semantics and idempotency is infeasible | STANDARD |
| Runs < 5 minutes, high-volume (>1k/day), idempotent or read-mostly | EXPRESS |
| Triggered by EventBridge at high frequency | EXPRESS |
| Fronted by API Gateway returning the workflow result synchronously | EXPRESS (sync) |
| Async messaging with very high throughput | EXPRESS (async) |
Full detail moved verbatim to references/advanced-patterns.md - load on demand. Summary: the worked cost math (Standard vs Express break-even).
Step 2 — Verify workflow duration fits in the 5-minute cap
Sum the worst-case duration of every Task state multiplied by its
Retry MaxAttempts. If the workflow includes a Distributed Map,
sum the longest batch. If the result can exceed 5 minutes, the
workflow is incompatible with Express — go back to Step 1.
Full detail moved verbatim to references/diagnostic-commands.md - load on demand. Summary: the validate-state-machine-definition CLI (syntax-only check).
Common mistake: assuming validate-state-machine-definition
checks the 5-min cap. It does NOT — only syntax. The cap is
enforced at runtime; executions fail with States.Timeout.
Step 3 — Verify all service integrations are Express-compatible
Full detail moved verbatim to references/diagnostic-commands.md - load on demand. Summary: the grep command that rejects .waitForTaskToken definitions.
Express-compatible integration patterns:
- RequestResponse (default): invoke and return immediately
.sync: invoke and wait for completion (Glue, Batch, ECS, SageMaker, Comprehend)- AWS SDK integrations: direct API calls without Lambda
Express-INCOMPATIBLE patterns:
.waitForTaskToken: callback pattern (unbounded wait)
Common mistake: converting a Standard workflow that uses
.waitForTaskToken for the human-approval step. Replace with a
DynamoDB polling loop (.sync on a Lambda that polls approval
status) or split into two workflows.
Step 4 — Define the ASL with Express-compatible patterns
Full detail moved verbatim to references/express-asl-patterns.md - load on demand. Summary: the complete Step 4 walkthrough with Distributed Map ASL template.
Step 5 — Create the IAM execution role with least-privilege
Full detail moved verbatim to references/iam-and-logging-templates.md - load on demand. Summary: the complete Step 5 CLI + trust/identity policy templates.
Step 6 — Configure logging (CloudWatch Logs)
Full detail moved verbatim to references/iam-and-logging-templates.md - load on demand. Summary: the complete Step 6 logging CLI, level guidance, and pitfalls.
Step 7 — Choose sync (RequestResponse) vs async invocation
| Mode | Caller | Use when |
|---|---|---|
| Sync | API Gateway, direct start-sync-execution | Caller needs result synchronously, workflow < 29s p99 |
| Async | EventBridge, S3, SQS, start-execution | High throughput, fire-and-forget, up to 5 min |
Full detail moved verbatim to references/diagnostic-commands.md - load on demand. Summary: the start-sync/start-execution CLI and timeout-alignment warning.
Step 8 — Configure EventBridge scheduling + observability
Full detail moved verbatim to references/scheduling-and-observability.md - load on demand. Summary: the complete Step 8 EventBridge rule, alarm, and X-Ray templates.
Step 9 — Verification
Run every verification command and confirm each output matches the expected state.
Full detail moved verbatim to references/diagnostic-commands.md - load on demand. Summary: the Step 9 verification CLI listing.
NEVER do these things
These anti-patterns cause silent exposure, data-plane bugs, or compliance violations. Each is observed in real production incidents — the "why it's wrong" line is the post-mortem finding.
-
NEVER provision an Express workflow with
.waitForTaskTokenin the ASL. Why it's wrong: Express rejects the integration at create-time (5-min cap is incompatible with unbounded callback wait). The error references the line number, not the incompatibility — operators loop on re-applying. Replace with.syncfor supported run-job integrations or split into a Standard + Express pair. -
NEVER deploy async Express without CloudWatch Logs enabled and an
ExecutionsFailedalarm. Why it's wrong: async Express has no caller to surface errors. The 5-min execution-history window rolls over quickly; without persistent logging, failures are invisible. Without an alarm, the failure may go undetected for days. ALWAYS attach a log group withlevel >= ERRORand alarm onExecutionsFailed. -
NEVER assume Express executions are exactly-once. Why it's wrong: Express is at-least-once. The infrastructure can restart an execution on internal events; the same input can produce two invocations of a side-effecting integration. Every write-path integration MUST be idempotent via a key persisted BEFORE the side effect.
-
NEVER front a sync Express workflow with API Gateway without aligning the timeout. Why it's wrong: API Gateway caps at 29s; Express sync can run to 5 min. When p99 exceeds 29s, API Gateway returns 504 while Express keeps running — the client retries, producing a second execution that may double-charge if the integration is non-idempotent. Set the API Gateway integration timeout to 29000 ms and alarm on p99 duration > 25s.
-
NEVER set log level to OFF or FATAL on an Express workflow. Why it's wrong: OFF and FATAL produce near-empty logs, blocking RCA. Use
ALLfor development and non-PII workloads;ERRORfor high-volume production. Always setincludeExecutionData=trueunless the workflow processes regulated PII — and in that case, redact the PII at the input, not by disabling execution data.
Output format
Full detail moved verbatim to references/worked-examples.md - load on demand. Summary: the literal output template block.
STRICT output contract
The rules below are hard constraints. Violating any one produces a checklist that looks complete but contains a silent misconfiguration. Self-check EVERY emitted block against these rules before returning.
Required output structure
Every response MUST be a single block using these literal labels, in this order. Do NOT preface with prose, headings, or disclaimers.
EXPRESS_WORKFLOW: <name>
VERDICT: READY_TO_DEPLOY | PREREQUISITES_MISSING
CHECKLIST:
[✓|✗] Express-vs-Standard decision: EXPRESS (duration < 5 min, at-least-once acceptable)
[✓|✗] Duration budget: p99 < 5 min (sync: p99 < 29s)
[✓|✗] No .waitForTaskToken in ASL: verified
[✓|✗] ASL definition validated: Distributed Map / .sync / AWS SDK as applicable
[✓|✗] IAM execution role: least-privilege, service principal states.<region>.amazonaws.com
[✓|✗] Logging: log-group /aws/states/<NAME>, level ALL|ERROR, includeExecutionData=true
[✓|✗] Invocation mode: sync | async (sync caller timeout aligned)
[✓|✗] EventBridge schedule + CloudWatch alarm: configured
[✓|✗] Idempotency: side-effecting integrations have idempotency key
VERIFICATION_COMMANDS:
<copy-pasteable verification commands — one per [✓] item>
Decision tree: Express vs Standard
Express vs Standard — START
│
Q1: Does any single execution need to run > 5 minutes?
├── YES → STANDARD (Express hard-caps at 5 min per execution)
└── NO → Q2
│
Q2: Does the ASL use .waitForTaskToken (callback / human-approval)?
├── YES → STANDARD (Express rejects .waitForTaskToken at create-time)
└── NO → Q3
│
Q3: Is exactly-once required AND idempotency is infeasible?
├── YES → STANDARD (Express is at-least-once; retries can double-execute)
└── NO → Q4
│
Q4: Is the workload high-volume (> 1,000 executions/day)?
├── NO → Either works; prefer STANDARD unless cost is a concern
└── YES → Q5
│
Q5: Can all side-effecting integrations be made idempotent?
├── NO → STANDARD (at-least-once risks duplicate writes / charges)
└── YES → EXPRESS
Cost model:
Standard: $25.00 / 1M state transitions
Express: $1.00 / 1M invocations + $0.025 / GB-hour
10-state workflow, 1M runs/day:
Standard = $250/day | Express = $1/day
10-state workflow, 10M runs/day:
Standard = $2,500/day | Express = $10/day
FORBIDDEN output patterns
-
NEVER emit
VERDICT: READY_TO_DEPLOYwithout showing ALL 9 checklist items. Every item MUST appear with a status marker:[✓],[✗], or[OPTIONAL](e.g., EventBridge schedule when the workflow is not scheduled). Omitting a row implies it was not evaluated. -
NEVER mark the ASL as
[✓]without confirming the definition contains NO.waitForTaskTokenResource ARN suffix. The integration is silently rejected by Express at create-time; the verification MUST include agrepor equivalent. -
NEVER mark Logging as
[✓]without citing the specific log group name, level (ALL / ERROR), andincludeExecutionDatavalue. A bare[✓] Logging: configuredis non-compliant — level and data-exposure flag are load-bearing. OFF and FATAL are non-compliant for an Express workflow. -
NEVER mark sync invocation as
[✓]without confirming the caller's timeout is ≤ 29s (API Gateway) or equivalent for the direct caller. Misaligned timeouts cause silent 504s while Express keeps running, producing double-executions on retry. -
NEVER mark Idempotency as
[✓]for a workflow with side- effecting integrations unless each such integration has an idempotency key persisted BEFORE the side effect. The checklist MUST cite the key source (e.g.,IdempotencyKey.$: "$$.Execution.Id"). -
NEVER emit
VERDICT: PREREQUISITES_MISSINGwithout citing the specific gap. Each[✗]item MUST have a one-line reason:[✗] ASL uses .waitForTaskToken at line 42 — replace with .sync or migrate to Standard. A bare[✗]is non-compliant. -
NEVER omit the cost-model comparison from the Express-vs- Standard checklist row. The row MUST cite the cost delta (e.g., "Express $1/M invocations vs Standard $25/M transitions") so the operator can sanity-check the type choice. A bare "EXPRESS" without cost rationale is non-compliant.
Perfect example output — READY_TO_DEPLOY
Scenario: High-volume event-processing Express workflow. JSON event batches land in S3; a Distributed Map fans them out to a Lambda for per-event processing. Async, triggered by EventBridge every 5 minutes. At 2M executions/day with a 5-state workflow: Standard would cost ~$250/day ($25/M x 10M transitions); Express costs ~$2/day ($1/M x 2M invocations). p99 execution duration = 12s.
EXPRESS_WORKFLOW: event-processor-express
VERDICT: READY_TO_DEPLOY
CHECKLIST:
[✓] Express-vs-Standard decision: EXPRESS (p99 12s, idempotent;
cost: Express $1/M invocations vs Standard $25/M transitions;
2M runs/day x 5 states = 10M transitions -> Standard $250/day vs Express $2/day)
[✓] Duration budget: p99 12s < 5 min (async; no sync API Gateway alignment needed)
[✓] No .waitForTaskToken in ASL: verified (grep -c ':waitForTaskToken' definition.json = 0)
[✓] ASL definition validated: Distributed Map (MaxConcurrency 1000, S3 ItemReader)
+ Lambda Task with idempotency key (see ASL below)
[✓] IAM execution role: sfn-event-processor-exec, trust=states.us-east-1.amazonaws.com,
scoped to lambda:InvokeFunction on arn:aws:lambda:us-east-1:123456789012:function:process-event
+ s3:GetObject on arn:aws:s3:::event-input-bucket/events/*.json
[✓] Logging: /aws/states/event-processor-express, level ALL, includeExecutionData=true
(30-day retention; see logging CLI below)
[✓] Invocation mode: async (EventBridge schedule rate(5 minutes))
[✓] EventBridge schedule: rule event-processor-schedule, target role eventbridge-sfn-role,
CloudWatch alarm event-processor-failed on ExecutionsFailed >= 1
[✓] Idempotency: ProcessEvent Lambda checks IdempotencyKey=$$.Execution.Id against
DynamoDB table event-idempotency before writing; duplicate retries are no-ops
VERIFICATION_COMMANDS:
aws stepfunctions describe-state-machine --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:event-processor-express
grep -c ':waitForTaskToken' definition.json
aws logs describe-log-groups --log-group-name-prefix /aws/states/event-processor-express
aws events describe-rule --name event-processor-schedule
aws cloudwatch describe-alarms --alarm-names event-processor-failed
ASL definition (Distributed Map + Lambda Task with idempotency key):
{
"StartAt": "FanOutProcess",
"States": {
"FanOutProcess": {
"Type": "Map",
"ItemProcessor": {
"ProcessorConfig": { "Mode": "DISTRIBUTED" },
"StartAt": "ProcessEvent",
"States": {
"ProcessEvent": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:process-event",
"Parameters": {
"IdempotencyKey.$": "$$.Execution.Id",
"EventPayload.$": "$.value"
},
"Retry": [
{ "ErrorEquals": ["States.TaskFailed"], "MaxAttempts": 3, "BackoffRate": 2 }
],
"End": true
}
}
},
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": { "Bucket": "event-input-bucket", "Key": "events/batch.json" }
},
"MaxConcurrency": 1000,
"End": true
}
}
}
Logging configuration CLI (create log group with retention + attach at state machine creation):
aws logs create-log-group --log-group-name /aws/states/event-processor-express
aws logs put-retention-policy \
--log-group-name /aws/states/event-processor-express --retention-in-days 30
aws stepfunctions create-state-machine \
--name event-processor-express \
--definition file://definition.json \
--role-arn arn:aws:iam::123456789012:role/sfn-event-processor-exec \
--type EXPRESS \
--logging-configuration \
level=ALL,includeExecutionData=true,\
destinations='[{CloudWatchLogsLogGroup={LogGroupArn=arn:aws:logs:us-east-1:123456789012:log-group:/aws/states/event-processor-express:*}}]'
Perfect example output — PREREQUISITES_MISSING
Full detail moved verbatim to references/worked-examples.md - load on demand. Summary: the full PREREQUISITES_MISSING example with self-check list.
Recent AWS features
Full detail moved verbatim to references/advanced-patterns.md - load on demand. Summary: the full feature list (Distributed Map on Express, SDK integrations, typed ARNs, log granularity, X-Ray, IAM condition keys).
References (load on demand)
- references/worked-examples.md - secondary example output (PREREQUISITES_MISSING) and the output-format template
- references/diagnostic-commands.md - pre-flight validation, compatibility grep, invocation, and verification CLI listings
- references/advanced-patterns.md - Express reasoning prose, expert heuristics, cost math, recent AWS features
- references/scheduling-and-observability.md - EventBridge scheduling, CloudWatch alarms, X-Ray tracing templates
- references/express-asl-patterns.md - (existing) ASL patterns; now also holds the Step 4 Express ASL template
- references/iam-and-logging-templates.md - (existing) IAM/logging templates; now also holds Step 5-6 CLI templates
04 同仓库更多 Skills
xray-tracing-deployer
Deploys AWS X-Ray distributed tracing with production-grade configuration: X-Ray daemon deployment (EC2 systemd, ECS sidecar, EKS DaemonSet, Lambda built-in), SDK instrumentation (Java, Python, Node.js, Go, .NET) with annotations and metadata, sampling rules (default reservoir + rate vs custom rules with URL / method / service-name predicates), service map generation, trace query and retrieval, groups and insights, CloudWatch ServiceLens integration, IAM permissions (PutTraceSegments, GetSamplingRules), and latest features (Lambda Powertools tracing, OpenTelemetry / ADOT Collector support, W3C trace context). Emits a READY_TO_DEPLOY checklist with every configuration item verified. Use when enabling X-Ray on a new application, adding tracing to ECS / EKS / Lambda, validating a sampling configuration, or generating daemon deployment CLI and IaC templates. Triggers: X-Ray, distributed tracing, X-Ray daemon, sampling rules, service map, X-Ray SDK, OpenTelemetry, ADOT, Lambda Powertools, CloudWatch ServiceLens.
wellarchitected-workload-auditor
Audits AWS Well-Architected Tool workloads for review staleness, per-pillar high-risk issue counts, milestone tracking gaps, and remediation plan completeness. Emits a deterministic verdict (STALE_REVIEW | HIGH_RISK | CONFIG_GAP | OK) per workload with per-pillar risk breakdown, milestone trend analysis, and specific remediation. Use when reviewing Well-Architected workloads, checking WA review freshness, auditing high-risk issues per pillar, validating milestone coverage, or tracking remediation plans.
wellarchitected-review-operator
Operates AWS Well-Architected Tool reviews end-to-end — creates workloads, runs pillar reviews (operational excellence, security, reliability, performance, cost optimization, sustainability, Prosperity), answers questions with risk-tier rationale, generates reports and improvement plans, creates milestones, and integrates with Trusted Advisor and Well-Architected Labs. Runs deterministic pre-checks (workload existence, lens availability, pillar coverage), emits the exact update-answer / get-consolidated-report CLI behind a CONFIRM gate, and verifies risk-tier transitions. Emits READY | BLOCKED | COMPLETED. Use when creating a workload, answering pillar questions, generating an improvement plan, creating a milestone, or integrating with Trusted Advisor. Triggers: well-architected tool, well architected review, workload review, pillar, operational excellence, security, reliability, performance, cost optimization, sustainability, prosperity, improvement plan, milestone, trusted advisor.
wafv2-web-acl-deployer
Provisions AWS WAFv2 Web ACLs with correct production defaults: scope selection (CLOUDFRONT vs REGIONAL), managed rule groups (AWSManagedRulesCommonRuleSet, SQLiRuleSet, LinuxRuleSet, WindowsRuleSet, IPReputationList, BotControlRuleSet, AmazonIpReputationList, ATP), custom rules (byte match, IP set, regex pattern, geo match, size constraint, rate-based), rule priority ordering, logging destinations (Kinesis Firehose, CloudWatch Logs, S3), resource association (ALB, API Gateway, CloudFront), rate-based rules with aggregate keys (IP, forwarded IP), Challenge and CAPTCHA actions, and account takeover prevention. Emits a READY_TO_DEPLOY checklist. Use when creating a Web ACL, attaching managed rules, configuring rate limiting, enabling WAF logging, associating a Web ACL with an ALB/API Gateway/CloudFront, or configuring CAPTCHA/Challenge actions. Triggers: create WAF Web ACL, WAFv2, managed rule groups, WAF rate limiting, WAF logging, WAF CAPTCHA, WAF Challenge action, bot control, ATP managed rules.
wafv2-web-acl-auditor
Audits AWS WAFv2 Web ACL configurations to determine whether the ACL provides effective protection: default-action posture (Allow vs Block), managed-rule-group coverage gaps, rule effectiveness (BLOCK vs COUNT, shadow/bypass rules, stale exclusions), rate-based rule correctness, logging and visibility configuration, and text-transformation bypass vectors. Emits a deterministic verdict per Web ACL. Use when reviewing a WAFv2 Web ACL for security posture, checking managed-rule coverage, validating rate-limit configuration, auditing WAF logging, or hardening a WAF before production deployment. Triggers: WAF, WAFv2, Web ACL, managed rule group, AWSManagedRules, rate-based rule, CAPTCHA, Challenge, OverrideAction, Count mode, forwarded IP, Bot Control, ATP, text transformation, WAF logging, WAF visibility, OWASP, SQLi, XSS, RFI.
waf-rule-deployer
Provisions AWS WAFv2 rule sets with production defaults: Web ACL creation (CloudFront scope in us-east-1 vs Regional scope), rule groups (managed vs custom) with capacity planning in WCU (Web ACL Capacity Units, 1500 default per ACL), managed rule groups (AWSManagedRulesCommonRuleSet, AWSManagedRulesSQLiRuleSet, AWSManagedRulesAmazonIpReputationList, AWSManagedRulesLinuxRuleSet, AWSManagedRulesWindowsRuleSet, AWSManagedRulesUnixRuleSet), custom rules (byte-match, regex pattern set, geo-match, rate-based), IP set and regex pattern set resources, rule priority ordering (lowest number evaluated first), action types (allow, block, count, CAPTCHA, Challenge), bot control managed rule group, account takeover. Triggers: create WAF rule, WAF managed rule group, WAF custom rule, WAF byte match, WAF geo match, WAF rate based rule, WAF IP set, WAF regex pattern set, WAF WCU budget, WAF CloudFront ACL, WAF logging Kinesis Firehose, WAF bot control, WAF ATP, WAF label matching, WAF Challenge action, WAF CAPTCHA.