Bundled upstream support

Supporting files are included at skill-relative paths. See UPSTREAM-NOTICE.md for their pinned sources, licenses, hashes, and import changes.

Restored helper safety

scripts/validate-stack.sh runs cdk synth from the caller-selected project root, which executes that project's CDK application and dependencies, can write cdk.out, and may contact AWS context providers if the project requires lookups. Review the project and AWS context before invoking it. The helper does not deploy; deployment needs separate user authorization.

AWS CDK Development

This skill provides comprehensive guidance for developing AWS infrastructure using the Cloud Development Kit (CDK), with integrated MCP servers for accessing latest AWS knowledge and CDK utilities.

AWS Documentation Requirement

Always verify AWS facts using MCP tools (mcp__aws-mcp__* or mcp__*awsdocs*__*) before answering. Check actual tool availability; no dependency is auto-loaded by this catalog. If MCP is unavailable, use current official AWS documentation, or report the missing capability without automatically installing a server.

CDK-Specific MCP Guidance

AWS Labs replaced the dedicated CDK MCP server (awslabs.cdk-mcp-server) with the broader awslabs.aws-iac-mcp-server, which covers CDK alongside CloudFormation and other AWS infrastructure-as-code workflows.

For CDK construct lookups, best-practice recommendations, and pattern guidance, install awslabs.aws-iac-mcp-server. It ships in the deploy-on-aws plugin from awslabs/agent-plugins, or can be registered directly with claude mcp add aws-iac uvx awslabs.aws-iac-mcp-server@latest.

When to reach for it:

• CDK construct recommendations and API lookups
• CDK and CloudFormation best-practice patterns
• Validation of synthesized templates
• Cross-resource configuration guidance

When to Use This Skill

Use this skill when:

• Creating new CDK stacks or constructs
• Refactoring existing CDK infrastructure
• Implementing Lambda functions within CDK
• Following AWS CDK best practices
• Validating CDK stack configurations before deployment
• Verifying AWS service capabilities and regional availability

Core CDK Principles

Resource Naming

CRITICAL: Do NOT explicitly specify resource names when they are optional in CDK constructs.

Why: CDK-generated names enable:

• Reusable patterns: Deploy the same construct/pattern multiple times without conflicts
• Parallel deployments: Multiple stacks can deploy simultaneously in the same region
• Cleaner shared logic: Patterns and shared code can be initialized multiple times without name collision
• Stack isolation: Each stack gets uniquely identified resources automatically

Pattern: Let CDK generate unique names automatically using CloudFormation's naming mechanism.

// ❌ BAD - Explicit naming prevents reusability and parallel deployments
new lambda.Function(this, 'MyFunction', {
  functionName: 'my-lambda',  // Avoid this
  // ...
});

// ✅ GOOD - Let CDK generate unique names
new lambda.Function(this, 'MyFunction', {
  // No functionName specified - CDK generates: StackName-MyFunctionXXXXXX
  // ...
});

Security Note: For different environments (dev, staging, prod), follow AWS Security Pillar best practices by using separate AWS accounts rather than relying on resource naming within a single account. Account-level isolation provides stronger security boundaries.

Lambda Function Development

Use the appropriate Lambda construct based on runtime:

TypeScript/JavaScript: Use aws-cdk-lib/aws-lambda-nodejs (CDK v2)

import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

new NodejsFunction(this, 'MyFunction', {
  entry: 'lambda/handler.ts',
  handler: 'handler',
  // Automatically handles bundling, dependencies, and transpilation
});

Python: Use the version-matched @aws-cdk/aws-lambda-python-alpha package

import { PythonFunction } from '@aws-cdk/aws-lambda-python-alpha';

new PythonFunction(this, 'MyFunction', {
  entry: 'lambda',
  index: 'handler.py',
  handler: 'handler',
  // Automatically handles dependencies and packaging
});

Benefits:

• Automatic bundling and dependency management
• Transpilation handled automatically
• No manual packaging required
• Consistent deployment patterns

Pre-Deployment Validation

Use a multi-layer validation strategy for comprehensive CDK quality checks:

#### Layer 1: Real-Time IDE Feedback (Recommended)

For TypeScript/JavaScript projects:

Install cdk-nag for synthesis-time validation:

npm install --save-dev cdk-nag

Add to your CDK app:

import { Aspects } from 'aws-cdk-lib';
import { AwsSolutionsChecks } from 'cdk-nag';

const app = new App();
Aspects.of(app).add(new AwsSolutionsChecks());

Optional - VS Code users: Install [CDK NAG Validato