CDK Project Scaffold

Skill to initialize a new AWS CDK project with a standard toolchain.

When to Use This Skill

Use this skill when the user:

• Says "create CDK project", "scaffold CDK", "new CDK project", or "initialize CDK"
• Wants to start a new AWS infrastructure project with TypeScript
• Needs a production-ready CDK setup with testing and linting configured

Toolchain Overview

Tool	Role
mise	Version management for Node, pnpm, AWS CLI, etc.
pnpm	Package manager (2-day minimumReleaseAge via pnpm-workspace.yaml)
TypeScript	Type-safe development (ES2020 / NodeNext)
tsx	Direct TypeScript execution without compilation
oxlint	Fast Rust-based linter
oxfmt	Code formatter
vitest	Unit testing
knip	Unused code and dependency detection
prek	Pre-commit hook manager
aws-cdk	AWS CDK framework v2

Parameters

Parameter	Required	Default	Usage
PROJECT_NAME	Yes	—	package.json name field
AWS_REGION	No	us-east-1	AWS_REGION in .mcp.json

Implementation Steps

Execute the following steps in order.

1. Collect Parameters

Always confirm PROJECT_NAME with the user. If AWS_REGION is not specified, use us-east-1 as the default.

STACK_NAME is PROJECT_NAME converted to PascalCase.
Example: my-app → MyApp, gitlab-poc → GitlabPoc

PROJECT_KEBAB uses PROJECT_NAME as-is in kebab-case.

2. Create Directories

mkdir -p bin lib test scripts .claude

3. Generate Config Files

Read each template from this skill's assets/ directory, replace the following placeholders, and write to the project root:

• {{PROJECT_NAME}} → value of PROJECT_NAME
• {{AWS_REGION}} → value of AWS_REGION (default: us-east-1)

assets/ file	Output path
mise.toml	mise.toml
package.json.tmpl	package.json
pnpm-workspace.yaml	pnpm-workspace.yaml
.pre-commit-config.yaml	.pre-commit-config.yaml
.oxlintrc.json	.oxlintrc.json
.oxfmtrc.json	.oxfmtrc.json
knip.json	knip.json
.gitignore	.gitignore
.mcp.json.tmpl	.mcp.json
setup.sh	scripts/setup.sh
claude-settings.json	.claude/settings.json

4. Generate CDK Starter Code

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["es2020"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["bin/**/*", "lib/**/*", "test/**/*"]
}

cdk.json:

{
  "app": "pnpm cdk",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "node_modules",
      "test"
    ]
  },
  "context": {
    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
    "@aws-cdk/core:checkSecretUsage": true,
    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
    "@aws-cdk/aws-iam:minimizePolicies": true,
    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
    "@aws-cdk/aws-codepipeline-actions:useNewDefaultBranchForCodeCommitSource": true,
    "@aws-cdk/aws-codepipeline-actions:useNewDefaultBranchForCodeStarSource": true,
    "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
    "@aws-cdk/aws-iam:importedRoleStackSafeDefaultPolicyName": true,
    "@aws-cdk/aws-s3:setUniqueReplicationRoleName": true,
    "@aws-cdk/aws-cognito:enableSendEmailVerificationMessage": true,
    "@aws-cdk/core:enableStackNameDuplicates": false
  }
}

bin/app.ts (replace {{STACK_NAME}} and {{PROJECT_KEBAB}}):

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { {{STACK_NAME}}Stack } from '../lib/{{PROJECT_KEBAB}}-stack.js';

const app = new cdk.App();
new {{STACK_NAME}}Stack(app, '{{STACK_NAME}}Stack', {});

lib/{{PROJECT_KEBAB}}-stack.ts:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class {{STACK_NAME}}Stack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // TODO: Add your constructs here
  }
}

test/{{PROJECT_KEBAB}}-stack.test.ts:

import { App } from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { describe, it } from 'vitest';
import { {{STACK_NAME}}Stack } from '../lib/{{PROJECT_KEBAB}}-stack.js';

describe('{{STACK_NAME}}Stack', () => {
  it('synthesizes without errors', () => {
    const app = new App();
    const stack = new {{STACK_NAME}}Stack(app, 'TestStack');
    const template = Template.fromStack(stack);
    template.resourceCountIs('AWS::CloudFormation::WaitConditionHandle', 0);
  });
});

5. Run Setup

git init
chmod +x scripts/setup.sh
bash scripts/setup.sh

6. Verify

pnpm typecheck && pnpm test && pnpm knip && pnpm lint

Confirm all commands pass. If errors occur, review the output and fix accordingly.