nmor/the-claude-council/aws-serverless-patterns
Claude Code and agent skill by nmor/the-claude-council
- community
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-patternsSKILL.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 authmiddleware, one error responder, one body parser, oneidempotency helper, one DDB client factory, one outboxpublisher. Lambda layers (or shared/lib/for monorepodeploys) are the canonical home. Each new handler imports theshared 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, SAMtemplate.yaml, or CDK stacks
Cold Start: Minimize, Don't Eliminate
Cold-start latency comes from two places:
- Container provisioning — AWS-controlled; ~100-300 ms for Node 22+ (20 EOL 2026-04) / 256 MB
- 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:
- Verify the signature (HMAC) — sync, < 10 ms
- 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.
- Return 200 only after durable acceptance, within the provider's deadline.
- 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.
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 = :nowif `: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 restfunctionResponseType: 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 least6 * 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.
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.
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 executionRetry: [{ ErrorEquals: [...], IntervalSeconds: 30, MaxAttempts: 3, BackoffRate: 2.0 }]on
idempotent steps
TimeoutSecondson every Task — must be less than the state machine'sTimeoutSeconds
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:
iamRoleStatementsper-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.CloudWatchMetricsenvelope; CloudWatch parses
it as a metric. Zero SDK calls, zero IAM perms, dimensioned by organization_id / cell_id / whatever you need.
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.
The auto-rollback window is your safety net. Outside it, manual rollback (re-deploy the previous SHA) is the procedure.
Common Smells
| Smell | Fix | |
|---|---|---|
console.log("foo " + bar) | Structured JSON or a logger lib | |
new DynamoDBClient() inside a handler | Move to module scope | |
| Synchronous webhook handler making external API calls | Split: sync handler enqueues; worker dispatches | |
aws-sdk v2 import | Migrate to v3 modular imports | |
Lambda with no RedrivePolicy on its trigger | Add a DLQ | |
reservedConcurrency unset on user-facing handler | Set a sensible cap | |
| One IAM role for every Lambda in the stack | Split per-function | |
| Cron job with no idempotency check | Idempotency key per scheduled run | |
events: stream: consumer that throws on bad row | Catch + log + ack; only retry on transient | |
fs.writeFile, os.Create, open(path, "w") in production source | Stream 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
- aws-serverless-patterns — this skill
- deployment-patterns — CI/CD, canary, rollback
- dynamodb-patterns — when DDB is involved
- security-review — IAM, secrets, signature verification
- 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
- SKILL.md in the repositoryCheckingskills/aws-serverless-patterns/SKILL.md
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
[](https://verified-skill.com/skills/nmor/the-claude-council/aws-serverless-patterns)