AWS CDK

Apache-2.0

Featured markdown Development

awscdkinfrastructure-as-codecloudformationtypescriptpythondevops

Summary

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

Features

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

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

Copy the skill content with the button below.
Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
Ask the agent to apply the skill whenever the task matches.

Claude Code & Claude apps

Claude loads skills automatically from its skills directory.

Claude Code

Create a skill folder — personal: ~/.claude/skills/aws-cdk/, or per-project: .claude/skills/aws-cdk/
Save the skill content as SKILL.md inside that folder.
Claude Code picks it up automatically and invokes it when relevant.

mkdir -p ~/.claude/skills/aws-cdk

Claude.ai / Claude Desktop

Enable Skills under Settings → Capabilities, then upload the skill (a folder or zip containing SKILL.md).

One-prompt install

Paste this prompt into any agent with web access and it will install the skill for you.

Install the "AWS CDK" skill from Onei AI. Fetch https://onei.ai/skills/aws-cdk, extract the full skill content from the page, and save it where you load skills from (for Claude Code: .claude/skills/aws-cdk/SKILL.md). From now on, apply this skill whenever it is relevant to my request.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
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

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

## 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](references/troubleshooting-deployment.md) |
| **NoCredentials / ExpiredToken / AssumeRoleFailed** | `aws 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) |
| **AppRequired** | Add `"app": "npx tsx bin/my-app.ts"` to `cdk.json`. [Details](references/troubleshooting-synth.md) |
| **AnnotationErrors** | Fix the underlying issue; suppress with `NagSuppressions` only as last resort. [Details](references/troubleshooting-synth.md) |
| **ConcurrentReadLock / ConcurrentWriteLock** | `rm -rf cdk.out` then re-run. Parallel CI: `--output ./cdk.out.$BUILD_ID`. [Details](references/troubleshooting-synth.md) |
| **BootstrapVersionValidation** | Re-bootstrap. Match `--qualifier` everywhere. [Details](references/troubleshooting-credentials.md) |
| **DependencyCycle** | Extract shared resource into third stack or use SSM for late-binding. [Details](references/troubleshooting-synth.md) |
| **UnresolvedAccount** | Set explicit `env: { account, region }` on stack. Commit `cdk.context.json`. [Details](references/troubleshooting-credentials.md) |
| **NoStacksMatched** | CDK 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-lib** | V1 `@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 conflicts** | Set `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`

Usage Instructions

Learn how to use this skill with different AI agents.

Claude Desktop

Install the bundle in Claude Code with /plugin install aws-core@claude-plugins-official. The skill activates on CDK work — writing constructs, running cdk deploy/synth/diff, planning stack structure, or debugging CDK and CloudFormation errors.

Cursor

codex plugin marketplace add aws/agent-toolkit-for-aws, then enable the aws-core plugin.

Generic Instructions

npx skills add aws/agent-toolkit-for-aws/skills installs the skills into your agent's skills directory (for example ~/.kiro/skills/ or .claude/skills/).

Example Usage

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

Description

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.

Related Skills

Skill: Twilio AI Agent Architect

by Twilio

New

Planning skill that interrogates your use case before any code is written, then recommends the right Twilio Conversations stack — ConversationRelay, Memory, Intelligence, Orchestrator, TaskRouter — and the implementation skills to follow.

Development

Skill: fal.ai genmedia CLI

by fal.ai community

New

Foundational fal.ai skill that drives the genmedia CLI across 1200+ hosted generative model endpoints — smart routing, schema inspection, async queues and agent-parseable JSON.

DevelopmentDesign & Creative

Skill: Genkit for JavaScript

by Genkit (Google)

New

The official Genkit skill for Node.js and TypeScript — flows, Dotprompt files, tools and the beta agent API with sessions, interrupts and branching.

Development

Skill: Superpowers

by Jesse Vincent

New

An agentic software-development methodology: composable skills that push a coding agent through spec, plan, TDD and review instead of straight into code.

Development

Browse all skills →