CDK Upgrader

An Agent Skill that automatically upgrades TypeScript AWS CDK v2 projects to the latest stable version with intelligent merging, deprecated construct handling, and git integration. Shipped both standalone and inside a thin Kiro Power.

Quick Start

1. Install it as a skill — one command, no clone (a Power route exists too)
2. Open Kiro in a workspace containing TypeScript CDK v2 projects
3. Create a feature branch (git checkout -b feat/cdk-upgrade)
4. Ask Kiro: "Upgrade my CDK projects"
5. Review the planned changes and confirm

Example Workflow

You: Upgrade my CDK projects

Kiro: Found 2 CDK projects:
      - ./infrastructure (CDK v2.150.0)
      - ./services/api-stack (CDK v2.145.0)

      Environment check passed ✓

      Planned changes for ./infrastructure:
      - Update aws-cdk-lib: 2.150.0 → 2.263.0
      - Update aws-cdk: 2.150.0 → 2.1135.0
      - Replace tsconfig.json with latest template
      - Update Lambda runtime: nodejs18.x → nodejs24.x

      Proceed with upgrade? [Yes/No]

You: Yes

Kiro: ✓ ./infrastructure upgraded successfully
      ✓ ./services/api-stack upgraded successfully

      Created commits:
      - feat(cdk): upgrade CDK to version 2.263.0 (infrastructure)
      - feat(cdk): upgrade CDK to version 2.263.0 (api-stack)

To preview changes without modifying files: "Preview CDK upgrade changes" or "Dry-run CDK upgrade".

Installation

The upgrade logic lives in the skill. The Power is a thin wrapper that carries the same skill, so both routes run identical logic — pick whichever suits you.

As a skill (recommended)

DISABLE_TELEMETRY=1 npx skills add \
  https://github.com/frankhefeng/kiro-power-cdk-upgrader.git \
  --skill cdk-upgrader --agent kiro-cli --global --yes

Global scope only — -g is required, not a preference. The upgrader needs a clean working directory in the project it upgrades; a project-scope install would write .kiro/skills/cdk-upgrader/ into that project's own git tree, forcing you to commit the upgrader into the repository being upgraded or fail its own precondition. Keep -g on list, update and remove as well.

As a Power

The Power is supported and shipped: POWER.md declares the activation keywords and delegates to the bundled skills/cdk-upgrader/.

1. Open Kiro and navigate to the Powers panel
2. Click "Add Custom Power" or use the command palette (Cmd+Shift+P / Ctrl+Shift+P)
3. Select "Import Power from GitHub"
4. Enter the repository URL: https://github.com/frankhefeng/kiro-power-cdk-upgrader

Or clone it locally and open the folder in Kiro — the Power is detected automatically from POWER.md.

Switching from a Power install to a skill install

Installing the skill alongside a Power leaves two copies of the workflow where the Power's can win. Remove the Power first, then install the skill — that order fails safe, because the window between the two has nothing installed rather than two things competing.

1. Remove the Power in the Kiro Powers panel.
2. Confirm nothing is left behind: ~/.kiro/powers/installed/kiro-power-cdk-upgrader should no longer exist.
3. Install the skill with the command above.

Repository Layout

POWER.md                          Power wrapper — keywords, prerequisites, delegates to the skill
skills/cdk-upgrader/
  SKILL.md                        The workflow — loaded on activation
  references/*.md                 Detail — loaded on demand, per step

All execution logic lives in the skill. The Power carries it, declares the activation keywords, and documents the blast radius.

Features

• Multi-project discovery and selective upgrades
• Version selection with a 7-day stability window, pinned exactly so the choice survives lockfile regeneration
• Package ownership computed from a baseline-versus-target scaffold diff — superseded packages are removed, shared ones are kept with a warning
• Intelligent per-file merging (replace, merge, or preserve based on file type)
• Deprecated construct detection and automatic migration
• Lambda runtime upgrades (Node.js, Python, Java, .NET)
• Git integration with semantic commits
• Dry-run mode for previewing changes
• Acceptance gates: cdk synth and npm audit --audit-level=high must both pass
• Bootstrap version check that derives the target account and qualifier from the project itself and predicts deploy-stage failures before the pipeline runs
• Error handling with retry mechanisms and project isolation

Supported Scope

• Language: TypeScript only
• CDK Version: CDK v2 only
• Platform: the skill runs in the Kiro IDE and CLI; the Power wrapper is IDE-only (Kiro CLI support for Powers requires v3)

Contributing

We welcome contributions. Files you can extend:

• Add deprecated construct mappings in skills/cdk-upgrader/references/deprecated-constructs.md
• Update runtime upgrade paths in skills/cdk-upgrader/references/lambda-runtimes.md
• Add troubleshooting solutions in skills/cdk-upgrader/references/troubleshooting.md

Use semantic commit messages (feat:, fix:, docs:) and submit pull requests.

Reporting Issues

1. Check existing issues to avoid duplicates
2. Include: CDK version you're upgrading from/to, Node.js and npm versions, error messages, and steps to reproduce

License

MIT License - see LICENSE file for details.

Author

Feng He

Links

• Repository
• AWS CDK Documentation
• Kiro Documentation