AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides comprehensive support for the AWS CDK, covering the full lifecycle of infrastructure-as-code development. It includes best practices for construct patterns, environment bootstrapping, compliance enforcement, drift detection, and safe refactoring. The skill also offers detailed troubleshooting workflows for common CLI, CloudFormation, and deployment errors, ensuring developers can maintain stable and secure AWS environments using TypeScript or Python.
What it does
- Guides the authoring of AWS infrastructure using L1 and L2 CDK constructs.
- Provides procedures for bootstrapping AWS accounts and regions for CDK usage.
- Enforces security and compliance policies using cdk-nag integration.
- Detects and resolves configuration drift between live resources and CDK templates.
- Offers systematic troubleshooting for deployment failures and asset management issues.
- Details safe refactoring patterns to prevent accidental resource replacement.
When to use it
- When initializing new AWS infrastructure projects in TypeScript or Python.
- When planning complex stack architectures or managing cross-stack references.
- When diagnosing deployment errors or stuck CloudFormation stacks.
- When integrating security compliance checks into the CI/CD pipeline.
- When importing existing AWS resources into a CDK-managed stack.
- When refactoring existing infrastructure without causing data loss or resource replacement.
Advantages
- Reduces risk of accidental resource replacement during stack refactoring.
- Ensures infrastructure compliance through automated policy enforcement.
- Provides clear, actionable steps for resolving complex deployment deadlocks.
- Standardizes project structure and dependency management for CDK apps.
- Offers safe, documented patterns for handling stateful resources and S3 buckets.
Usage examples
- “How do I safely remove a cross-stack reference without breaking my deployment?”
- The agent explains the three-deploy process: weakening the reference strength to WEAK before final removal to avoid the deadly embrace deadlock.
- “My stack is stuck in UPDATE_ROLLBACK_FAILED. How do I fix it?”
- The agent provides commands to use cdk rollback or cdk rollback --orphan to recover the stack state.
- “How can I ensure my CDK app follows AWS best practices?”
- The agent instructs on installing and applying cdk-nag rule packs like AwsSolutionsChecks as an Aspect to the application.
- “I need to import an existing S3 bucket into my CDK stack. What is the process?”
- The agent outlines the cdk import workflow and the necessary steps to align the existing resource with the CDK template.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/aws/aws-cdk/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip aws-cdk.zip -d .agents/skills
Documentation by AWS
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-boundaryon bootstrapgrant*()for inter-resource IAMcdk-nag+--strictin CIStateful resources in own stack with
terminationProtection: trueCommit
cdk.context.json
Files
- ATTRIBUTION.mdAdded by AutoGineer879 B
- LICENSELicence file added by AutoGineer9.9 KiB
- NOTICELicence file added by AutoGineer67 B
- SKILL.md8.7 KiB
- references/bootstrap-and-project-setup.md8.0 KiB
- references/compliance-and-drift.md5.2 KiB
- references/construct-patterns.md10.4 KiB
- references/fast-deployments.md13.4 KiB
- references/import-and-migrate.md6.3 KiB
- references/refactor-and-prevent-replacement.md6.2 KiB
- references/troubleshooting-credentials.md5.8 KiB
- references/troubleshooting-deployment.md12.9 KiB
- references/troubleshooting-synth.md8.8 KiB
- references/v1-to-v2-migration.md3.2 KiB
references/v1-to-v2-migration.md
CDK v1 to v2 Migration
Table of Contents
Overview
V1 Import Paths
Wrong Construct Import
Duplicate aws-cdk-lib
Overview
CDK v2 consolidated all @aws-cdk/* packages into a single aws-cdk-lib package and moved Construct to the standalone constructs package. These changes cause three common error patterns when migrating from v1 or when mixing v1/v2 code.
V1 Import Paths
Symptom
Cannot find module '@aws-cdk/aws-ec2'
Cannot find module '@aws-cdk/aws-s3'
Cannot find module '@aws-cdk/core'Cause
CDK v2 consolidated all @aws-cdk/* packages into aws-cdk-lib. Old v1 package names no longer resolve.
Fix
Replace v1 imports with v2 equivalents:
// Wrong (v1)
import * as ec2 from '@aws-cdk/aws-ec2';
import * as s3 from '@aws-cdk/aws-s3';
import { Construct } from '@aws-cdk/core';
// Correct (v2)
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';You MUST also remove all @aws-cdk/* packages from package.json dependencies and replace with a single aws-cdk-lib dependency.
Wrong Construct Import
Symptom
Argument of type 'this' is not assignable to parameter of type 'Construct'This error appears even though the code looks correct — the types have the same name but come from different packages.
Cause
Construct was imported from @aws-cdk/core or aws-cdk-lib instead of the standalone constructs package. In CDK v2, all constructs MUST extend Construct from the constructs package.
Fix
// Wrong
import { Construct } from 'aws-cdk-lib';
import { Construct } from '@aws-cdk/core';
// Correct
import { Construct } from 'constructs';You MUST ensure constructs is listed as a dependency in package.json.
Duplicate aws-cdk-lib
Symptom
Argument of type 'Function' is not assignable to parameter of type 'IFunction'
Argument of type 'Bucket' is not assignable to parameter of type 'IBucket'TypeScript uses structural typing, but CDK classes contain private members, which causes TypeScript to treat them nominally. When two copies of aws-cdk-lib exist, the private members originate from different class declarations, making types like Function and IFunction from different copies incompatible.
Cause
Multiple copies of aws-cdk-lib exist in the module graph. Common causes:
Monorepo with improperly hoisted dependencies
Shared construct library declares
aws-cdk-libas a regular dependency instead of a peer dependencynpm linkorfile:protocol pulling in a second copy
Diagnosis
npm ls aws-cdk-libIf more than one version appears, you have duplicates.
Fix
You MUST make
aws-cdk-libandconstructspeer dependencies in shared construct librariesRun
npm dedupeto collapse duplicatesIn monorepos, hoist
aws-cdk-libto the root workspaceVerify with
npm ls aws-cdk-lib— only one copy SHOULD appear
If npm dedupe alone does not resolve it, reset the install:
rm -rf node_modules && npm ci && npm dedupeRequirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs Python, Needs Node.js
Security
What our scanner noticed· Medium risk
- References to credential files
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- AWS
- Publisher
- AWS (Official)
- Source
- aws/agent-toolkit-for-aws · skills/core-skills/aws-cdk · commit 0a218f8
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- NOTICE (added by AutoGineer from NOTICE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
- Also distributed in
- aws/agent-toolkit-for-aws
AutoGineer is not affiliated with or endorsed by AWS.
Related skills
Deployment Strategies Terraform Specialist
Seth Hobson· Community
An expert Terraform and OpenTofu specialist for advanced infrastructure automation, state management, and enterprise-grade IaC patterns.
Cloud and DevOpsClaude CodeMITGitHub stars of the source repository42.3k
Terraform Module Library
Seth Hobson· Community
A comprehensive guide to building reusable, production-ready Terraform modules across AWS, Azure, GCP, and OCI.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository42.3k
Cloud Infrastructure Terraform Specialist
Seth Hobson· Community
An expert Terraform and OpenTofu specialist for advanced infrastructure automation, module design, and enterprise-grade GitOps workflows.
Cloud and DevOpsClaude CodeMITGitHub stars of the source repository42.3k
Cicd Automation Terraform Specialist
Seth Hobson· Community
An expert Terraform and OpenTofu specialist for advanced infrastructure automation, state management, and enterprise-grade GitOps workflows.
Cloud and DevOpsClaude CodeMITGitHub stars of the source repository42.3k
Terraform Azure Planning
GitHubOfficial
An expert Azure Cloud Engineering persona that generates structured Terraform implementation plans.
Cloud and DevOpsGitHub CopilotMITGitHub stars of the source repository40.9k
Terratest Module Testing
GitHubOfficial
Generate and refactor Go Terratest suites for Terraform modules with CI-safe patterns and negative-path validation.
Cloud and DevOpsGitHub CopilotMITGitHub stars of the source repository40.9k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-cdk.zip