AutoGineer
Generated banner for AWS Well Architected Review
Generated logo for AWS Well Architected Review

AWS Well Architected Review

AWSOfficialPublished by AWS

  • Skill
  • Review and audit
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Performs a full AWS Well-Architected Framework review evaluating every framework question across all pillars discovered from the live AWS documentation by analyzing code, IaC, and configurations to produce evidence-backed findings with Eisenhower-prioritized remediation. Supports full reviews (every framework best practice with BP ID citations), quick reviews (question-level), pillar-scoped reviews, score-mode reviews (a maturity scorecard with per-pillar scores and filtered findings), and lens-specific reviews using lenses discovered from the live AWS documentation. Triggers on mentions of Well-Architected review, WA review, WAR, pillar assessment, architecture review across pillars, workload assessment, cloud readiness evaluation, or a Well-Architected score, grade, or scorecard request. Does not apply to single-pillar deep-dives, learning WA concepts, ADRs, or migration readiness assessments.
— the description by AWS

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill conducts a systematic AWS Well-Architected Framework (WA Framework) review by discovering workload architecture from code and IaC, acquiring a live corpus of framework best practices, and evaluating them against the workload. It produces a risk-ranked, Eisenhower-prioritized report, ensuring comprehensive coverage across all pillars. The process is gated to ensure accuracy, using a frozen manifest of questions and best practices to maintain consistency throughout the assessment.

What it does

  • Discovers infrastructure and application architecture from code, IaC, and deployment configurations.
  • Fetches and validates the current AWS Well-Architected Framework corpus from live documentation.
  • Evaluates every framework best practice against the workload with specific evidence citations.
  • Generates a risk-classified report including a pillar scorecard and remediation plan.
  • Supports multiple review modes including full, quick, pillar-scoped, and lens-specific assessments.
  • Provides Eisenhower-prioritized remediation steps for identified risks.

When to use it

  • When you need a formal, evidence-based assessment of your AWS workload's alignment with the Well-Architected Framework.
  • When preparing for a cloud architecture review or seeking to improve the maturity of an existing deployment.
  • When you require a prioritized list of remediation tasks based on architectural risks.
  • When you need to evaluate specific AWS lenses or pillar-scoped assessments for your infrastructure.

Advantages

  • Evidence-backed findings linked directly to your codebase or architecture description.
  • Comprehensive coverage ensures no best practice is overlooked during the review.
  • Prioritized remediation plan helps focus efforts on the most critical architectural risks.
  • Uses live documentation to ensure the framework criteria are current and accurate.
  • Structured, repeatable process reduces subjectivity in architectural assessments.

Usage examples

“Perform a full AWS Well-Architected review for my current project in this repository.”
The agent will analyze the IaC and code, fetch the latest WA framework, evaluate all pillars, and output a comprehensive report with a scorecard and remediation plan.
“Can you run a pillar-scoped assessment on the Security pillar for my infrastructure?”
The agent will focus its discovery and evaluation exclusively on the Security pillar, providing a detailed breakdown of findings and risks for that specific area.
“I need a Well-Architected scorecard for my workload.”
The agent will perform a score-mode review, providing a maturity scorecard with per-pillar scores and a summary of findings.
“Perform a lens-specific review using the Serverless Lens.”
The agent will apply the Serverless Lens criteria to your workload and generate a standalone report focusing on serverless-specific best practices.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/aws/aws-well-architected-review/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip aws-well-architected-review.zip -d .agents/skills

Documentation by AWS

Well-Architected Review

Overview

Guides a systematic AWS Well-Architected Framework (WA Framework) review: discover the workload from code and IaC, acquire the live corpus inventory, evaluate every framework question and best practice against evidence, and deliver a risk-ranked, Eisenhower-prioritized report inline.

Framework content is fetched from the live AWS documentation at review time rather than embedded as a snapshot. The AWS MCP server's documentation reader (aws___read_documentation) is recommended for reliable retrieval; when it is unavailable, fetch the same docs.aws.amazon.com pages over HTTPS with the environment's web-fetch tool, and if no documentation access exists at all, proceed from internal knowledge and disclose that the framework inventory could not be verified live. Do not depend on any non-public or internal best-practice/WA-guidance MCP; those are unavailable in supported runtimes.

Detailed procedures live in reference files — read each one when its step says to:

  • Review modes — mode selection (full / quick / pillar-scoped / score), trigger phrases, score output format

  • Discovery procedure — infrastructure and application architecture discovery

  • Live corpus inventory — the gated ACQUIRE_CORPUS stage: deterministic read-only traversal of the framework, the corpus records, and the validation gate

  • Evaluation procedure — evaluating every BP against the frozen manifest, per-pillar passes, aggregation rules, coverage audit

  • Lens guidance — when and how to apply Well-Architected Lenses

  • Risk assessment — impact × likelihood matrix and cross-pillar trade-offs

  • Report template — the full report structure for the report step

  • Security considerations — secure handling of workload data, review tooling, findings, and persisted artifacts

Execution model

Before beginning any step, read and follow security considerations — secrets redaction, HTTPS-only retrieval, least privilege, and confidentiality handling must be loaded before you operate on workload code or review tooling.

A full review runs as a gated sequence. Each step has a transition gate; you MUST NOT advance to the next step, or skip a step, when its gate has not passed. The single user-visible deliverable is one complete inline report — scratch files (a run-local working directory) are execution state only, never the delivered artifact, and their paths MUST NOT appear in the report.

Non-interactive by default. When the user has explicitly requested a review and supplied sufficient scope, execute every step to completion without pausing for confirmation between steps. The discovery and risk-assessment checkpoints are internal validation gates, not user stops: validate them yourself and proceed. Pause for the user only when the user explicitly asked for interactive checkpoints, or when a required scope decision genuinely cannot be inferred (e.g. an ambiguous pillar-scoped request).

Non-negotiable invariants — ALL modes (full / quick / pillar-scoped / score):

  • Step 4 (ACQUIRE_CORPUS) is mode-independent: every mode acquires and validates the live corpus inventory before any assessment and reads its questions/BPs against that frozen manifest. Assessment MUST NOT begin against an incomplete or unvalidated manifest, and no mode may skip Step 4.

  • Canonical IDs only — never fabricate a PILLAR##-BP## ID. If corpus acquisition cannot produce an ID, that is a surfaced error, not a gap to invent around.

Non-negotiable invariants — full review only:

  • Every BP in the frozen manifest receives exactly one status from the five-value vocabulary.

  • All sections of the report template are present (it is the authoritative list — the numbered items in Step 7 are the recall-critical subset, NOT the complete set: the template also mandates the Executive Summary, Architecture Overview, Cross-Pillar Trade-offs, Next Steps, and others). The report is emitted inline, first line # Well-Architected Review:. No "see file", attachment, or scratch-path deferral.

Step 1: Define the workload scope

Establish the workload from what the user provided:

  • Workload name and brief description

  • Code packages/directories to analyze (IaC, application code, CI/CD configs)

  • Business criticality (critical, high, standard, low)

  • Current pain points (optional)

If the user has already provided architecture details or you are in a codebase with IaC, proceed with discovery without prompting. When no code or IaC is available (the user describes their architecture verbally), proceed using the description as evidence; mark findings you cannot verify in code as "Based on description — verify in code." Do NOT ask for code when the user has already given enough context for a meaningful review.

Determine the review mode (full / quick / pillar-scoped / score) from the user's phrasing — read review modes. Determine whether the workload matches a live lens — read lens guidance when one does.

Step 2: Infrastructure Discovery

Read and follow the discovery procedure.

Step 3: Application Architecture Discovery

Continue following the discovery procedure, including its internal completeness gate before evaluation.

Step 4: Acquire and freeze the live corpus inventory (ACQUIRE_CORPUS gate)

Read and follow the live corpus inventory procedure. First create the run-local working directory this review uses for scratch state — the corpus/ folder that holds questions.jsonl, best-practices.jsonl, and manifest.json referenced below. Then build the complete live corpus inventory (the question + best-practice manifest) by a bounded, read-only traversal of the canonical framework pages (prefer aws___read_documentation; see the reference for the non-MCP HTTPS fallback), reduce each page to structured records immediately, and validate the manifest.

Gate: you MUST NOT begin Step 5 until corpus/manifest.json reports valid: true. The frozen manifest is the sole authority for the expected question and BP sets used by evaluation, the coverage audit, and the report.

Step 5: Evaluate EVERY BP against the frozen manifest

CRITICAL — DO NOT PRODUCE A SHORT REVIEW. The most common failure is citing a subset of BPs and stopping. A full review MUST evaluate every BP in the frozen manifest, each with a status from the five-value vocabulary (with rationale).

Read and follow the evaluation procedure. It defines per-pillar passes against the frozen manifest, aggregation, per-mode adjustments, and the coverage audit (its sub-steps are labelled 5a–5d). For each BP assess:

  • Status: exactly one of "Implemented", "Partially Implemented", "Not Implemented", "Not Applicable", "Cannot Determine"

  • Evidence: specific file paths and line numbers (or "Based on description")

  • Gaps: what is missing or could be improved

  • Risk: what could go wrong due to the gap

Evaluate every pillar in the frozen manifest, using its pillar names, prefixes, and question categories.

Step 6: Risk Assessment

Read and follow the risk assessment procedure, including its internal gate.

Step 7: Produce the report

Mode gate: For score mode, emit only the scorecard output from review modes. For quick and pillar-scoped reviews, apply the mode adjustments from review modes. For a lens-only request (the user named a single WA Lens and did not ask for a full framework review), produce a standalone lens report — the core framework tables are omitted and the deliverable is the Lens Findings section plus a lens scorecard, following lens guidance; when a lens is applied on top of a full review, keep the full structure and add the Lens Findings section. Otherwise — a full review — read the report template and produce the report with that exact structure. The report template is the authoritative list of mandatory sections; the following are the recall-critical ones that a weaker model most often drops (do NOT treat them as the complete set):

  1. Coverage audit (from the evaluation procedure, Step 5d) before the executive summary

  2. Pillar scorecard with per-pillar scores (1-5)

  3. Per-question assessment table — every question in the frozen manifest, no truncation

  4. Full BP Ledger — one row per evaluated BP, concatenated verbatim from the pillar passes

  5. Risk-classified findings (Critical/High expanded, Medium condensed, Low tabular)

  6. Eisenhower-prioritized remediation plan (Do First / Plan / Delegate / Defer) with SMART goals

Emit the report inline as the final response, first line # Well-Architected Review:. Do not defer any section to a file.

Step 8: Offer follow-up

After delivering the report, offer:

Would you like me to:

  • Deep-dive into a specific pillar with expanded analysis?

  • Generate IaC templates to remediate a specific finding?

  • Create a migration plan for a specific architectural change?

  • Compare your workload against a specific WA Lens in detail?

  • Generate automated checks (Config rules, custom metrics) for ongoing compliance?

  • Produce a WA Tool import for tracking in the AWS console?

Calibration Guidance

  • A workload with multi-AZ, encryption, CI/CD with rollback, monitoring, and auto-scaling is MATURE — most findings should be improvements, not Critical

  • Do NOT manufacture Critical findings for a well-built workload — accuracy over alarm

  • When business criticality is "low"/"standard", accept simpler architectures (single-region is fine for internal tools)

  • When business criticality is "critical", apply stricter standards (multi-region DR, chaos testing, sub-minute RTO expected)

  • Every finding MUST have code evidence — no generic recommendations without backing

  • If something cannot be determined from code, say "Cannot Determine" and explain what runtime/interview data is needed

  • Acknowledge strengths prominently — a mature workload should feel validated, not just criticized

Security Considerations

Read and follow security considerations before using review tooling, sharing findings, or persisting artifacts.

Files

references/phase-live-inventory.md

Phase: Live corpus inventory (ACQUIRE_CORPUS)

Build a complete, validated inventory of every live Well-Architected question and best practice before any assessment begins. ASSESS MUST NOT start until the corpus validator passes.

Retrieval mechanism

Prefer the AWS MCP server's documentation reader — aws___read_documentation (call shape: {"requests":[{"url": "...", "max_length": 100000}]}) — when it is available. When the AWS MCP server is unavailable, fetch the same docs.aws.amazon.com URLs over HTTPS with the environment's web-fetch tool (the TOC index below is plain JSON that any HTTPS fetch returns intact). If no documentation access exists at all, enumerate from internal knowledge and disclose that the inventory could not be verified live. Do not depend on any non-public/internal MCP, and do not use semantic search to enumerate.

Two facts that determine the method (both verified live):

  • The reader strips markdown link targets from HTML/MD pages, so you cannot follow links between pages and MUST NOT guess or abbreviate page slugs.

  • The framework publishes a machine-readable table-of-contents index, and the reader returns it verbatim. This index is the corpus source.

Primary source — the TOC index (one call)

Read the framework table of contents:

https://docs.aws.amazon.com/wellarchitected/latest/framework/toc-contents.json

It returns a JSON tree of the whole framework:

{ "contents": [
  { "title": "Operational excellence", "href": "operational-excellence.html", "contents": [
    { "title": "OPS 1. How do you determine what your priorities are?", "href": "ops-01.html", "contents": [
      { "title": "OPS01-BP01 Evaluate external customer needs", "href": "ops_priorities_ext_cust_needs.html" },
      { "title": "OPS01-BP02 Evaluate internal customer needs", "href": "ops_priorities_int_cust_needs.html" }
    ] }
  ] }
] }

Walk the tree recursively. Classify each node by its title / href using general patterns — do NOT hardcode the pillar prefixes, so any pillar AWS adds or renames is picked up automatically:

  • Best-practice node — title matches ^[A-Z]{2,5}\d{2}-BP\d{2}\b. Record: bp_id (the matched ID), bp_title (the remainder of the title), bp_url (base + href), question_id (the PILLAR## prefix of the matched ID), pillar_id/pillar_name (derived from the prefix and the enclosing pillar node's title).

  • Question node — href matches ^[a-z]{2,5}-\d{2}\.html$ (the lowercased pillar stem plus question number). Record its title and href to enrich the question's question_title and question_url.

Base for relative hrefs: https://docs.aws.amazon.com/wellarchitected/latest/framework/.

Notes:

  • Derive the set of questions from the BP prefixes (every SEC02-BP0x implies question SEC02); enrich each with the title/URL from its question node when present. This is robust to the index listing best practices under both the pillar and appendix branches — dedupe best practices by bp_id.

  • Everything needed for the ledger (canonical IDs + titles + URLs + question mapping) is in this one document. Do NOT read the individual best-practice pages here; fetch a single best-practice page later (during assessment) only when its title is insufficient to judge status or when writing a Critical/High recommendation.

Immediate reduction (context discipline)

Parse the index into records in one pass and MUST NOT re-quote the raw index afterward. Persist records as you go; do not narrate the tree.

Records

Write one record per best practice to corpus/best-practices.jsonl and one per question to corpus/questions.jsonl, in the run-local working directory you create at the start of this stage (the corpus/ folder — scratch state only, never part of the delivered report). If that working directory is backed by persistent storage, ensure encryption at rest is enabled (see security considerations).

Best-practice record (wa-review.corpus.v1):

{
  "schema_version": "wa-review.corpus.v1",
  "pillar_id": "operational-excellence",
  "pillar_name": "Operational Excellence",
  "question_id": "OPS01",
  "question_title": "OPS 1. How do you determine what your priorities are?",
  "question_url": "https://docs.aws.amazon.com/wellarchitected/latest/framework/ops-01.html",
  "bp_id": "OPS01-BP01",
  "bp_title": "Evaluate external customer needs",
  "bp_url": "https://docs.aws.amazon.com/wellarchitected/latest/framework/ops_priorities_ext_cust_needs.html",
  "retrieved_at": "2026-09-08T12:00:00Z"
}

Validation gate (must pass before ASSESS)

Write corpus/manifest.json with counts, per-pillar question counts, provenance (index URL + UTC retrieval time), and a validation verdict. The validator MUST confirm:

  • Every pillar discovered in the TOC top-level entries is represented, and each discovered pillar carries at least one best practice (do not assert a fixed pillar count — a newly added pillar must not fail this check).

  • Every BP ID matches canonical PILLAR##-BP##; BP IDs are unique after dedupe.

  • Question IDs are unique; every question has at least one BP.

  • Every BP refers to a discovered question and pillar.

  • The global BP set equals the union of per-question BP sets.

  • Provenance (index URL, retrieval time) is recorded; no stale/cached manifest is silently reused as live content.

A parse that yields zero BP IDs, or fewer than a sanity floor, is an acquisition failure — go to Recovery. Never invent a BP ID to fill a gap. As a post-hoc sanity check recorded in the manifest, confirm each discovered pillar carries a non-trivial number of best practices (> 0, with a plausible spread across pillars rather than one pillar holding almost all of them) — do not pin the check to specific question or BP totals. The parsed live index is the sole source of truth for the inventory.

Recovery (fallback traversal)

If toc-contents.json is unavailable (HTTP/parse error) or yields no best practices:

  1. Retry the index read once.

  2. If still failing, fall back to construct-and-iterate over question pages, which the reader supports even though it strips links. First discover the current set of pillar stems dynamically: read the framework appendix page (or the framework landing page) and take the lowercased stem of each pillar it lists — do not start from a hardcoded stem list, so a newly added pillar is still covered. Then, for each discovered stem, read <base><stem>-01, -02, … (i.e. <stem>-NN), incrementing until the page is missing — that missing page is the clean pillar boundary, wherever it falls, so do not assume a fixed per-pillar question count. Each question page lists its PILLAR##-BP## IDs as text; derive question_id from the BP prefix (not the heading, which varies: SEC 2. vs SUS 6).

    The page suffix and the missing-page signal depend on the retrieval tool. The canonical pages are served as .html (e.g. operational-excellence.html, ops-01.html):

    • aws___read_documentation: request the markdown-suffixed form the reader accepts (verified live) — <base>appendix.md, then <base><stem>-NN.md — and stop when a read returns the reader's sentinel string "Documentation page not found.".

    • Non-MCP HTTPS web-fetch fallback: request the canonical .html form — <base>appendix.html, then <base><stem>-NN.html (a plain HTTPS fetch of a .md suffix 404s because the site serves .html) — and stop on an HTTP 404.

  3. To relocate a specific moved page, use aws___search_documentation when the AWS MCP server is available; otherwise use the environment's web-search tool scoped to docs.aws.amazon.com over HTTPS; if neither is available, skip the relocated page and note the gap in the coverage audit. Use this ONLY to relocate a moved page — never to supply BP IDs.

Freshness

Read the index live for every review. Do not reuse a prior run's manifest as current content unless the user explicitly authorizes a cache whose freshness policy is disclosed in the coverage audit.

Transition

ACQUIRE_CORPUS -> ASSESS only when corpus/manifest.json reports valid: true. The frozen manifest is the sole authority for the expected question and BP sets used by per-question validation, derivation, and the final report validator.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
AWS
Publisher
AWS (Official)
Source
aws/agent-toolkit-for-aws · skills/core-skills/aws-well-architected-review · commit 0a218f8
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • NOTICE (added by AutoGineer from NOTICE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Also distributed in
aws/agent-toolkit-for-aws

AutoGineer is not affiliated with or endorsed by AWS or AWS.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-well-architected-review.zip