How to use the AWS Well-Architected Review agent skill

What the skill makes the agent do

The agent reviews your AWS infrastructure-as-code files (Terraform, CloudFormation, SAM or CDK) and, where possible, your live AWS setup. It checks them against the six pillars of the AWS Well-Architected Framework: operational excellence, security, reliability, performance efficiency, cost optimization and sustainability.

Each gap it finds is classified as high, medium or low risk. The agent then shows you a summary and asks for confirmation before creating anything. Once you approve, it can create one GitHub issue per finding plus a single tracking epic issue.

• Discovers IaC files such as **/*.tf, **/*.yaml and **/*.json templates, and lib/**/*.ts, bin/**/*.ts and cdk.json for CDK
• Identifies AWS services in use and generates a Mermaid architecture diagram
• Reviews each pillar against a checklist, for example S3 public access blocking, DynamoDB point-in-time recovery and CloudTrail for audit logging
• Labels issues with "well-architected" and the pillar name

Install the skill in Claude

Download the ZIP file from this page. The skill is distributed as a package whose main file is SKILL.md. You can install it in one of three places, depending on whether you want it for yourself across projects or for one repository.

For a personal install, unzip the file into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ in your repository
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you run it

The skill depends on several tools being ready. Set these up first, otherwise the review will stall or fall back to a narrower scope.

The skill also needs network access to fetch AWS Well-Architected documentation, and it runs scripts. Read the safety section below before using it on a production account.

• AWS CLI installed, configured and authenticated
• IaC files in the repository (Terraform, CloudFormation, CDK or SAM)
• GitHub MCP server configured and authenticated, for creating issues
• Network access to fetch AWS Well-Architected documentation
• Read-only AWS permissions for the live review. The skill lists the permissions it needs if access is insufficient

Trigger the skill with a natural request

You do not need a special command. Describe what you want in plain language from a session in the repository that holds your infrastructure code. The agent matches your request to the skill's description, which covers reviewing the workload IaC and architecture and generating findings and GitHub issues.

Good requests name the outcome you want. Mention the pillars or the risk level if you want to focus, and say whether you want issues created or only a report.

• "Run an AWS Well-Architected review of this repo's Terraform and tell me the high-risk findings."
• "Review our CloudFormation templates against the Well-Architected Framework before the security review on Friday."
• "Do a WAF review of the CDK app and show the summary, but don't create any issues yet."

Read the summary and approve the issue creation

After analysis the agent prints a summary with the number of IaC files analyzed, AWS services identified and findings by risk level. It lists the top high-risk findings and states how many individual issues and how many epic issues it will create.

Read this list before you answer. The agent asks whether to proceed (y/n). Approving leads to many GitHub issues being created in one step, so decline or ask for changes if the findings look wrong.

• Check the IaC file count matches what you expect
• Check that findings point to resources you actually own
• Reply n or ask for a narrower scope if the list is too long

Understand what gets created in GitHub

Each finding becomes an issue titled in the form [WAF-<PILLAR>] [Brief Finding] — [Risk Level]. The body includes a description, a remediation step (an IaC fix preferred, with an AWS CLI fallback), AWS reference links and a validation checklist. A single EPIC issue summarizes the review with a pillar breakdown table, the architecture diagram and a prioritized checklist linking the individual issues.

The epic's success criteria are: all high-risk findings resolved, medium findings with accepted mitigation plans, and no regression in existing CloudWatch alarms or Config rules.

Safety notes: scripts and network access

This skill runs scripts and uses the network. It runs AWS CLI commands against your account to inspect live resources, and it fetches AWS documentation. Because the workflow is built around IaC files, review the proposed commands and issues before approving.

Use credentials with read-only permissions for the live part of the review. Remember that the GitHub step writes to your repository's issue tracker, so confirm the target repository is correct before you say yes.

• Use read-only AWS credentials where possible
• Confirm the GitHub repository is the one you intend before approving
• Do not run it against accounts you are not authorised to inspect