A Well-Architected review of your AWS SaaS or agent with Claude Code

If you run a SaaS or an agent on AWS and have never been through a Well-Architected review, you can now produce a first draft on your own from Claude Code. Install the aws-core plugin, start with a single-pillar review, and read the report as a list of questions, not a pass mark.

What it is

The AWS Well-Architected Framework is the set of best practices AWS uses to assess an architecture: six pillars (operational excellence, security, reliability, performance efficiency, cost and sustainability), plus “lenses” for specific kinds of workload, such as serverless, SaaS or agentic AI. A review means going question by question and checking whether your system follows each practice. Done by hand, it takes days.

On October 28, the AWS Architecture Blog described how Smarsh, a communications archiving company, automated that review for its agents. They used the Agentic AI Lens, which has 150 best practices across 41 questions and still can’t be selected in the Well-Architected console. They packaged it as a Claude skill (a bundle of instructions, data and scripts the model loads when it needs them) with three parts:

A JSON file with the 150 practices, which is the single source of truth. The skill is not allowed to invent or renumber practices.
An assessment guide with five possible statuses. Every status has to cite evidence from the repository, and when there is none, the practice is marked “Not Reviewed” instead of guessed.
A Python script that builds the final spreadsheet and rejects any ID or status that doesn’t exist.

According to the post, the full draft takes “hours instead of a multi-day manual effort”. In their tests on two sample repositories, the skill met 16 of 16 expectations and Claude without the skill met 8 of 16. Those are synthetic repos and the company’s own results, so read it as a signal, not a benchmark.

Smarsh’s code is not public. What is public is what AWS has released around it.

What you can install today

The original lead for this post was the aws-samples/sample-well-architected-skills-and-steering repository: MIT-0 skills covering 307 best practices, 57 questions and 27 lenses, including Agentic AI, Serverless and SaaS. But its README now marks it as deprecated and closed to new contributions. Its successor is the aws-well-architected-review skill in Agent Toolkit for AWS, under Apache 2.0.

The difference matters. The old repo ships a snapshot of the AWS docs taken on a given date, and its own README warns that keeping it current is your job. The new skill reads the AWS documentation at review time.

In Claude Code you install it from the official marketplace, which is added by default:

/plugin install aws-core@claude-plugins-official

If you get Plugin not found, refresh the index first with /plugin marketplace update claude-plugins-official. The plugin also bundles the AWS MCP Server configuration, which the skill recommends for reading the docs. Searching the documentation needs no AWS credentials; you only need them to call the API on your account.

How to use it

Open Claude Code in the repo you want reviewed. The skill discovers the workload from your code, your infrastructure as code (CDK, CloudFormation, Terraform) and your CI pipelines.
Pick the mode through your wording. There are four: a per-pillar score (“score this architecture”), a quick question-level review, a review of one or two pillars (“review only security and reliability”) and a full review.
Ask for a lens when it fits. For example: “Run a Well-Architected review of this repo for security and reliability only, and apply the Serverless Lens”. Lenses add to the framework questions and get their own section in the report.
Read what it couldn’t check first. Each practice gets one of five statuses, and one of them is “Cannot Determine”. The skill explains which piece of data is missing, usually something that lives in your AWS account and not in the code.

The report includes a 1-to-5 score per pillar, a per-question table, findings ranked by risk and a prioritized remediation plan.

My take

I’d use it before a conversation with AWS or with a large customer’s security team, and not as a certificate. Smarsh’s case makes the point: the gaps the repo couldn’t answer became the agenda for their meeting with AWS architects. When you build alone, that’s the real value: walking into the meeting knowing what to ask.

I wouldn’t start with the full review. It’s the heaviest mode, it covers all six pillars, and its token cost grows with what it finds. For a small SaaS, security and reliability are the two pillars where a failure hits the customer directly: one tenant seeing another tenant’s data, or an outage with no way back. Start there.

What I like most about Smarsh’s approach is the honesty rule: no evidence, no checkmark. An agent that fills 150 boxes with “compliant” is worse than no review at all, because it gives you peace of mind you haven’t earned. If you build your own skill for another checklist, copy that rule and the script that rejects made-up IDs.

One common-sense warning: the report describes your infrastructure and its holes. Treat it as confidential and keep it out of public repos.

Sources

If you want to see how I review AWS architectures with agents and no team, follow me on LinkedIn.