Bundled upstream support
Supporting files are included at skill-relative paths. See UPSTREAM-NOTICE.md for their pinned sources, licenses, hashes, and import changes.
SST v4 for AWS
When to Use
Use this skill when you need sST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework. Use when writing or editing sst.config.ts, building infra/ modules (sst.aws.Function/Bucket/Dynamo/Cron/Service/Router, sst.Secret, sst.Linkable, raw aws.* Pulumi resources), wiring resource links,...
SST v4 (the "Ion" engine) is a Pulumi-backed IaC framework: you describe AWS
resources in TypeScript and SST/Pulumi reconciles them into your account. It
gives you high-level sst.aws.* components (Function, Bucket, Dynamo, Cron,
Service, …) that expand into many underlying resources, plus an escape hatch to
any raw Pulumi aws.* resource for the long tail. This skill encodes a
production-proven way to author, link, test, deploy, and troubleshoot SST
stacks on AWS — distilled from real multi-stack projects that have paid for
each lesson with a prod incident.
SST and Pulumi are third-party — verify current syntax with Context7
(resolve-library-id → query-docs for sst or pulumi-aws) when you're
unsure about a component's options. Verify AWS-side facts (service limits,
model IDs, IAM action names, region availability) with the AWS docs MCP, never
from memory. The patterns here are the how; the docs are the what.
When you're invoked
Figure out which mode you're in and jump to the right reference:
| Situation |
Go to |
| New project, or adding a resource/module to an existing SST app |
Author → references/authoring.md |
| Wiring one module's output into another (links, SSM, IAM scope) |
Author → references/authoring.md § Sharing |
| Writing tests for infra so changes don't silently break |
Test → references/testing.md |
| Running a deploy, or a deploy just failed |
Deploy/Operate → references/deploy-and-troubleshoot.md |
| Migrating a resource between Pulumi types, renaming a physical name |
Deploy/Operate → references/deploy-and-troubleshoot.md § Migrations |
Always read the relevant reference before editing — they carry the why behind
each rule, which matters more than the rule itself.
Orientation: read the repo before you touch it
SST projects are conventional but not identical. Before editing, build a quick
map so your change matches the house style instead of fighting it:
sst.config.ts — the app name, home, providers/region, defaultTags,
any global $transform (Node runtime pin, bundle fixups), and the order in
which run() imports infra/ modules. The import order is the dependency
order; respect it.
infra/ — one file per domain (storage, functions, api, observability…).
This is where resources are declared. Check for an infra/CLAUDE.md — these
projects keep IaC-specific rules there, and it's the single most valuable
file to read first.
infra/tests/ — source-level Vitest assertions that pin resource
invariants. If they exist, your change must keep them green and probably
needs a new assertion.
package.json / .nvmrc — package manager (npm vs pnpm), Node version,
and the sst/pulumi versions actually installed.
Run npx sst version to confirm you're on v4/Ion (the $config + .sst/platform/
signature). v2/v3 ("SST Classic", CDK-based) is a different framework — these
patterns don't apply there.
The conventions, and which are universal vs tunable
The projects this skill is built from share a deliberate house style. Some of it
is universal (true for any SST v4 + AWS project — apply it everywhere); some
is project-specific (a sensible default these projects chose — adopt it for
consistency, but recognize a project may differ).
Universal — these principles hold for any SST v4 + AWS project:
- Control the Node runtime deliberately, in one place. Don't leave it to
whatever the installed SST happens to default to. The idiom is a single global
$transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" }) in
run() — ??= is correct here (the transform runs before the component
applies its own default, so it fills in only when the user didn't set one).
Recent SST already defaults to a current Node runtime, so check the installed
default first (Context7); the transform is then version-independence insurance
so a future SST downgrade can't silently move your fleet. See
references/authoring.md.
- Never interpolate a Pulumi
Output<T> into a plain JS template literal.
Use $interpolate (or pulumi.interpolate). A bare top-level
`${bucket.arn}/*` stringifies the Output to a [Output<T>] placeholder
and produces a broken ARN that only fails at deploy time (it type-checks and
sst dev runs fine). The fix is $interpolate`${bucket.arn}/*`. This
has caused prod deploy outages. See references/authoring.md § Outputs.
- Migrating a resource between Pulumi types should default to two PRs —
Pulumi creates-before-destroys, so for a uniqueness-constrained AWS name
(bucket, IAM role, gateway) the old resource still owns it and the create
fails with
ConflictException. Two sequential deploys (teardown, then
recreate) is the conservative default; aliases: / pulumi import / state
surgery can bridge identity in some cases but only with a reviewed plan. See
references/deploy-and-troubleshoot.md § Migrations.
- Prefer typed
sst.aws.* / aws.* resources over the
aws.cloudcontrol.Resource escape hatch. CloudControl outputs are
stringly-typed and oneOf fields don't patch cleanly. Use it only when no
typed resource exists yet, and migrate off it when one ships.
Project-specific defaults — adopt for consistency, but confirm per repo:
- Region
ap-northeast-1, home: "aws", and defaultTags carrying
Project / Stage / ManagedBy: "sst".
- Stage-gated lifecycle:
removal: stage === "prod" ? "retain" : "remove"
and protect: stage === "prod" so prod resources survive a stack tear-down
and non-prod previews clean up.
- SSM Parameter Store as the out-of-graph contract under a
/{app}/{stage}/{domain}/... prefix — for consumers that aren't in the
Pulumi graph (CI scripts, sibling apps, operators). For same-app Lambdas,
prefer SST link: (it wires a real dependency edge and grants IAM); don't
route same-app sharing through SSM. See references/authoring.md § Sharing.
- Lazy
await import("./infra/<module>") inside run() so sst dev
hot-reload stays light. (For testing, a module export still runs its top-level
new sst.aws.* unless it's wrapped in a factory function — see
references/testing.md for how to test infra.)
- Source-level Vitest tests on every infra module — a lightweight,
house-style regression net asserting on the source text (resource names,
index shapes, IAM scopes). It's a deliberate choice, not an SST limit: Pulumi
does support runtime mocks (
@pulumi/pulumi/runtime) for behavioral graph
tests when a module has real logic. Source assertions don't replace a
preview-deploy + smoke test. See references/testing.md.
- An observability gate: every new Lambda/queue/schedule gets an alarm and
structured logging before merge. Whether you enforce this depends on the
project, but it's cheap insurance. See
references/deploy-and-troubleshoot.md
§ Observability.
When you introduce a convention, say which bucket it's in ("this is universal"
vs "matching this repo's house style") so the user can override the
project-specific ones deliberately.
Working rhythm
- Orient (above) — map config, modules, tests, tooling.
- Verify syntax with Context7 / AWS docs MCP if anything is non-obvious.
Don't guess at a component's option name.
- Author the resource/module following
references/authoring.md. Match the
surrounding file's commenting density and naming — these projects comment the
why heavily, and a terse one-liner in a heavily-annotated file reads as a
regression.
- Test — add or update source-level assertions (
references/testing.md) and
run npx vitest (or the repo's test script). Run npx sst diff and/or
tsc --noEmit to catch type and plan errors before deploying.
- Deploy/operate per
references/deploy-and-troubleshoot.md. Confirm the
target account with aws sts get-caller-identity before any sst deploy.
- Clean up any exported state files — they contain account IDs and ARNs and
must not linger in
/tmp or chat history.
What good looks like
- The change is the smallest diff that satisfies the requirement, in the right
infra/ module, wired into run() in dependency order.
- Every Lambda gets the right runtime via the global transform (you didn't
hand-set
runtime unless intentionally diverging — e.g. a Python function).
- Cross-resource references use
link: (in-graph) and/or $interpolate-scoped
IAM; outputs other tools consume are published to SSM under the stage prefix.
- New infra has a matching source-level test, and the existing suite stays green.
- You confirmed AWS-side facts via the docs MCP and SST/Pulumi syntax via
Context7 rather than relying on recall.
- Anything irreversible (deploy,
sst remove, a resource-type migration) was
flagged to the user with the account it targets, and migrations were planned
as two PRs, not one.
Example
User request:
Use @aws-sst-development for this task: SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework.
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
1---2name: aws-sst-development3description: "SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework."4risk: critical5source: https://github.com/zxkane/aws-skills/tree/main/plugins/aws-iac/skills/aws-sst-development6source_repo: zxkane/aws-skills7source_type: community8date_added: 2026-07-019license: MIT10license_source: https://github.com/zxkane/aws-skills/blob/main/LICENSE11metadata:12 source: https://skillmd.com/skills/iradoweck/aws-sst-development13---1415## Bundled upstream support1617Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes.1819# SST v4 for AWS20## When to Use2122Use this skill when you need sST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework. Use when writing or editing sst.config.ts, building infra/ modules (sst.aws.Function/Bucket/Dynamo/Cron/Service/Router, sst.Secret, sst.Linkable, raw aws.* Pulumi resources), wiring resource links,...232425SST v4 (the "Ion" engine) is a Pulumi-backed IaC framework: you describe AWS26resources in TypeScript and SST/Pulumi reconciles them into your account. It27gives you high-level `sst.aws.*` components (Function, Bucket, Dynamo, Cron,28Service, …) that expand into many underlying resources, plus an escape hatch to29*any* raw Pulumi `aws.*` resource for the long tail. This skill encodes a30production-proven way to author, link, test, deploy, and troubleshoot SST31stacks on AWS — distilled from real multi-stack projects that have paid for32each lesson with a prod incident.3334**SST and Pulumi are third-party — verify current syntax with Context7**35(`resolve-library-id` → `query-docs` for `sst` or `pulumi-aws`) when you're36unsure about a component's options. Verify AWS-side facts (service limits,37model IDs, IAM action names, region availability) with the AWS docs MCP, never38from memory. The patterns here are the *how*; the docs are the *what*.3940## When you're invoked4142Figure out which mode you're in and jump to the right reference:4344| Situation | Go to |45|-----------|-------|46| New project, or adding a resource/module to an existing SST app | **Author** → `references/authoring.md` |47| Wiring one module's output into another (links, SSM, IAM scope) | **Author** → `references/authoring.md` § Sharing |48| Writing tests for infra so changes don't silently break | **Test** → `references/testing.md` |49| Running a deploy, or a deploy just failed | **Deploy/Operate** → `references/deploy-and-troubleshoot.md` |50| Migrating a resource between Pulumi types, renaming a physical name | **Deploy/Operate** → `references/deploy-and-troubleshoot.md` § Migrations |5152Always read the relevant reference before editing — they carry the *why* behind53each rule, which matters more than the rule itself.5455## Orientation: read the repo before you touch it5657SST projects are conventional but not identical. Before editing, build a quick58map so your change matches the house style instead of fighting it:59601. **`sst.config.ts`** — the app name, `home`, providers/region, `defaultTags`,61 any global `$transform` (Node runtime pin, bundle fixups), and the order in62 which `run()` imports `infra/` modules. The import order *is* the dependency63 order; respect it.642. **`infra/`** — one file per domain (storage, functions, api, observability…).65 This is where resources are declared. Check for an `infra/CLAUDE.md` — these66 projects keep IaC-specific rules there, and it's the single most valuable67 file to read first.683. **`infra/tests/`** — source-level Vitest assertions that pin resource69 invariants. If they exist, your change must keep them green and probably70 needs a new assertion.714. **`package.json` / `.nvmrc`** — package manager (npm vs pnpm), Node version,72 and the `sst`/`pulumi` versions actually installed.7374Run `npx sst version` to confirm you're on v4/Ion (the `$config` + `.sst/platform/`75signature). v2/v3 ("SST Classic", CDK-based) is a different framework — these76patterns don't apply there.7778## The conventions, and which are universal vs tunable7980The projects this skill is built from share a deliberate house style. Some of it81is **universal** (true for any SST v4 + AWS project — apply it everywhere); some82is **project-specific** (a sensible default these projects chose — adopt it for83consistency, but recognize a project may differ).8485**Universal — these principles hold for any SST v4 + AWS project:**8687- **Control the Node runtime deliberately, in one place.** Don't leave it to88 whatever the installed SST happens to default to. The idiom is a single global89 `$transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" })` in90 `run()` — `??=` is correct here (the transform runs before the component91 applies its own default, so it fills in only when the user didn't set one).92 Recent SST already defaults to a current Node runtime, so check the installed93 default first (Context7); the transform is then version-independence insurance94 so a future SST downgrade can't silently move your fleet. See95 `references/authoring.md`.96- **Never interpolate a Pulumi `Output<T>` into a plain JS template literal.**97 Use `$interpolate` (or `pulumi.interpolate`). A bare top-level98 `` `${bucket.arn}/*` `` stringifies the `Output` to a `[Output<T>]` placeholder99 and produces a broken ARN that only fails at deploy time (it type-checks and100 `sst dev` runs fine). The fix is `$interpolate``` `${bucket.arn}/*` ``. This101 has caused prod deploy outages. See `references/authoring.md` § Outputs.102- **Migrating a resource between Pulumi *types* should default to two PRs** —103 Pulumi creates-before-destroys, so for a uniqueness-constrained AWS name104 (bucket, IAM role, gateway) the old resource still owns it and the create105 fails with `ConflictException`. Two sequential deploys (teardown, then106 recreate) is the conservative default; `aliases:` / `pulumi import` / state107 surgery can bridge identity in some cases but only with a reviewed plan. See108 `references/deploy-and-troubleshoot.md` § Migrations.109- **Prefer typed `sst.aws.*` / `aws.*` resources over the110 `aws.cloudcontrol.Resource` escape hatch.** CloudControl outputs are111 stringly-typed and `oneOf` fields don't patch cleanly. Use it only when no112 typed resource exists yet, and migrate off it when one ships.113114**Project-specific defaults — adopt for consistency, but confirm per repo:**115116- **Region `ap-northeast-1`**, `home: "aws"`, and `defaultTags` carrying117 `Project` / `Stage` / `ManagedBy: "sst"`.118- **Stage-gated lifecycle**: `removal: stage === "prod" ? "retain" : "remove"`119 and `protect: stage === "prod"` so prod resources survive a stack tear-down120 and non-prod previews clean up.121- **SSM Parameter Store as the out-of-graph contract** under a122 `/{app}/{stage}/{domain}/...` prefix — for consumers that aren't in the123 Pulumi graph (CI scripts, sibling apps, operators). For *same-app* Lambdas,124 prefer SST `link:` (it wires a real dependency edge and grants IAM); don't125 route same-app sharing through SSM. See `references/authoring.md` § Sharing.126- **Lazy `await import("./infra/<module>")` inside `run()`** so `sst dev`127 hot-reload stays light. (For testing, a module export still runs its top-level128 `new sst.aws.*` unless it's wrapped in a factory function — see129 `references/testing.md` for how to test infra.)130- **Source-level Vitest tests** on every infra module — a lightweight,131 house-style regression net asserting on the *source text* (resource names,132 index shapes, IAM scopes). It's a deliberate choice, not an SST limit: Pulumi133 *does* support runtime mocks (`@pulumi/pulumi/runtime`) for behavioral graph134 tests when a module has real logic. Source assertions don't replace a135 preview-deploy + smoke test. See `references/testing.md`.136- **An observability gate**: every new Lambda/queue/schedule gets an alarm and137 structured logging before merge. Whether you enforce this depends on the138 project, but it's cheap insurance. See `references/deploy-and-troubleshoot.md`139 § Observability.140141When you introduce a convention, say which bucket it's in ("this is universal"142vs "matching this repo's house style") so the user can override the143project-specific ones deliberately.144145## Working rhythm1461471. **Orient** (above) — map config, modules, tests, tooling.1482. **Verify syntax** with Context7 / AWS docs MCP if anything is non-obvious.149 Don't guess at a component's option name.1503. **Author** the resource/module following `references/authoring.md`. Match the151 surrounding file's commenting density and naming — these projects comment the152 *why* heavily, and a terse one-liner in a heavily-annotated file reads as a153 regression.1544. **Test** — add or update source-level assertions (`references/testing.md`) and155 run `npx vitest` (or the repo's `test` script). Run `npx sst diff` and/or156 `tsc --noEmit` to catch type and plan errors before deploying.1575. **Deploy/operate** per `references/deploy-and-troubleshoot.md`. Confirm the158 target account with `aws sts get-caller-identity` before any `sst deploy`.1596. **Clean up** any exported state files — they contain account IDs and ARNs and160 must not linger in `/tmp` or chat history.161162## What good looks like163164- The change is the smallest diff that satisfies the requirement, in the right165 `infra/` module, wired into `run()` in dependency order.166- Every Lambda gets the right runtime via the global transform (you didn't167 hand-set `runtime` unless intentionally diverging — e.g. a Python function).168- Cross-resource references use `link:` (in-graph) and/or `$interpolate`-scoped169 IAM; outputs other tools consume are published to SSM under the stage prefix.170- New infra has a matching source-level test, and the existing suite stays green.171- You confirmed AWS-side facts via the docs MCP and SST/Pulumi syntax via172 Context7 rather than relying on recall.173- Anything irreversible (deploy, `sst remove`, a resource-type migration) was174 flagged to the user with the account it targets, and migrations were planned175 as two PRs, not one.176177## Example178179**User request:**180181> Use @aws-sst-development for this task: SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework.182183## Limitations184185- Use this skill only when the task clearly matches its upstream source and local project context.186- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.187- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.