AWS Well Architected Review
AWSOfficialPublished by AWS
- Skill
- Review and audit
- Cloud and DevOps
- Apache-2.0
- No issues found
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
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/aws/aws-well-architected-review/downloadUnzip 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_CORPUSstage: deterministic read-only traversal of the framework, the corpus records, and the validation gateEvaluation 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):
Coverage audit (from the evaluation procedure, Step 5d) before the executive summary
Pillar scorecard with per-pillar scores (1-5)
Per-question assessment table — every question in the frozen manifest, no truncation
Full BP Ledger — one row per evaluated BP, concatenated verbatim from the pillar passes
Risk-classified findings (Critical/High expanded, Medium condensed, Low tabular)
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
- ATTRIBUTION.mdAdded by AutoGineer919 B
- LICENSELicence file added by AutoGineer9.9 KiB
- NOTICELicence file added by AutoGineer67 B
- SKILL.md11.7 KiB
- assets/report-template.md6.6 KiB
- references/discovery-procedure.md3.5 KiB
- references/evaluation-procedure.md9.7 KiB
- references/lens-guidance.md2.1 KiB
- references/phase-live-inventory.md8.3 KiB
- references/review-modes.md4.7 KiB
- references/risk-assessment.md1.6 KiB
- references/security-considerations.md4.3 KiB
LICENSE
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
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.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-well-architected-review.zip