--- name: aws-sst-development description: "SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework." risk: critical source: https://github.com/zxkane/aws-skills/tree/main/plugins/aws-iac/skills/aws-sst-development source_repo: zxkane/aws-skills source_type: community date_added: 2026-07-01 license: MIT license_source: https://github.com/zxkane/aws-skills/blob/main/LICENSE --- ## Bundled upstream support Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](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 set of project-derived patterns to author, link, test, deploy, and troubleshoot SST stacks on AWS . The catalog review does not establish those incident or production-validation claims. **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: 1. **`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. 2. **`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. 3. **`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. 4. **`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 (Classic) is CDK-based; v3 also introduced the Pulumi-backed Ion architecture. Verify v3-to-v4 breaking changes rather than classifying v3 as CDK-based. ## 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` into a plain JS template literal.** Use `$interpolate` (or `pulumi.interpolate`). A bare top-level `` `${bucket.arn}/*` `` stringifies the `Output` to a `[Output]` 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. - **Plan stateful migrations before replacement.** Inspect type/URN/physical identity and provider-supported import/alias/state-move options. Never default to destroying a database/bucket just to free its name. A reviewed export/restore, parallel migration or preserved-resource adoption may avoid loss; any destructive recreate needs explicit downtime/data-loss acceptance and a tested recovery plan. See the migration reference. - **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/")` 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. CLI and config evaluation can run arbitrary project code, including during diff/preview, and dev/deploy can create billable resources. Use the locked local CLI (do not let npx fetch an unreviewed package), verify account/role/region/stage and authorization before cloud operations. Context7/AWS MCP are optional documentation routes; use official web docs if unavailable. ## Working rhythm 1. **Orient** (above) — map config, modules, tests, tooling. 2. **Verify syntax** with Context7 / AWS docs MCP if anything is non-obvious. Don't guess at a component's option name. 3. **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. 4. **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. 5. **Deploy/operate** per `references/deploy-and-troubleshoot.md`. Confirm the target account with `aws sts get-caller-identity` before any `sst deploy`. 6. **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 stateful migrations had a reviewed preservation/rollback plan. ## 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. --- Source attribution: zxkane/aws-skills contributors, via Agentic Awesome Skills Original project: https://github.com/zxkane/aws-skills License: MIT + CC-BY-4.0 License information: https://creativecommons.org/licenses/by/4.0/ Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Mengxin Zhu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: zxkane/aws-skills contributors, via Agentic Awesome Skills Original project: https://github.com/zxkane/aws-skills Attribution basis: Recorded upstream repository Fields of work: Development & Engineering Roles: DevOps / SRE Specialties: Specialty not specified Tools: Tool not specified Country applicability: Country not specified Classification basis: Dave AI task classification from package title, description, and declared metadata Instruction SHA-256: cedfb1bf5321ea1331e2bfd38fc9a579ab0bee7d538a12592ddc91566a348b7c Metadata reviewed: 2026-10-27 This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.