agent-advisor

Files (87)

• SKILL.md
• agentcore.md · references/decision-refs/
• batch.md · references/decision-refs/
• cost-levers.md · references/decision-refs/
• ecs.md · references/decision-refs/
• eks.md · references/decision-refs/
• freshness.md · references/decision-refs/
• lambda-microvms.md · references/decision-refs/
• lambda.md · references/decision-refs/
• managed-alternatives.md · references/decision-refs/
• maturity-readiness.md · references/decision-refs/
• model-selection.md · references/decision-refs/
• poc-shapes.md · references/decision-refs/
• temporal.md · references/decision-refs/
• workload-classes.md · references/decision-refs/
• build-diagram.md · references/diagram/
• handoff-migration.md · references/handoff/
• anthropic-bedrock-2026-07-21.json · references/models/
• anthropic-bedrock-2026-09-24.json · references/models/
• openai-bedrock-2026-08-21.json · references/models/
• openai-bedrock-2026-09-24.json · references/models/
• recommendation-doc.md · references/output-templates/
• add-capabilities-assemble.md · references/phases/add-capabilities/
• add-capabilities.md · references/phases/add-capabilities/
• clarify-assemble.md · references/phases/clarify/
• clarify-business.md · references/phases/clarify/
• clarify-technical.md · references/phases/clarify/
• clarify.md · references/phases/clarify/
• confirm-assemble.md · references/phases/confirm/
• confirm.md · references/phases/confirm/
• design-assemble.md · references/phases/design/
• design.md · references/phases/design/
• discover-assemble.md · references/phases/discover/
• discover.md · references/phases/discover/
• estimate-assemble.md · references/phases/estimate/
• estimate.md · references/phases/estimate/
• generate-assemble.md · references/phases/generate/
• generate-report.md · references/phases/generate/
• generate.md · references/phases/generate/
• intake-assemble.md · references/phases/intake/
• intake.md · references/phases/intake/
• migration-plan-assemble.md · references/phases/migration-plan/
• migration-plan-gcp-constraints.md · references/phases/migration-plan/
• migration-plan.md · references/phases/migration-plan/
• model-recommend-assemble.md · references/phases/model-recommend/
• model-recommend.md · references/phases/model-recommend/
• poc-assemble.md · references/phases/poc/
• poc-report.md · references/phases/poc/
• poc.md · references/phases/poc/
• report-help-banner.md · references/
• report-shell.md · references/
• agentcore.json · references/runtimes/
• ecs.json · references/runtimes/
• eks.json · references/runtimes/
• lambda.json · references/runtimes/
• lambda_microvms.json · references/runtimes/
• README.md · references/vendored/
• bedrock-pricing-cache.md · references/vendored/ai/
• INTERPRETER.md · references/vendored/dsl/
• anthropic_model_recommendation.py · scripts/
• …and 27 more

SKILL.md (first lines)

# 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 (if existing non-AWS AI workload detected and user confirms)** → **Gate 2 → POC (any winning runtime)**.
- `migrate` → Discover (if code) → Clarify → Confirm → Design → Estimate (target-state run cost; migration TCO comparison stays with the Migration Plan engine) → Generate → **Gate 1 → Migration Plan (in-skill, reusing the sibling `gcp-to-aws` skill)** → **Gate 2 → POC (any winning runtime, when the plan was produced)**. Declining Gate 1 keeps the classic handoff: pointer to `/aws-startup-advisor:llm-to-bedrock` with `handoff-summary.md`.
- `add_capabilities` → load `references/phases/add-capabilities/add-capabilities.md` and follow it (no runtime
  scoring; writes `capabilities-recommendation.md`). This is a self-contained branch — it does
  NOT pass through Clarify / Confirm / Design / Estimate / Generate, so the phase gate
  below never applies to it.
- Temporal detection routes into `migrate` with temporal units pre-seeded (see discover).

**Gate semantics (backbone tail):**

- **Gate 1 → `migration_plan`** runs only when `generate` is done AND
  `recommendation_reviewed == true` (generate.md Step 5.5) AND entry point ∈ {migrate,
  build_deploy} AND the run is migration-eligible (generate.md Step 6) AND the user
  confirmed Gate 1. Otherwise resolve it: `not_applicable` (build_scratch / no migratable
  workload) or `skipped` (declined) — and advance.
- **Gate 2 → `poc`** runs only when `phases.poc == "in_progress"` (set when the user
  answers Gate 2 "yes" — asked in generate.md Step 7 or migration-plan.md Step 6) AND
  `recommendation_reviewed == true`. Any winning runtime (agentcore / ecs / eks / lambda /
  lambda_microvms) — the POC shape follows the verdict (poc.md Step 3 dispatch on
  `references/decision-refs/poc-shapes.md`). Gate 2 is only offered when `migration_plan`
  ∈ {completed, skipped, not_applicable} — or `in_progress` on build_deploy only (Stage 2
  failed/aborted; fallback POC from design.json per migration-plan.md failure handling);
  for entry point `migrate`, only when `migration_plan == "completed"` (the POC implements the
  plan) OR when the stage resolved `not_applicable` with `migration_plan_unavailable ==
  "engine_absent"` — a standalone deployment that does not bundle the migration engine, where
  Gate 2 is offered by migration-plan.md Step -1 and the POC is design-backed. A migrate-POC
  with no plan for any OTHER reason (the user declined) has nothing to implement.
- Persisting Gate 2 as `phases.poc = "in_progress"` BEFORE poc.md loads makes the
  confirmation resumable: if the session breaks between the "yes" and the load, the
  interpreter re-enters `poc` without re-asking. (A declared deviation from
  `INTERPRETER.md` § The interpreter loop step 5's gate-then-`in_progress` ordering — the
  user's confirmation is the entry event worth persisting.)

**Phase gate:** Do NOT load design.md / estimate.md / generate.md unless
`$RUN_DIR/.phase-status.json` exists and BOTH `phases.clarify == "completed"` AND
`phases.confirm == "completed"`. Confirm confirms the deployment model, the service
set, and (for a co_recommend tie) the user's `chosen_runtime` — Design and the diagram depend on
its `confirm.json` output, so it must not be skipped. If the user asks to skip Clarify or Pass 2,
refuse briefly and run it.

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws