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/zxkane/aws-sst-development13---1415# SST v4 for AWS16## When to Use1718Use 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,...192021SST v4 (the "Ion" engine) is a Pulumi-backed IaC framework: you describe AWS22resources in TypeScript and SST/Pulumi reconciles them into your account. It23gives you high-level `sst.aws.*` components (Function, Bucket, Dynamo, Cron,24Service, …) that expand into many underlying resources, plus an escape hatch to25*any* raw Pulumi `aws.*` resource for the long tail. This skill encodes a26production-proven way to author, link, test, deploy, and troubleshoot SST27stacks on AWS — distilled from real multi-stack projects that have paid for28each lesson with a prod incident.2930**SST and Pulumi are third-party — verify current syntax with Context7**31(`resolve-library-id` → `query-docs` for `sst` or `pulumi-aws`) when you're32unsure about a component's options. Verify AWS-side facts (service limits,33model IDs, IAM action names, region availability) with the AWS docs MCP, never34from memory. The patterns here are the *how*; the docs are the *what*.3536## When you're invoked3738Figure out which mode you're in and jump to the right reference:3940| Situation | Go to |41|-----------|-------|42| New project, or adding a resource/module to an existing SST app | **Author** → `references/authoring.md` |43| Wiring one module's output into another (links, SSM, IAM scope) | **Author** → `references/authoring.md` § Sharing |44| Writing tests for infra so changes don't silently break | **Test** → `references/testing.md` |45| Running a deploy, or a deploy just failed | **Deploy/Operate** → `references/deploy-and-troubleshoot.md` |46| Migrating a resource between Pulumi types, renaming a physical name | **Deploy/Operate** → `references/deploy-and-troubleshoot.md` § Migrations |4748Always read the relevant reference before editing — they carry the *why* behind49each rule, which matters more than the rule itself.5051## Orientation: read the repo before you touch it5253SST projects are conventional but not identical. Before editing, build a quick54map so your change matches the house style instead of fighting it:55561. **`sst.config.ts`** — the app name, `home`, providers/region, `defaultTags`,57 any global `$transform` (Node runtime pin, bundle fixups), and the order in58 which `run()` imports `infra/` modules. The import order *is* the dependency59 order; respect it.602. **`infra/`** — one file per domain (storage, functions, api, observability…).61 This is where resources are declared. Check for an `infra/CLAUDE.md` — these62 projects keep IaC-specific rules there, and it's the single most valuable63 file to read first.643. **`infra/tests/`** — source-level Vitest assertions that pin resource65 invariants. If they exist, your change must keep them green and probably66 needs a new assertion.674. **`package.json` / `.nvmrc`** — package manager (npm vs pnpm), Node version,68 and the `sst`/`pulumi` versions actually installed.6970Run `npx sst version` to confirm you're on v4/Ion (the `$config` + `.sst/platform/`71signature). v2/v3 ("SST Classic", CDK-based) is a different framework — these72patterns don't apply there.7374## The conventions, and which are universal vs tunable7576The projects this skill is built from share a deliberate house style. Some of it77is **universal** (true for any SST v4 + AWS project — apply it everywhere); some78is **project-specific** (a sensible default these projects chose — adopt it for79consistency, but recognize a project may differ).8081**Universal — these principles hold for any SST v4 + AWS project:**8283- **Control the Node runtime deliberately, in one place.** Don't leave it to84 whatever the installed SST happens to default to. The idiom is a single global85 `$transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" })` in86 `run()` — `??=` is correct here (the transform runs before the component87 applies its own default, so it fills in only when the user didn't set one).88 Recent SST already defaults to a current Node runtime, so check the installed89 default first (Context7); the transform is then version-independence insurance90 so a future SST downgrade can't silently move your fleet. See91 `references/authoring.md`.92- **Never interpolate a Pulumi `Output<T>` into a plain JS template literal.**93 Use `$interpolate` (or `pulumi.interpolate`). A bare top-level94 `` `${bucket.arn}/*` `` stringifies the `Output` to a `[Output<T>]` placeholder95 and produces a broken ARN that only fails at deploy time (it type-checks and96 `sst dev` runs fine). The fix is `$interpolate``` `${bucket.arn}/*` ``. This97 has caused prod deploy outages. See `references/authoring.md` § Outputs.98- **Migrating a resource between Pulumi *types* should default to two PRs** —99 Pulumi creates-before-destroys, so for a uniqueness-constrained AWS name100 (bucket, IAM role, gateway) the old resource still owns it and the create101 fails with `ConflictException`. Two sequential deploys (teardown, then102 recreate) is the conservative default; `aliases:` / `pulumi import` / state103 surgery can bridge identity in some cases but only with a reviewed plan. See104 `references/deploy-and-troubleshoot.md` § Migrations.105- **Prefer typed `sst.aws.*` / `aws.*` resources over the106 `aws.cloudcontrol.Resource` escape hatch.** CloudControl outputs are107 stringly-typed and `oneOf` fields don't patch cleanly. Use it only when no108 typed resource exists yet, and migrate off it when one ships.109110**Project-specific defaults — adopt for consistency, but confirm per repo:**111112- **Region `ap-northeast-1`**, `home: "aws"`, and `defaultTags` carrying113 `Project` / `Stage` / `ManagedBy: "sst"`.114- **Stage-gated lifecycle**: `removal: stage === "prod" ? "retain" : "remove"`115 and `protect: stage === "prod"` so prod resources survive a stack tear-down116 and non-prod previews clean up.117- **SSM Parameter Store as the out-of-graph contract** under a118 `/{app}/{stage}/{domain}/...` prefix — for consumers that aren't in the119 Pulumi graph (CI scripts, sibling apps, operators). For *same-app* Lambdas,120 prefer SST `link:` (it wires a real dependency edge and grants IAM); don't121 route same-app sharing through SSM. See `references/authoring.md` § Sharing.122- **Lazy `await import("./infra/<module>")` inside `run()`** so `sst dev`123 hot-reload stays light. (For testing, a module export still runs its top-level124 `new sst.aws.*` unless it's wrapped in a factory function — see125 `references/testing.md` for how to test infra.)126- **Source-level Vitest tests** on every infra module — a lightweight,127 house-style regression net asserting on the *source text* (resource names,128 index shapes, IAM scopes). It's a deliberate choice, not an SST limit: Pulumi129 *does* support runtime mocks (`@pulumi/pulumi/runtime`) for behavioral graph130 tests when a module has real logic. Source assertions don't replace a131 preview-deploy + smoke test. See `references/testing.md`.132- **An observability gate**: every new Lambda/queue/schedule gets an alarm and133 structured logging before merge. Whether you enforce this depends on the134 project, but it's cheap insurance. See `references/deploy-and-troubleshoot.md`135 § Observability.136137When you introduce a convention, say which bucket it's in ("this is universal"138vs "matching this repo's house style") so the user can override the139project-specific ones deliberately.140141## Working rhythm1421431. **Orient** (above) — map config, modules, tests, tooling.1442. **Verify syntax** with Context7 / AWS docs MCP if anything is non-obvious.145 Don't guess at a component's option name.1463. **Author** the resource/module following `references/authoring.md`. Match the147 surrounding file's commenting density and naming — these projects comment the148 *why* heavily, and a terse one-liner in a heavily-annotated file reads as a149 regression.1504. **Test** — add or update source-level assertions (`references/testing.md`) and151 run `npx vitest` (or the repo's `test` script). Run `npx sst diff` and/or152 `tsc --noEmit` to catch type and plan errors before deploying.1535. **Deploy/operate** per `references/deploy-and-troubleshoot.md`. Confirm the154 target account with `aws sts get-caller-identity` before any `sst deploy`.1556. **Clean up** any exported state files — they contain account IDs and ARNs and156 must not linger in `/tmp` or chat history.157158## What good looks like159160- The change is the smallest diff that satisfies the requirement, in the right161 `infra/` module, wired into `run()` in dependency order.162- Every Lambda gets the right runtime via the global transform (you didn't163 hand-set `runtime` unless intentionally diverging — e.g. a Python function).164- Cross-resource references use `link:` (in-graph) and/or `$interpolate`-scoped165 IAM; outputs other tools consume are published to SSM under the stage prefix.166- New infra has a matching source-level test, and the existing suite stays green.167- You confirmed AWS-side facts via the docs MCP and SST/Pulumi syntax via168 Context7 rather than relying on recall.169- Anything irreversible (deploy, `sst remove`, a resource-type migration) was170 flagged to the user with the account it targets, and migrations were planned171 as two PRs, not one.172173## Example174175**User request:**176177> Use @aws-sst-development for this task: SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework.178179## Limitations180181- Use this skill only when the task clearly matches its upstream source and local project context.182- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.183- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.