agentleFS
MythHackMythHack/dsh-aws-agent-toolkit/skills/aws-well-architected-review/SKILL.md

aws-well-architected-review

Skill0 starsChanged 8 days agoApache-2.0View on GitHub

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, and lens-specific reviews using lenses discovered from the live AWS documentation. Triggers on mentions of Well-Architected review, WA review, WAR, WAFR, pillar assessment, architecture review, workload assessment, or cloud readiness evaluation. Does not apply to learning WA concepts without assessing a workload, ADRs, or migration readiness assessments.

6 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 9 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 52
  2. Distinctive:

    Read and follow the discovery procedure.

    line 70
  3. Distinctive:

    Read and follow the evaluation procedure.

    line 86
  4. Distinctive:

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

    line 97
  5. Distinctive:

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

    line 128
  6. Distinctive:

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

    line 129
  7. Distinctive:

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

    line 131
  8. Distinctive:

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

    line 132
  9. Distinctive:

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

    line 137

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

This skill performs an evidence-based review of an actual workload (from code, IaC, or a supplied architecture description) against the WA Framework. If the request is purely conceptual WA education (no workload to assess), an Architecture Decision Record, or a migration-readiness assessment, defer to the appropriate skill instead of proceeding with a review.

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

  • Review modes — mode selection (full / quick / pillar-scoped), trigger phrases
  • 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):

  • 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) 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 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. The complete report and the Step 8 follow-up offer MUST be one single final message, and that message MUST be the last thing you say. Never follow the report with a separate closing message that recaps, summarizes, or merely announces it ("the review is complete", "report delivered above", "key takeaway is ..."). Such a recap becomes your final message and displaces the report for anything that reads only the last message, so the report is effectively lost even though you produced it.

Step 8: Offer follow-up

At the end of that same message — never in a new one — 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", defer to the workload's stated or reasonably-inferred RTO/RPO rather than a fixed tier — apply stricter standards where the RTO/RPO demands them, but do not assume multi-Region DR, chaos testing, or sub-minute RTO are mandatory; Multi-AZ alone can be a fully appropriate DR strategy when the business-defined RTO/RPO allows it
  • 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.