GCP-to-AWS Migration Skill

Philosophy

• Re-platform by default: Select AWS services that match GCP workload types (e.g., Cloud Run → Fargate, Cloud SQL → RDS).

• Dev sizing unless specified: Default to development-tier capacity (e.g., db.t4g.micro, single AZ). Upgrade only on user direction.

• Infrastructure-first approach: v1.0 migrates Terraform-defined infrastructure only. App code scanning and billing import are v1.1+.

Prerequisites

User must provide GCP infrastructure-as-code:

• One or more .tf files (Terraform)

• Optional: .tfvars or .tfstate files

If no Terraform files are found, stop immediately and ask user to provide them.

State Management

Migration state lives in .migration/[MMDD-HHMM]/ directory (created by Phase 1, persists across invocations):

.migration/ ├── .gitignore # Auto-created to protect state files from git └── 0226-1430/ # MMDD-HHMM timestamp ├── .phase-status.json # Current phase tracking ├── gcp-resource-inventory.json # All GCP resources found ├── gcp-resource-clusters.json # Clustered resources by affinity ├── clarified.json # User answers (Phase 2 output) ├── aws-design.json # AWS services mapping (Phase 3 output) ├── estimation.json # Cost breakdown (Phase 4 output) └── execution.json # Timeline + risks (Phase 5 output)

Note: The .migration/ directory is automatically protected by a .gitignore file created in Phase 1. Migration state files will not be accidentally committed to version control.

.phase-status.json schema:

{ "phase": "discover|clarify|design|estimate|execute", "status": "in-progress|completed", "timestamp": "2026-02-26T14:30:00Z", "version": "1.0.0" }

If .phase-status.json exists:

• If status is completed : advance to next phase (discover→clarify, clarify→design, etc.)

• If status is in-progress : resume from that phase

Phase Routing

On skill invocation: Check for .migration/*/ directory

• If none exist: Initialize Phase 1 (Discover), set status to in-progress

• If multiple exist: STOP. Output: "Multiple migration sessions detected in .migration/ :" then for each directory, display its name and the contents of its .phase-status.json (phase + status). Output: "Pick one to continue: [list with phase info]"

• If exists: Load .phase-status.json and validate:

• If empty file (0 bytes): STOP. Output: "State file is empty. Delete .migration/[MMDD-HHMM]/.phase-status.json and restart."

• If invalid JSON: STOP. Output: "State file corrupted (invalid JSON). Delete .migration/[MMDD-HHMM]/.phase-status.json and restart Phase [X]."

• If missing required fields (phase , status , timestamp , version ): STOP. Output: "State file incomplete (missing [field]). Delete and restart."

• If version != "1.0.0": STOP. Output: "Incompatible state file version: [version]. This skill requires version 1.0.0."

• If unrecognized phase value: STOP. Output: "Unrecognized phase: [value]. Valid values: discover, clarify, design, estimate, execute."

• If status not in {in-progress, completed}: STOP. Output: "Unrecognized status: [value]. Valid values: in-progress, completed."

• If valid: Determine next action:

• If phase status is in-progress : Resume that phase

• If phase status is completed : Advance to next phase

Phase transition mapping (when phase is completed ):

• discover (completed) → Route to clarify

• clarify (completed) → Route to design

• design (completed) → Route to estimate

• estimate (completed) → Route to execute

• execute (completed) → Migration complete; offer summary and cleanup options

Phase gate checks: If prior phase incomplete, do not advance (e.g., cannot enter estimate without completed design)

Phase Summary Table

Phase Inputs Outputs Reference

Discover .tf files gcp-resource-inventory.json , gcp-resource-clusters.json , .phase-status.json updated references/phases/discover/discover.md

Clarify gcp-resource-inventory.json , gcp-resource-clusters.json

clarified.json , .phase-status.json updated references/phases/clarify.md

Design gcp-resource-inventory.json , gcp-resource-clusters.json , clarified.json

aws-design.json , aws-design-report.md , .phase-status.json updated references/phases/design.md

Estimate aws-design.json , clarified.json

estimation.json , estimation-report.md , .phase-status.json updated references/phases/estimate.md

Execute aws-design.json , estimation.json

execution.json , execution-timeline.md , .phase-status.json updated references/phases/execute.md

MCP Servers

awspricing (for cost estimation):

• Call get_pricing_service_codes() to detect availability

• If success: use live AWS pricing

• If timeout/error: fall back to references/shared/pricing-fallback.json (includes 2026 on-demand rates for major services)

awsknowledge (for design validation):

• Use for regional availability checks (e.g., service available in target region?)

• Use for feature parity checks (e.g., do required features exist in AWS service?)

• Use for service constraints and best practices

• Fallback: if unavailable, set validation_status: "skipped" in aws-design.json with note in design report

• Important: Validation is informational; design proceeds either way (not blocking)

Error Handling

Condition Action

No .tf files found Stop. Output: "No Terraform files detected. Please provide .tf files with your GCP resources and try again."

.phase-status.json missing phase gate Stop. Output: "Cannot enter Phase X: Phase Y-1 not completed. Start from Phase Y or resume Phase Y-1."

awspricing unavailable after 3 attempts Display user warning about ±15-25% accuracy. Use pricing-fallback.json . Add pricing_source: fallback to estimation.json.

User does not answer all Q1-8 Offer Mode C (defaults) or Mode D (free text). Phase 2 completes either way.

aws-design.json missing required clusters Stop Phase 4. Output: "Re-run Phase 3 to generate missing cluster designs."

Defaults

• IaC output: None (v1.0 produces design, cost estimates, and execution plans — no IaC code generation)

• Region: us-east-1 (unless user specifies, or GCP region → AWS region mapping suggests otherwise)

• Sizing: Development tier (e.g., Aurora Serverless v2 0.5 ACU for databases, 0.5 CPU for Fargate)

• Migration mode: Full infrastructure path (no AI-only subset path in v1.0)

• Cost currency: USD

• Timeline assumption: 8-12 weeks total

Workflow Execution

When invoked, the agent MUST follow this exact sequence:

Load phase status: Read .phase-status.json from .migration/*/ .

• If missing: Initialize for Phase 1 (Discover)

• If exists: Determine current phase based on phase field and status value

Determine phase to execute:

• If status is in-progress : Resume that phase (read corresponding reference file)

• If status is completed : Advance to next phase (read next reference file)

• Phase mapping for advancement:

• discover (completed) → Execute clarify (read references/phases/clarify.md )

• clarify (completed) → Execute design (read references/phases/design.md )

• design (completed) → Execute estimate (read references/phases/estimate.md )

• estimate (completed) → Execute execute (read references/phases/execute.md )

• execute (completed) → Migration complete

Read phase reference: Load the full reference file for the target phase.

Execute ALL steps in order: Follow every numbered step in the reference file. Do not skip, optimize, or deviate.

Validate outputs: Confirm all required output files exist with correct schema before proceeding.

Update phase status: Each phase reference file specifies the final .phase-status.json update (records the phase that just completed).

Display summary: Show user what was accomplished, highlight next phase, or confirm migration completion.

Critical constraint: Agent must strictly adhere to the reference file's workflow. If unable to complete a step, stop and report the exact step that failed.

User can invoke the skill again to resume from last completed phase.

Scope Notes

v1.0 includes:

• Terraform infrastructure discovery (no app code scanning)

• User requirement clarification (8 structured questions)

• Structured Design (cluster-based mapping from Terraform)

• AWS cost estimation (from pricing API or fallback)

• Execution timeline and risk assessment

Deferred to v1.1+:

• App code scanning (runtime detection of compute workload types)

• AI-only fast-track path in Clarify/Design

• Billing data import from GCP

• Flat Design path (for non-Terraform codebases)