Index of every page on this site: llms.txt
All skills
Run it yourself

Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.

Use this Skill: https://skilld.dev/gh/aws/agent-toolkit-for-aws/aws-cdk

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈106 tokens for metadata: the name and description. ≈2.1k when used: this file. ≈21k more on demand in 10 files.

Description uses 5.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈426 characters, or 5.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

AWS CDK

Overview

Domain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.

When NOT to use: Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.

Critical Warnings

Deadly embrace: Removing a cross-stack reference deadlocks deployment (Export ... cannot be deleted as it is in use by ...). Preferred fix: weaken the reference first — CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH) then WEAK, then remove (three deploys). Legacy fallback: two-deploy this.exportValue() recipe. See troubleshooting-deployment.

Construct ID changes cause replacement: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always cdk diff before deploy. See refactor-and-prevent-replacement.

UPDATE_ROLLBACK_FAILED: Stack is stuck. Fix with cdk rollback $STACK or cdk rollback $STACK --orphan <LogicalId>. Express mode stacks are the exception — they cannot be rolled back at all. See troubleshooting-deployment.

Hotswap and express mode are development-only: --hotswap / --hotswap-fallback bypass CloudFormation and create drift on purpose; --express reports success before resources stabilize and disables automatic rollback. You MUST NOT use either in production. A failed --express deployment cannot be rolled back — recover by rolling forward with another --express deploy. See fast-deployments.

Non-empty S3 buckets persist after destroy: You MUST set both removalPolicy: DESTROY and autoDeleteObjects: true. Versioned buckets are worse — delete markers persist even after apparent deletion.

Common Workflows

Task Quick Command Details
Bootstrap cdk bootstrap aws://$ACCOUNT/$REGION bootstrap-and-project-setup
New TS project cdk init app --language typescript — use tsx, eslint-plugin-awscdk bootstrap-and-project-setup
New Python project cdk init app --language python — pin deps, use virtualenv bootstrap-and-project-setup
Deploy cdk synth --strict → cdk diff → cdk deploy Always diff before deploy to production
Fast dev iteration cdk deploy --hotswap-fallback, cdk watch, or cdk deploy --express — dev only, never production fast-deployments
cdk-nag Aspects.of(app).add(new AwsSolutionsChecks()) compliance-and-drift
Drift cdk drift $STACK (use --fail in CI) compliance-and-drift
Import resource cdk import (interactive or --resource-mapping for CI), cdk deploy --import-existing-resources import-and-migrate
Refactor safely cdk refactor --unstable=refactor — no property changes in same deploy refactor-and-prevent-replacement

Fast Deployments — Hotswap vs Express (dev only)

Both trade safety for speed and you MUST NOT use either in production.

Choosing between them: Use --hotswap / --hotswap-fallback for the fastest loop when you work mostly with hotswappable resources and drift does not matter. Use --express when drift is unacceptable, or your resources are not hotswappable.

Recovery workflows (hotswap drift via --revert-drift, rolling a failed --express deploy forward), the hotswappable-resource rules, and IAM/monitoring enforcement of the prod prohibition are all in the full guide: fast-deployments.

Troubleshooting

Error Cause → Fix
DeployFailed / DeploymentError CDK error isn't the root cause. cdk deploy $STACK --verbose, then cdk --unstable=diagnose diagnose $STACK (CLI ≥ 2.1120.0); else aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true — the first _FAILED event is the cause. Details
NoCredentials / ExpiredToken / AssumeRoleFailed aws sts get-caller-identity + cdk doctor. Expired SSO, missing env, missing sts:AssumeRole. Details
Asset errors (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) Path wrong, Docker not running, or bootstrap bucket perms. Use path.join(__dirname, ...). Details
AppRequired Add "app": "npx tsx bin/my-app.ts" to cdk.json. Details
AnnotationErrors Fix the underlying issue; suppress with NagSuppressions only as last resort. Details
ConcurrentReadLock / ConcurrentWriteLock rm -rf cdk.out then re-run. Parallel CI: --output ./cdk.out.$BUILD_ID. Details
BootstrapVersionValidation Re-bootstrap. Match --qualifier everywhere. Details
DependencyCycle Extract shared resource into third stack or use SSM for late-binding. Details
UnresolvedAccount Set explicit env: { account, region } on stack. Commit cdk.context.json. Details
NoStacksMatched CDK uses logical ID (2nd constructor arg), not CFN name. cdk list to find IDs. Details
Cannot find module (synth time) Run npx tsc --noEmit, check cdk.json app path matches tsconfig.json outDir, delete stale .js files. Python: activate venv. Details
V1 import paths / duplicate aws-cdk-lib V1 @aws-cdk/* imports, wrong Construct import, duplicate lib copies in monorepos. Details
Lambda Cannot find module (runtime) Wrong handler value, missing AWS SDK v3 migration, Python deps not bundled. Details
API Gateway multi-stage conflicts Set deploy: false on RestApi, create Deployment and Stage explicitly. Details
Change didn't deploy under --hotswap Changes to non-hotswappable resources are silently ignored and only logged — the command still reports success. Read the output; use --hotswap-fallback to force a CloudFormation deployment instead. Details
Failed --express deploy / can't roll back Express mode cannot use the Rollback Stack API, and a standard deploy MUST NOT be used to recover it. Roll forward: fix the cause, then cdk deploy $STACK --express. Details
Unexpected drift on a dev stack Hotswap and cdk watch create drift by design. Until reverted, the live resources — not CloudFormation's records — are authoritative. Reconcile with cdk deploy $STACK --revert-drift, which uses Drift Aware Changesets to bring live resources in line with the template (updates reality to match desired state; does NOT rewrite CF records to match drifted resources). Details

Construct Patterns

Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: node.defaultChild → addPropertyOverride. See construct-patterns.

Additional Resources

  • Search AWS documentation for "CDK Developer Guide", "CDK API Reference" and "CDK Pipelines" respectively

Security Considerations

  • OIDC for CI/CD credentials (no static keys)
  • --custom-permissions-boundary on bootstrap
  • grant*() for inter-resource IAM
  • cdk-nag + --strict in CI
  • Stateful resources in own stack with terminationProtection: true
  • Commit cdk.context.json

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides a comprehensive reference for AWS CDK infrastructure management. It includes extensive documentation on project setup, deployment workflows, and troubleshooting, with a strong emphasis on security best practices and operational safety.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 12d7f78. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago
metadata
{
  "version": "2"
}

README badge

README badge for aws/agent-toolkit-for-aws/aws-cdk