Skip to content
AWS CDK

AWS CDK Skill

Official AWS skill for authoring, deploying and debugging CDK stacks — construct patterns, bootstrap, drift, resource import and the CloudFormation errors that trap people.

GitHub Docs
Featured DevOps & Infrastructure
Released
v1
Apache-2.0
69 views

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from aws/agent-toolkit-for-aws.

$ npx skills add aws/agent-toolkit-for-aws --skill aws-cdk

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/aws-cdk/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/aws/agent-toolkit-for-aws.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/core-skills/aws-cdk ~/.claude/skills/aws-cdk

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/aws-cdk/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Guides CDK construct authoring in TypeScript and Python
  • Documents the deadly-embrace cross-stack reference deadlock and the three-deploy ReferenceStrength fix
  • Warns that renaming a construct changes its logical ID and replaces the resource
  • Covers UPDATE_ROLLBACK_FAILED recovery with cdk rollback and --orphan
  • Explains why non-empty S3 buckets survive cdk destroy without removalPolicy plus autoDeleteObjects
  • Reference files for bootstrapping, drift resolution, resource import and safe refactoring

aws-cdk is one of the core skills in Amazon's Agent Toolkit for AWS, the company's officially supported bundle of MCP servers, skills and plugins for coding agents. It gives an agent working domain knowledge of the AWS Cloud Development Kit rather than generic infrastructure advice.

The valuable part is not the happy path — it is the failure modes the skill front-loads as critical warnings, because these are the CDK problems that cost hours:

  • Deadly embrace. Removing a cross-stack reference deadlocks deployment with Export ... cannot be deleted as it is in use by .... The skill's preferred fix is to weaken the reference first — CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH), then WEAK, then remove — a three-deploy sequence, with the legacy two-deploy this.exportValue() recipe as a fallback.
  • Construct ID changes cause replacement. Renaming or moving a construct changes its logical ID, so CloudFormation replaces the resource. For stateful resources that means data loss. The skill insists on cdk diff before every deploy.
  • UPDATE_ROLLBACK_FAILED. A stuck stack is recovered with cdk rollback $STACK, or cdk rollback $STACK --orphan <LogicalId>.
  • S3 buckets survive destroy. You need both removalPolicy: DESTROY and autoDeleteObjects: true; versioned buckets are worse still, because delete markers persist.

Beyond the warnings, bundled reference files cover bootstrapping and project setup, deployment troubleshooting, drift resolution, importing existing resources into a stack, and refactoring without triggering replacement. The skill explicitly scopes itself out of raw CloudFormation YAML/JSON, SAM, Terraform, Pulumi and general CI/CD, which keeps it from being invoked on tasks it has no special knowledge of.

Installation. Claude Code: /plugin install aws-core@claude-plugins-official. Codex and Cursor: codex plugin marketplace add aws/agent-toolkit-for-aws. Kiro and other agents: npx skills add aws/agent-toolkit-for-aws/skills. Licensed Apache-2.0.

Best for teams already committed to CDK who want their agent to stop suggesting resource-replacing refactors. If your stacks are Terraform or Pulumi, this is the wrong skill — look at the HashiCorp and Pulumi skill sets instead.

Try it

Once installed, ask your agent something like:

I renamed a construct and cdk diff now wants to replace my DynamoDB table. How do I refactor this without losing data?

SKILL.md

The instructions your agent loads, as published by Amazon Web Services.

SKILL.md
name
aws-cdk
description
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Always use 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.
metadata
version: "1"

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](references/troubleshooting-deployment.md).

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](references/refactor-and-prevent-replacement.md).

UPDATE_ROLLBACK_FAILED: Stack is stuck. Fix with cdk rollback $STACK or cdk rollback $STACK --orphan <LogicalId>. See [troubleshooting-deployment](references/troubleshooting-deployment.md).

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
TaskQuick CommandDetails
Bootstrapcdk bootstrap aws://$ACCOUNT/$REGION[bootstrap-and-project-setup](references/bootstrap-and-project-setup.md)
New TS projectcdk init app --language typescript — use tsx, eslint-plugin-awscdk[bootstrap-and-project-setup](references/bootstrap-and-project-setup.md)
New Python projectcdk init app --language python — pin deps, use virtualenv[bootstrap-and-project-setup](references/bootstrap-and-project-setup.md)
Deploycdk synth --strict → cdk diff → cdk deployAlways diff before deploy to prod
cdk-nagAspects.of(app).add(new AwsSolutionsChecks())[compliance-and-drift](references/compliance-and-drift.md)
Driftcdk drift $STACK (use --fail in CI)[compliance-and-drift](references/compliance-and-drift.md)
Import resourcecdk import (interactive or --resource-mapping for CI), cdk deploy --import-existing-resources[import-and-migrate](references/import-and-migrate.md)
Refactor safelycdk refactor --unstable=refactor — no property changes in same deploy[refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md)
Troubleshooting
ErrorCause → Fix
DeployFailed / DeploymentErrorCDK 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](references/troubleshooting-deployment.md)
NoCredentials / ExpiredToken / AssumeRoleFailedaws sts get-caller-identity + cdk doctor. Expired SSO, missing env, missing sts:AssumeRole. [Details](references/troubleshooting-credentials.md)
Asset errors (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed)Path wrong, Docker not running, or bootstrap bucket perms. Use path.join(__dirname, ...). [Details](references/troubleshooting-synth.md)
AppRequiredAdd "app": "npx tsx bin/my-app.ts" to cdk.json. [Details](references/troubleshooting-synth.md)
AnnotationErrorsFix the underlying issue; suppress with NagSuppressions only as last resort. [Details](references/troubleshooting-synth.md)
ConcurrentReadLock / ConcurrentWriteLockrm -rf cdk.out then re-run. Parallel CI: --output ./cdk.out.$BUILD_ID. [Details](references/troubleshooting-synth.md)
BootstrapVersionValidationRe-bootstrap. Match --qualifier everywhere. [Details](references/troubleshooting-credentials.md)
DependencyCycleExtract shared resource into third stack or use SSM for late-binding. [Details](references/troubleshooting-synth.md)
UnresolvedAccountSet explicit env: { account, region } on stack. Commit cdk.context.json. [Details](references/troubleshooting-credentials.md)
NoStacksMatchedCDK uses logical ID (2nd constructor arg), not CFN name. cdk list to find IDs. [Details](references/troubleshooting-synth.md)
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](references/troubleshooting-synth.md)
V1 import paths / duplicate aws-cdk-libV1 @aws-cdk/* imports, wrong Construct import, duplicate lib copies in monorepos. [Details](references/v1-to-v2-migration.md)
Lambda Cannot find module (runtime)Wrong handler value, missing SDK v3 migration, Python deps not bundled. [Details](references/troubleshooting-deployment.md)
API Gateway multi-stage conflictsSet deploy: false on RestApi, create Deployment and Stage explicitly. [Details](references/troubleshooting-deployment.md)
Construct Patterns

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

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
Install

Build multi-step Lambda workflows that survive interruption and run for up to a year — the replay model, step operations, wait/callback patterns, saga-style compensation and local testing.

Browse all skills →