aws-transform

What this skill does

# 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:

```bash
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)

```bash
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)

```bash
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.

```bash
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`):

```bash
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:

```bash
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:

```bash
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
```