nmor/the-claude-council/aws-serverless-patterns

Claude Code and agent skill by nmor/the-claude-council

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Design AWS Lambda, API Gateway, DynamoDB, EventBridge and SQS workflows with durable publish intent, retries, idempotency and backpressure.

Install

npx vskill@latest install nmor/the-claude-council/aws-serverless-patterns

SKILL.md

The same SKILL.md was published earlier as nmor/the-claude-council/aws-serverless-patterns.

AWS Serverless Patterns

Reuse-first (per ~/.claude/rules-library/common/reuse-first.md):
One source of truth per Lambda layer concern — one auth
middleware, one error responder, one body parser, one
idempotency helper, one DDB client factory, one outbox
publisher. Lambda layers (or shared /lib/ for monorepo
deploys) are the canonical home. Each new handler imports the
shared primitives; never re-implement them per handler.
Size budget: 22 KB — token-budget.mjs --check.

Lambda + API Gateway + the surrounding event-driven AWS surface. The patterns here matter because the failure modes (cold starts, lost messages, double-processing, runaway concurrency) show up at customer scale, not in dev.

When to Activate

  • Authoring or reviewing a Lambda handler
  • Designing a webhook ingest path (Stripe, Slack, ClickUp, Twilio, GitHub)
  • Adding SQS / SNS / EventBridge wiring
  • Diagnosing a cold-start tail or throttled-concurrency incident
  • Building a Step Functions workflow
  • Configuring serverless.yml, SAM template.yaml, or CDK stacks

Cold Start: Minimize, Don't Eliminate

Cold-start latency comes from two places:

  1. Container provisioning — AWS-controlled; ~100-300 ms for Node 22+ (20 EOL 2026-04) / 256 MB
  2. Module import — your code; can balloon to 1-3 s with heavy SDK imports

Fixes that work:

  • Tree-shake heavy SDKs — import { DynamoDBClient } from "@aws-sdk/client-dynamodb" only pulls

the DDB client, not the whole aws-sdk v2 monolith.

  • Top-of-file imports for the hot path — keep await import("...") for genuinely conditional

dependencies; static imports JIT-compile during cold start so they don't pay per-request.

  • Singleton AWS clients — instantiate once at module scope so warm invocations reuse them. Never

new DynamoDBClient() inside a handler.

  • Provisioned concurrency — last resort. Use only for user-facing latency-critical endpoints

(login, dashboard). Costs money even when idle.

Don't fix:

  • Most Lambdas — async workers (SQS / Stream consumers) are forgiving of 500 ms cold starts.

Engineering time spent shaving it off pays nothing.

Async-By-Default For Webhooks

Every external webhook (Stripe, Slack, GitHub, ClickUp, Twilio, Shopify) has a tight deadline (3-30 s). The synchronous Lambda must:

  1. Verify the signature (HMAC) — sync, < 10 ms
  2. Persist payload and publish intent atomically — conditional DynamoDB write of

one event/outbox row. A duplicate must match the original payload and retain its recoverable delivery state; it must not be mistaken for completed work.

  1. Return 200 only after durable acceptance, within the provider's deadline.
  2. Publish asynchronously — a DynamoDB Streams/outbox worker sends to SQS, then

records acknowledgment. A scheduled reconciliation worker recovers pending rows beyond stream retention. An ambiguous send can duplicate; consumers deduplicate.

The SQS worker then runs the heavy dispatch (API calls, AI inference, downstream writes) without blocking the upstream's retry timer.

yaml
# serverless.yml
functions:
stripeWebhook:
handler: handlers/stripeWebhook.handler
events:
- httpApi: { path: /stripe/webhook, method: post }
environment:
STRIPE_INBOUND_QUEUE_URL: !Ref StripeInboundQueue
stripeInboundWorker:
handler: handlers/stripeInboundWorker.handler
timeout: 60
events:
- sqs:
arn: !GetAtt StripeInboundQueue.Arn
batchSize: 5
functionResponseType: ReportBatchItemFailures
resources:
Resources:
StripeInboundDLQ:
Type: AWS::SQS::Queue
StripeInboundQueue:
Type: AWS::SQS::Queue
Properties:
VisibilityTimeout: 360
RedrivePolicy:
deadLetterTargetArn: !GetAtt StripeInboundDLQ.Arn
maxReceiveCount: 3

The synchronous handler stays thin; the worker owns the work.

Idempotency Is Mandatory

Every async path delivers AT LEAST once. SQS, SNS, EventBridge, DynamoDB Streams, Step Functions — none of them guarantee exactly-once. Defenses:

  • Conditional writes — attribute_not_exists(pk) rejects the second delivery atomically
  • Idempotency keys — distinguish pending, retryable and completed states. Do not

expire pending work or short-circuit it after a failed publish. A claim alone is not proof of delivery; atomically retain payload and intent, and reconcile ambiguity.

  • Last-writer-wins updates — order-independent operations (SET last_seen = :now if `:now >

last_seen`)

A good idempotency key is the upstream's event ID (stripe:<event_id>, slack:<event_id>, github:<delivery_id>). Their uniqueness is part of their contract; you inherit it.

SQS: Backpressure + Partial Failure

Configure every consumer Lambda with:

  • batchSize: 5-10 — small enough that one slow record doesn't block the rest
  • functionResponseType: ReportBatchItemFailures — return { batchItemFailures: [...] } to retry

only the failing records, not the whole batch

  • RedrivePolicy: { maxReceiveCount: 3, deadLetterTargetArn } — fail fast to a DLQ instead of

redelivering forever

  • VisibilityTimeout — at least 6 * function timeout (covers the BatchWrite retry window)

A Lambda asynchronous destination does not control SQS poller retries. Use queue RedrivePolicy, visibility timeout and partial batch responses on the event-source path. Fault-test failed/ambiguous publish, duplicate consumer execution and poison records. AWS transactional outbox.

A DLQ alarm is mandatory: any message in the DLQ is unprocessed business state and should page on-call.

SNS Fan-Out For 1:N Delivery

When one event needs N independent consumers (notifications, search index, analytics), SNS Topic + SNS-to-SQS subscriptions decouple them. Each consumer's failure doesn't backpressure the others.

yaml
RunCompletionTopic:
Type: AWS::SNS::Topic
EmailDeliveryQueue:
Type: AWS::SQS::Queue
Properties:
RedrivePolicy: { ... }
EmailSnsSubscription:
Type: AWS::SNS::Subscription
Properties:
Protocol: sqs
TopicArn: !Ref RunCompletionTopic
Endpoint: !GetAtt EmailDeliveryQueue.Arn

Don't fan out from application code. SNS is purpose-built for this and gives you per-subscription DLQs for free.

EventBridge Cron For Scheduled Work

Use events: schedule: on a Lambda for cron-like triggers. The schedule expression is cron(min hour day-of-month month day-of-week year) — note the year column AWS adds.

yaml
auditIntegrityJob:
handler: handlers/auditIntegrityJob.handler
events:
- schedule:
rate: cron(0 3 * * ? *) # 03:00 UTC daily
enabled: true

EventBridge cron is at-least-once. Make scheduled jobs idempotent (timestamp-keyed run rows in DDB), or accept that occasional duplicate runs are OK.

Reserved Concurrency: Capacity Insurance

Without reservedConcurrency, one runaway tenant (or a typo'd retry loop) can consume the account's entire concurrency pool and starve every other Lambda. Set it on:

  • Webhook ingestion (cap so a flood doesn't cascade)
  • Public APIs (cap so a 429 storm doesn't take down internal systems)
  • Heavyweight jobs (audit walker, GDPR erasure)

Don't set it everywhere — reserved concurrency removes capacity from the pool even when idle.

Step Functions Over State In Code

When a workflow has multiple async steps with retries, branches, and timeouts, use Step Functions. Encoding the same logic in handler code with DDB-backed state quickly becomes unmaintainable.

Default state-machine settings:

  • Catch: ["States.ALL"] on every Task — surface failures, don't crash the execution
  • Retry: [{ ErrorEquals: [...], IntervalSeconds: 30, MaxAttempts: 3, BackoffRate: 2.0 }] on

idempotent steps

  • TimeoutSeconds on every Task — must be less than the state machine's TimeoutSeconds

Use waitForTaskToken for human-in-the-loop or external callback steps. Lambdas inside Step Functions should be small enough to fit in 6 MB (the payload limit) — for bigger payloads, write to S3 and pass the key.

IAM Least Privilege

Each Lambda's execution role grants only what THAT Lambda needs. Avoid one big role for all functions in the stack. Patterns:

  • Per-Lambda role — Serverless Framework: iamRoleStatements per-function
  • Resource ARN locked to `${AWS::AccountId}` — never * in the account-id slot
  • Resource ARN locked to the stage-suffixed table name — never arn:aws:dynamodb:*:*:table/*

When a cell-based architecture spawns a second cell, per-stage table names + per-stage IAM roles automatically isolate the cells. Cross-cell data access is impossible at the IAM layer.

Observability: Structured Logs + EMF Metrics

Lambdas log to CloudWatch automatically. Make the logs useful:

  • Structured JSON — never console.log("user " + id). Use `console.log(JSON.stringify({ msg:

"...", user_id: id }))` or a logger lib that emits JSON.

  • Per-request correlation id — pass through request_id (APIGW provides one) on every log line

in the request's call chain

  • EMF metrics — emit a JSON line with the _aws.CloudWatchMetrics envelope; CloudWatch parses

it as a metric. Zero SDK calls, zero IAM perms, dimensioned by organization_id / cell_id / whatever you need.

ts
console.log(JSON.stringify({
_aws: {
Timestamp: Date.now(),
CloudWatchMetrics: [{
Namespace: "MyApp",
Dimensions: [["organization_id"]],
Metrics: [{ Name: "WebhookFailures", Unit: "Count" }],
}],
},
organization_id: orgId,
WebhookFailures: 1,
}));

Canary Deploys + Auto-Rollback

For production-traffic Lambdas, use serverless-plugin-canary-deployments (or CDK CodeDeploy.LambdaDeploymentGroup). Deploy 10% of traffic to the new version for 5-10 min; auto-rollback on any CloudWatch alarm breach.

yaml
functions:
httpApi:
deploymentSettings:
type: Canary10Percent5Minutes
alias: live
alarms:
- HttpApiErrorAlarm
- HttpApiDurationAlarm

The auto-rollback window is your safety net. Outside it, manual rollback (re-deploy the previous SHA) is the procedure.

Common Smells

SmellFix
console.log("foo " + bar)Structured JSON or a logger lib
new DynamoDBClient() inside a handlerMove to module scope
Synchronous webhook handler making external API callsSplit: sync handler enqueues; worker dispatches
aws-sdk v2 importMigrate to v3 modular imports
Lambda with no RedrivePolicy on its triggerAdd a DLQ
reservedConcurrency unset on user-facing handlerSet a sensible cap
One IAM role for every Lambda in the stackSplit per-function
Cron job with no idempotency checkIdempotency key per scheduled run
events: stream: consumer that throws on bad rowCatch + log + ack; only retry on transient
fs.writeFile, os.Create, open(path, "w") in production sourceStream to in-memory buffer + S3 PutObject. Lambda's local disk dies on invocation end; relying on it is a P1 in waiting. See ~/.claude/rules-library/common/no-local-fs.md

Skill Chain

  1. aws-serverless-patterns — this skill
  2. deployment-patterns — CI/CD, canary, rollback
  3. dynamodb-patterns — when DDB is involved
  4. security-review — IAM, secrets, signature verification
  5. backend-patterns — handler / repository shape

Purpose

AWS serverless architecture patterns for Lambda + API Gateway + DynamoDB + SQS + EventBridge + Step Functions: handler structure, cold-start optimisation, async-by-default for webhooks, idempotent processing, observability with EMF + X-Ray, and IaC discipline (AWS SAM, CDK, Serverless Framework).

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
5

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/nmor/the-claude-council/aws-serverless-patterns/badge)](https://verified-skill.com/skills/nmor/the-claude-council/aws-serverless-patterns)

Something wrong with this skill or its page? Tell us.