feat: add aws-well-architected-review skill

[DheerajGBhatt]

AWS Well-Architected Review Skill

Overview

A skill that enforces AWS Well-Architected best practices during both infrastructure generation and code review.

The skill operates in two distinct modes:

• Generate Mode: Ensures all newly created infrastructure follows best practices from the first draft
• Review Mode: Analyzes existing infrastructure and identifies anti-patterns with actionable fixes

It is designed to work across multiple Infrastructure as Code (IaC) frameworks and automatically adapts to the project’s context.

Video

https://drive.google.com/file/d/11OHiGAgBjiAP5AAF-RgtOzC7zf5dzuPk/view?usp=drive_link

---

Core Functionality

Generate Mode

In generation workflows, the skill ensures that infrastructure is created with Well-Architected defaults applied by design, eliminating the need for later corrections.

It enforces best practices across key AWS services.

Review Mode

In review workflows, the skill scans existing infrastructure and application code to detect anti-patterns across all Well-Architected pillars.

It produces a structured findings report that includes:

• Architecture summary
• Identified services and patterns
• Quick wins (low-effort, high-impact fixes)
• Detailed findings grouped by pillar
• Severity classification
• File-level references
• Concrete fixes in the same framework and language

---

Supported Frameworks

The skill supports multiple IaC frameworks and automatically detects the framework and language used in the project:

• AWS CDK (TypeScript, Python)
• AWS SAM (YAML, JSON)
• CloudFormation (YAML, JSON)
• Terraform (HCL)
• Serverless Framework (YAML)

---

Pillars Evaluated

The skill evaluates infrastructure against all major AWS Well-Architected pillars along with cross-cutting concerns:

• Security
  IAM least privilege, encryption, public access, secrets management, network isolation

• Reliability
  DLQs, retries, backups, idempotency, fault tolerance mechanisms

• Performance Efficiency
  Resource sizing, compute choices, caching, batching, architecture optimizations

• Cost Optimization
  Over-provisioning, scaling strategies, log retention, lifecycle policies, cost-heavy resources

• Operational Excellence
  Observability, CI/CD readiness, deployment strategies, tagging, infrastructure coverage

• Sustainability
  Efficient resource usage, batching, reduced idle compute

• Cross-Cutting Concerns
  Event-driven design, service coupling, error handling, backpressure, environment isolation

---

Skill Behavior

The skill is automatically triggered in both generation and review scenarios.

Generation use cases:

• Creating new infrastructure stacks
• Adding services to existing systems
• Scaffolding new serverless applications

Review use cases:

• Reviewing infrastructure or backend code
• Validating AWS best practices
• Performing architecture audits during pull requests

---

Output Structure (Review Mode)

The review output follows a consistent and structured format:

• Architecture summary (services, patterns, framework)

• Quick wins for immediate improvements

• Findings grouped by pillar

• Each finding includes:

  • Unique identifier
  • Severity level
  • Description
  • File reference
  • Recommended fix

This ensures the output is directly actionable during development and code review.

[github-actions]

Skill Evaluator — Tier 1 Results

✅ All checks passed

skills/aws-well-architected-review

Using CPython 3.11.15 interpreter at: /opt/hostedtoolcache/Python/3.11.15/x64/bin/python3
Creating virtual environment at: .venv
Downloading tiktoken (1.1MiB)
 Downloaded tiktoken
Installed 8 packages in 12ms
=== Skill Evaluation Report ===
Skill: aws-well-architected-review

--- Tier 1: Deterministic Checks ---
[PASS] SKILL.md exists
[PASS] kebab-case directory
[PASS] YAML frontmatter
[PASS] metadata.json
[PASS] length/efficiency — 3318 tokens. Instruction/code ratio: 6.5.
[PASS] prerequisites — Broad prerequisites detected (aws, database, terraform). May limit audience.
[PASS] security patterns — Has security section.

--- Summary ---
Tier 1: 7/7 passed

[vishwasnavadak]

update https://github.com/antstackio/skills/blob/main/README.md with the updated list that includes this skill as well.