/agent-advisor

name: agent-advisor
description: "Entry point for AI-agent work on AWS: pick a runtime, plan a migration for existing workloads, and build an executable POC — one phased flow. Triggers on: which runtime for my agent, AgentCore vs ECS vs EKS vs Lambda, AgentCore vs Lambda MicroVMs, deploy an AI agent on AWS, agent architecture on AWS, I have an agent idea what do I build, move/migrate my agents to AWS, agent migration plan, add AgentCore services (memory, gateway, identity, policy, observability) to an agent already on AWS, Temporal on AWS (migrate/run Temporal workers on AWS, a service orchestrated by Temporal, Temporal Cloud vs self-hosted). Temporal Workflow code is never rewritten into Step Functions. Requires at least one agentic component — a purely non-agent system (plain services, batch jobs, HTTP endpoints, non-agent Temporal Activities) is out of scope, redirected to gcp-to-aws / heroku-to-aws / llm-to-bedrock. Not for: compute/data migration with no AI agent; pure LLM SDK rewrite (use llm-to-bedrock); per-model pricing."

AWS Agent Advisor

Helps startups decide how and where to run AI agents on AWS. Deterministic scoring recommends a runtime; the conversation adapts to the user's technical background.

Definitions

• **"Load"** = Read the file with the Read tool and follow it. Do not summarize or skip.
• **`$RUN_DIR`** = the run directory under `.agent-advisor/` (e.g. `.agent-advisor/0630-1430/`),

created in Intake.

• **`$PLUGIN`** = `${CLAUDE_PLUGIN_ROOT}` (the installed plugin root). On Claude Code this token

substitutes inline. **If `${CLAUDE_PLUGIN_ROOT}` does not resolve** (some Cursor/Codex builds, or a literal `${CLAUDE_PLUGIN_ROOT}` string showing up in a path error), fall back to the skill's own directory: this SKILL.md lives at `<plugin>/skills/agent-advisor/SKILL.md`, so the engine and its data are all inside this skill — scripts at `./scripts/...`, runtime profiles at `./references/runtimes/...`, and decision refs at `./references/decision-refs/...` relative to it. Prefer `${CLAUDE_PLUGIN_ROOT}/skills/agent-advisor/...`; use the relative fallback only when it fails to resolve.

Prerequisites

• `uv` available (for scoring). Check: `uv --version`. If missing, tell the user to install

it from the official install guide (https://docs.astral.sh/uv/getting-started/installation/ — e.g. `brew install uv` or `pipx install uv`) and stop.

Phase Structure (frontmatter)

Phase, fragment, and assembler files carry a YAML frontmatter block that declares how each phase is composed — its inputs, triggers, fragments, assembler, artifacts, gates, and ordering. The execution contract is the vendored `references/vendored/dsl/INTERPRETER.md`: it defines every frontmatter key, the fragment/assembler model, the gate protocol (`HANDOFF_OK` / `GATE_FAIL`), and the interpreter loop. **Load it first** (once, at the start of a run), then execute each phase file's prose body. Elsewhere in this skill, `INTERPRETER.md` (without a path) refers to this loaded contract.

Execution

This skill is driven by the interpreter loop in `INTERPRETER.md` (§ The interpreter loop): it reads `.phase-status.json`, determines the current phase, runs each phase's `_preconditions` / fragments / `_assemble` / `_postconditions`, advances on `HANDOFF_OK` via `_advances_to`, and validates state. The backbone (intake → discover → clarify → confirm → design → estimate → generate → migration-plan → poc → complete) and the one sidebar branch (add-capabilities) are derived from the phase files' frontmatter — they are not restated here.

**Cold start (entry phase).** With no run under `.agent-advisor/` carrying a `.phase-status.json`, begin at `references/phases/intake/intake.md` — this skill's entry phase (the one carrying `_init: true`). On a warm start, `current_phase` in `.phase-status.json` is authoritative (`INTERPRETER.md` § The interpreter loop).

**Skill bindings (`INTERPRETER.md` § Skill bindings).** This skill declares:

• **Run root**: `.agent-advisor/` — `$RUN_DIR` is this skill's name for the run directory

(`.agent-advisor/[MMDD-HHMM]/`). Intake's own prose performs the `_init` bootstrap.

• **State shape**: § State file below (advisor-specific keys such as `entry_point`,

`audience`, `recommendation_reviewed`, `migration_plan_ctx`, `migration_plan_unavailable`); the shared state schema is not vendored.

• **Run seed (optional)**: `$RUN_DIR/seed.json`, else `.agent-advisor/seed.json` at the run root

(schema `scripts/schemas/seed.json`) supplies machine-readable answers for a non-interactive run — the Clarify dimensions, the two gate answers, the POC mode, the live-probe answer, and a `co_recommend` tie-break. It is the HIGHEST-precedence source for every value it carries (clarify.md Step 2.5), which is what makes a repeated run's score comparable: the deterministic engine gets byte-identical input. A gate the seed omits is declined; a dimension the seed omits falls through to detection, then prose, then an `assumed` value that MUST be recorded in `$RUN_DIR/UNANSWERED.md`. With no seed, the interactive flow is unchanged.

• **Resolved statuses**: `skipped` (routing resolved the phase without running it), plus

`not_applicable` for `migration_plan` only.

• **Conditional backbone routing**: the entry-point routing below. When a routing rule

marks a phase not-applicable, set it `skipped` and advance through its `_advances_to` in the same state write.

Routing & gates (orchestration)

Sidebar placement and conditional backbone routing are orchestration prose owned by this file (`INTERPRETER.md` § Skill bindings, § Backbone vs sidebar).

**Entry-point routing:**

• `build_scratch` → skip Discover; Clarify → Confirm → Design → Estimate → Generate → **Gate 2 → POC (any winning runtime)**. No migration plan (nothing existing to migrate).
• `build_deploy` → Discover (if code) → Clarify → Confirm → Design → Estimate → Generate → **Gate 1 → Migration Plan