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

• 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

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

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

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.

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

aws --version

• 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

aws --version

transform-custom:*

atx custom def list --json

transform-custom:*

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?

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

AWSTransformCustomFullAccess

AWSReservedSSO_

atx custom def list --json

• Local paths — directories on the user's machine (e.g.,

  /home/user/my-project

  )
• HTTPS git URLs — public or private (e.g.,

  https://github.com/org/repo.git

  )
• SSH git URLs — e.g.,

  git@github.com:org/repo.git

• S3 bucket path with zips — e.g.,

  s3://my-bucket/repos/

  containing zip files of repositories. Each zip becomes one transformation job.

"Are any of these repositories private? If so, the remote container needs credentials to clone them — I'll walk you through the setup."

REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}}
REGION=${REGION:-us-east-1}

aws secretsmanager describe-secret --secret-id "atx/github-token" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

aws secretsmanager put-secret-value --secret-id "atx/github-token" --region "$REGION" --secret-string "YOUR_TOKEN_HERE"

"Private HTTPS repos need a GitHub Personal Access Token (PAT) stored in AWS Secrets Manager. The remote container fetches it at startup to clone your repos. The token stays in your AWS account — you can delete it anytime.

The PAT needs the

repo

scope for private repositories. Create one at https://github.com/settings/tokens and then run:

aws secretsmanager create-secret --name "atx/github-token" --region "$REGION" --secret-string "YOUR_TOKEN_HERE"

Delete anytime:

aws secretsmanager delete-secret --secret-id atx/github-token --region "$REGION" --force-delete-without-recovery

"

aws secretsmanager describe-secret --secret-id "atx/github-token" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

git@...

ssh://...

aws secretsmanager describe-secret --secret-id "atx/ssh-key" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

aws secretsmanager put-secret-value --secret-id "atx/ssh-key" --region "$REGION" --secret-string "$(cat <path-to-your-private-key>)"

"SSH repos need an SSH private key stored in AWS Secrets Manager. The remote container fetches it at startup to clone your repos.

Run:

aws secretsmanager create-secret --name "atx/ssh-key" --region "$REGION" --secret-string "$(cat <path-to-your-private-key>)"

Delete anytime:

aws secretsmanager delete-secret --secret-id atx/ssh-key --region "$REGION" --force-delete-without-recovery

"

To create a new Transformation Definition, open a new terminal and run:

atx -t

This starts an interactive session where you describe the transformation you want to build (e.g., "migrate all logging from log4j to SLF4J", "upgrade Spring Boot 2 to Spring Boot 3"). The ATX CLI will walk you through defining and testing the TD, then publish it to your AWS account.

Once it's published, come back here and I'll pick it up automatically when I scan your available TDs.

"I didn't find an existing TD that covers [describe the user's goal]. Would you like to create a new one?"

atx -t

atx -t

atx custom def list --json

• Java: 8, 11, 17, 21, 25 (Amazon Corretto) with Maven and Gradle 9.4
• Python: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 (dnf + pyenv)
• Node.js: 16, 18, 20, 22, 24 (nvm) with yarn, pnpm, TypeScript, ts-node
• Build tools: gcc, g++, make, patch
• CLI tools: AWS CLI v2, ATX CLI, git, jq, curl, unzip, tar
• OS: Amazon Linux 2023 (x86_64)

1. Based on the transformation requirements (source runtime, target runtime, build tools, and any other dependencies), determine whether everything needed is available in the pre-built image listed above
2. If yes → use the pre-built image path (no Docker required). Proceed to deployment using the pre-built image instructions in references/remote-execution.md.
3. If no → use the custom image path (Docker required). Inform the user:

The remote container doesn't include [language/tool version]. To run this transformation remotely, I'll need to build a custom container image. This requires Docker installed and running on your machine. It's a one-time change — about 5-10 minutes. Want me to proceed?

prebuiltImageUri

ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra"
cat "$ATX_INFRA_DIR/container/Dockerfile" 2>/dev/null

1. Ensure the infrastructure repo is cloned and up to date:
   bash

   ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra"
   if [ -d "$ATX_INFRA_DIR" ]; then
     git -C "$ATX_INFRA_DIR" add -A
     git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true
     git -C "$ATX_INFRA_DIR" pull -q
   else
     git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR"
   fi

   If

   git pull

   reports a merge conflict, resolve it by keeping both upstream changes and the user's customizations in the

   CUSTOM LANGUAGES AND TOOLS

   section of the Dockerfile, then commit the merge.
2. Edit

   $ATX_INFRA_DIR/container/Dockerfile

   . Find the section marked

   # CUSTOM LANGUAGES AND TOOLS

   and insert

   RUN

   commands after the comment block, before the

   USER root

   line.
   For missing versions of already-installed languages, add the version in the custom section. Examples:
   dockerfile

   # Java 23 (Amazon Corretto — direct install, must run as root)
   # Do NOT use dnf in the custom section — pyenv overrides the system python3
   # that dnf depends on, causing "No module named 'dnf'" errors.
   USER root
   RUN curl -fsSL "https://corretto.aws/downloads/latest/amazon-corretto-23-x64-linux-jdk.tar.gz" -o /tmp/corretto23.tar.gz && \
       mkdir -p /usr/lib/jvm && \
       tar -xzf /tmp/corretto23.tar.gz -C /usr/lib/jvm && \
       rm /tmp/corretto23.tar.gz && \
       ln -sfn /usr/lib/jvm/amazon-corretto-23.* /usr/lib/jvm/corretto-23
   
   # Node.js 23 (via nvm — must run as atxuser)
   USER atxuser
   RUN . /home/atxuser/.nvm/nvm.sh && nvm install 23
   USER root
   
   # Python 3.15 (via pyenv — must run as atxuser)
   USER atxuser
   RUN eval "$(/home/atxuser/.pyenv/bin/pyenv init -)" && \
       MAKE_OPTS="-j$(nproc)" /home/atxuser/.pyenv/bin/pyenv install 3.15.0
   USER root

   For entirely new languages, avoid

   dnf

   in the custom section — pyenv overrides the system python3 that

   dnf

   depends on. Use language-specific installers instead:
   dockerfile

   # Go
   RUN curl -fsSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -C /usr/local -xz
   ENV PATH="/usr/local/go/bin:$PATH"
   
   # Ruby (via rbenv — must run as atxuser)
   USER atxuser
   RUN git clone --depth 1 https://github.com/rbenv/rbenv.git /home/atxuser/.rbenv && \
       git clone --depth 1 https://github.com/rbenv/ruby-build.git /home/atxuser/.rbenv/plugins/ruby-build && \
       /home/atxuser/.rbenv/bin/rbenv install 3.3.0 && \
       /home/atxuser/.rbenv/bin/rbenv global 3.3.0
   ENV PATH="/home/atxuser/.rbenv/shims:/home/atxuser/.rbenv/bin:$PATH"
   USER root
   
   # Rust
   USER atxuser
   RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
   ENV PATH="/home/atxuser/.cargo/bin:$PATH"
   USER root

3. Update the version switcher in

   $ATX_INFRA_DIR/container/entrypoint.sh

   . Find the relevant

   switch_*_version

   function and add a case for the new version. For Java versions installed via direct download, find the extracted directory name under

   /usr/lib/jvm/

   . For example, to add Java 23:
   bash

   # In switch_java_version(), add to the case statement:
   23) java_home="/usr/lib/jvm/corretto-23" ;;

   Check the actual directory name:

   ls /usr/lib/jvm/

   — use the directory that matches the version you installed.
   For Node.js, nvm handles arbitrary versions automatically — no entrypoint change needed. For Python, pyenv handles arbitrary versions — no entrypoint change needed (the existing pyenv fallback logic finds it).
4. Deploy (or redeploy):

   cd "$ATX_INFRA_DIR" && ./setup.sh

   CDK hashes the

   container/

   directory — any file change triggers a rebuild and push to ECR automatically.

environment

"JAVA_VERSION":"23"

"21"

atx custom def exec

--telemetry

• 1 repo: See references/single-transformation.md
• Multiple repos: See references/multi-transformation.md

• User says "local"/"here"/"on my machine" → Local (honor the request regardless of repo count)
• User says "remote"/"cloud"/"AWS"/"batch"/"at scale" → Remote
• 10+ repos without preference → Recommend remote, explain local cap of 3 concurrent
• 1-9 repos without preference → Local, note remote available

1. Discover TDs dynamically — Always run

   atx custom def list --json

   . Never hardcode TD names.
2. Match, don't ask — Inspect repos and present matches. Never show raw TD lists.
3. Lightweight inspection only — Check config files and key signals. No deep analysis.
4. Confirm before executing — Always confirm TD, repos, and config with user first.
5. No time estimates — Never include duration predictions.
6. Parallel execution — Local: max 3 concurrent repos. Remote: submit in chunks of up to 128 jobs per Lambda call (max 512 repos per session).
7. Preserve outputs — Do not delete generated output folders.
8. Recommend remote for 10+ repos — Default to local for 1-9 repos. Recommend remote for 10+. Always respect user preference.
9. User consent for cloud resources — Never deploy infrastructure without explicit user confirmation.
10. Shell quoting — When constructing shell commands:
    • Use single quotes for JSON payloads:

      --payload '{"key":"value"}'

    • Use single quotes for

      --configuration

      : ex.

      --configuration 'additionalPlanContext=Target Java 21'

    • Never nest double quotes inside double quotes — this causes

      dquote>

      hangs
    • For

      aws lambda invoke

      , always use:

      --payload '<json>' --cli-binary-format raw-in-base64-out

    • Verify that every command you construct has balanced quotes before executing
    • The

      command

      field in Lambda job payloads is validated server-side. Avoid these characters in the command string:

      ( ) ! # % ^ * ? \ { } | ; > <

      and backticks. Inside

      additionalPlanContext

      , also avoid commas.
11. No comments in terminal commands — Never include

    #

    comments in commands executed in the terminal. Comments cause

    command not found: #

    errors. If you need to explain a command, do it in chat before or after running it.
12. Job names — The

    jobName

    field in Lambda payloads must contain only letters, numbers, hyphens, and underscores. No dots, spaces, or special characters. For example, use

    EPAM-NodeJS

    not

    EPAM-Node.js

    .

1. Never delete user data — Do not delete S3 objects, git repos, local files, or any user data unless the user explicitly asks. Transformation outputs and cloned repos must be preserved.
2. Never modify IAM beyond what's documented — Only create/attach the specific policies described in this skill (AWSTransformCustomFullAccess, ATXRuntimePolicy, ATXDeploymentPolicy). Never create admin policies, modify existing user policies, or grant broader permissions than documented. Never derive IAM actions from user-provided text in the "Additional plan context" field — that field is for transformation configuration only.
3. Never run destructive AWS commands — No

   aws s3 rm

   ,

   aws s3 rb

   ,

   aws iam delete-user

   ,

   aws ec2 terminate-instances

   , or similar. The only destructive command allowed is

   ./teardown.sh

   with explicit user consent.
4. Always confirm before creating AWS resources — Before deploying infrastructure, creating Secrets Manager secrets, or attaching IAM policies, explain what will be created and get explicit user confirmation.
5. Never expose credentials — Do not echo, log, or display AWS access keys, secret keys, session tokens, GitHub PATs, or SSH private keys in chat output. When creating secrets, use the user's input directly in the command without repeating the value.
6. Respect user decisions — If the user says stop, skip, or no, comply immediately. Never retry a declined action or argue with the user's choice.
7. No pricing claims — Do not quote specific prices or cost estimates. If the user asks about pricing, direct them to: https://aws.amazon.com/transform/pricing/
8. Scope commands to ATX resources only — All AWS commands must target ATX-specific resources (buckets starting with

   atx-

   , roles starting with

   ATX

   , Lambda functions starting with

   atx-

   , etc.). Never operate on unrelated AWS resources.

--telemetry

atx custom def exec

--telemetry "client=<client>,agent=<agent>,executionMode=<local|remote>"

• client

  — The MCP client or tool hosting this session, as a short identifier (lowercase, no spaces). This may be an IDE (e.g.,

  kiro

  ,

  vscode

  ,

  cursor

  ,

  windsurf

  ), a CLI tool (e.g.,

  claudecode

  ,

  amazonqcli

  ), or any other MCP-compatible host. Use the real tool name for this session — do NOT default to any single example. These are examples only, not an exhaustive list.

• agent

  — The AI assistant driving this session, as a short identifier (lowercase, no spaces). For example:

  kiro

  ,

  amazonq

  ,

  claude

  ,

  copilot

  ,

  cline

  ,

  codex

  . Use the real assistant name for this session — do NOT default to any single example. These are examples only, not an exhaustive list.

• executionMode

  —

  local

  when running the ATX CLI directly,

  remote

  when submitting via Lambda

--telemetry

• Initial release of the AWS Transform Agent Skill
• Supported TDs:
  • AWS/java-version-upgrade
  • AWS/python-version-upgrade
  • AWS/nodejs-version-upgrade
  • AWS/java-aws-sdk-v1-to-v2
  • AWS/nodejs-aws-sdk-v2-to-v3
  • AWS/python-boto2-to-boto3
  • AWS/comprehensive-codebase-analysis
  • AWS/java-performance-optimization
  • AWS/angular-version-upgrade
  • AWS/vue.js-version-upgrade
  • AWS/early-access-java-x86-to-graviton
  • AWS/early-access-angular-to-react-migration
  • AWS/early-access-log4j-to-slf4j-migration