Aws Transform

AWS Transform (ATX)

Overview

Perform code upgrades, migrations, and transformations using AWS Transform (ATX). Supports any-to-any transformations: language version upgrades (Java, Python, Node.js, etc.), framework migrations, AWS SDK migrations, library upgrades, code refactoring, architecture changes, and custom organization-specific transformations.

Two execution modes:

• Local mode: Runs the ATX CLI directly on the user's machine. Best for 1-9 repos.
• Remote mode: Runs transformations at scale via AWS Batch/Fargate containers. Best for 10+ repos or when the user prefers cloud execution. Infrastructure is auto-deployed with user consent.

You handle the full workflow: inspecting repos, matching them to available transformation definitions, collecting configuration, and executing transformations in either mode — the user just provides repos and confirms the plan.

Greet and Wait

On activation, introduce AWS Transform with this exact text -- don't print the above Overview text to the user, that is just for your reference:

"The agents modernizing the world's infrastructure and software — now accessible to your preferred AI assistant.

AWS Transform is a full modernization factory — compressing years of transformation work into months across infrastructure migrations, mainframe modernization, and continuous tech debt reduction. Today, with this skill, you have access to AWS Transform custom, the first of a growing library of playbooks.

AWS Transform custom can help you:

• Upgrade Java, Python, and Node.js to modern versions
• Migrate AWS SDKs (Java SDK v1→v2, boto2→boto3, JS SDK v2→v3)
• Handle framework migrations, library upgrades, and code refactoring
• Analyze codebases and generate documentation
• Define and run your own custom transformations using natural language, docs,

and code samples

Run locally on a few repos for fast iteration, or at scale on hundreds of repos (up to 128 in-parallel). Note: this skill collects telemetry. To opt out, see https://docs.aws.amazon.com/transform/latest/userguide/transform-usage-telemetry.html

What would you like to transform today?"

Do NOT inspect any files, run any commands, or check prerequisites until the user responds.

Usage

Use when the user wants to:

• Transform, upgrade, or migrate code (Java, Python, Node.js, etc.)
• Migrate AWS SDKs (Java SDK v1→v2, boto2→boto3, JS SDK v2→v3, etc.)
• Run bulk code transformations at scale via AWS Batch/Fargate
• Analyze which ATX transformations apply to their repositories
• Perform comprehensive codebase analysis
• Create a new custom Transformation Definition (TD)

Core Concepts

• Transformation Definition (TD): A reusable transformation recipe discovered via atx custom def list --json
• Match Report: Auto-generated mapping of repos to applicable TDs based on code inspection
• Local Mode: Runs ATX CLI on the user's machine (1-9 repos, max 3 concurrent)
• Remote Mode: Runs transformations in AWS Batch/Fargate (10+ repos, or by preference)

Philosophy

Wait for the user. On activation, present what this skill can do and ask the user what they'd like to accomplish. Do NOT automatically inspect the working directory, open files, or any repository until the user explicitly provides repos to work with.

Once the user provides repositories, match — don't ask. Inspect those repositories and present which transformations apply automatically. Never show a raw TD list and ask the user to pick.

Prerequisites

Prerequisite checks run ONCE at the start of a session. Do not repeat per repo. Do NOT run prerequisite checks until the user has stated what they want to do.

0. Platform Check (Required — All Modes)

Detect the user's operating system. If on Windows (not WSL), stop immediately and inform the user:

AWS Transform custom does not support native Windows. You need to install Windows Subsystem for Linux (WSL) and run this from within WSL. Install WSL: wsl --install in PowerShell (as Administrator), then restart. After that, open a WSL terminal and re-run this skill from there.

Check by running:

uname -s

• Linux or Darwin → proceed normally
• MINGW*, MSYS*, CYGWIN*, or any Windows-like output → block and show the WSL message above
• Command fails, errors, or is not found → treat as native Windows, block and show the WSL message above

Do NOT proceed with any other steps on native Windows.

1. AWS CLI (Required — All Modes)

aws --version

If not installed, guide the user:

• macOS: brew install awscli or curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" && sudo installer -pkg AWSCLIV2.pkg -target /
• Linux: curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && unzip awscliv2.zip && sudo ./aws/install

Do NOT proceed until aws --version succeeds.

2. AWS Credentials (Required — All Modes)

aws sts get-caller-identity

If credentials are NOT configured, walk the user through setup:

AWS Transform custom requires AWS credentials to authenticate with the service. Configure authentication using one of the following methods.

1. AWS CLI Configure (~/.aws/credentials):
   aws configure

2. AWS Credentials File (manual). Configure credentials in ~/.aws/credentials:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

3. Environment Variables. Set the following environment variables:

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token

You can also specify a profile using the AWS_PROFILE environment variable:

export AWS_PROFILE=your_profile_name

Do NOT proceed until credentials are verified. Re-run aws sts get-caller-identity after setup.

Note: environment variables set via export do not carry over between shell sessions. If the agent spawns a new shell, credentials set as env vars may be lost. Prefer aws configure or ~/.aws/credentials for persistence.

3. ATX CLI (Required — All Modes)

Required in all modes for TD discovery (atx custom def list --json). Local mode also uses it for transformation execution.

atx --version
# Install: curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash

Mandatory: always run `atx update` once at the start of every session, even if you just ran it recently. This catches new ATX CLI versions and new TDs. Run it before any other ATX command (including atx custom def list --json):

atx update

Do NOT skip this step. Do NOT ask the user whether to update. Do NOT condition it on whether the CLI "needs" an update. Run it unconditionally.

4. IAM Permissions (Required — All Modes)

Local mode requires transform-custom:* minimum. Verify by running a TD list:

atx custom def list --json

If this succeeds, permissions are sufficient — skip the rest of this section.

If it fails with a permissions error, the caller needs the transform-custom:* IAM permission. Explain to the user what's needed and get confirmation before proceeding:

Your identity needs the transform-custom:* permission to use the ATX CLI. I can attach the AWS-managed policy AWSTransformCustomFullAccess to your identity. Shall I proceed?

Only after the user confirms, attach the managed policy:

CALLER_ARN=$(aws sts get-caller-identity --query Arn --output text)
if echo "$CALLER_ARN" | grep -q ":user/"; then
  IDENTITY_NAME=$(echo "$CALLER_ARN" | awk -F'/' '{print $NF}')
  aws iam attach-user-policy --user-name "$IDENTITY_NAME" \
    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
elif echo "$CALLER_ARN" | grep -Eq ":assumed-role/|:role/"; then
  ROLE_NAME=$(echo "$CALLER_ARN" | sed 's/.*:\(assumed-\)\{0,1\}role\///' | cut -d'/' -f1)
  aws iam attach-role-policy --role-name "$ROLE_NAME" \
    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
fi