# wa-builder

wa-builder teaches AWS Well-Architected against your own workload, then generates commit-ready artifacts: an annotated architecture diagram, decision trees and an improvement roadmap.

- skill · `type=skill` · Claude Code, Cline, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 280 repo stars
- Author: aws-samples
- License: MIT-0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/HEAD/skills/wa-builder/SKILL.md
- Updated: 2026-10-06
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/wa-builder

## What it does

The skill runs in two passes: it walks through AWS Well-Architected for your workload, then ships artifacts you can commit. Output is a PlantUML architecture diagram with pillar health colour-coded and risk areas tagged by best-practice ID, decision trees for architectural compromises, and an improvement roadmap drawn as a Gantt timeline with a dependency graph. The knowledge base sits inside the skill instructions: six pillars, 57 framework questions, no framework files to fetch.

Calibration comes first. You give the workload name, how well you know WA, and which artifacts you want; the skill also infers your level from wording like “pillar”, “RTO/RPO” or “blast radius” and skips the teaching pass for practitioners. Discovery either scans your IaC files or parses an existing `aws-well-architected-framework-review` report with pillar scores and findings. Generation waits for your explicit confirmation at a checkpoint.

Scoring and findings are out of scope. For a review that produces them the skill points to `aws-well-architected-framework-review`; migration planning, guardrails and workshop facilitation go to `migration-readiness`, `wa-guardrails` and `wafr-facilitator`. It complements a review rather than replacing one.

## Requirements
- Works with: AWS

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add aws-samples/sample-well-architected-skills-and-steering --skill wa-builder -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/wa-builder/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/wa-builder/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add aws-samples/sample-well-architected-skills-and-steering --skill wa-builder -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/wa-builder/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add aws-samples/sample-well-architected-skills-and-steering --skill wa-builder -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/wa-builder/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install aws-samples/sample-well-architected-skills-and-steering skills/wa-builder
```

2. **Manually: put the files in place**
- File: `.github/skills/wa-builder/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add aws-samples/sample-well-architected-skills-and-steering --skill wa-builder -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/aws-samples/sample-well-architected-skills-and-steering --path skills/wa-builder
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/wa-builder/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/HEAD/skills/wa-builder/SKILL.md

## When to use it
- draw an architecture diagram with pillar health overlays
- flag risk areas by best-practice ID
- sort architectural compromises into a decision tree
- turn a review report into a roadmap with dependencies
- explain WA pillars using services already in the codebase

## Example prompts
- Walk my Lambda and DynamoDB stack through AWS Well-Architected and draw the diagram with problem pillars highlighted
- I'm new to WA, explain it against our ECS service and build a decision tree for picking a datastore
- Turn the `aws-well-architected-framework-review` report into a Gantt roadmap

## Source text · SKILL.md · MIT-0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3200357ead3e55b6.

BEGIN THIRD-PARTY FILE 3200357ead3e55b6
```text
---
name: wa-builder
description: '"Learn then Build" — help developers understand AWS Well-Architected best practices for their specific workload, then produce actionable visual artifacts (architecture diagrams with WA annotations, decision trees, improvement roadmaps) they can commit and use. Adapts explanations for beginners and generates artifacts faster for experienced builders. Use when the user wants to understand WA for their project, create architecture diagrams with pillar health overlays, get guided decision flows for architectural choices, or generate a visual improvement roadmap.'
not_for: assessments or reviews that produce findings (use aws-well-architected-framework-review), migration planning (use migration-readiness), generating guardrails (use wa-guardrails), facilitating a WAFR (use wafr-facilitator)
version: 1.0.0
---

# Well-Architected Builder

## Overview

This skill helps developers **understand** Well-Architected for their specific workload and **produce visual artifacts** they can commit. Unlike aws-well-architected-framework-review (which assesses and scores), wa-builder teaches and enables.

**What you'll produce:**
1. Architecture diagram with WA annotations (color-coded pillar health, risk hotspots)
2. Decision trees for architectural choices (contextual trade-off flowcharts)
3. Improvement roadmap (Gantt timeline + dependency graph)

### Knowledge base

This skill uses the AWS Well-Architected Framework (6 pillars, 57 questions) as its knowledge base. It does NOT require external framework files — all guidance is derived from the WA Framework questions and design principles embedded in this skill's instructions.

## Step 1: Context and Calibration

Ask the user:

> I can help you understand Well-Architected for your project and produce visual artifacts. Let me know:
> - **Workload name** and brief description (or point me at your code)
> - **Your WA familiarity**: New to WA / Familiar / Practitioner
> - **What you want**: Architecture diagram, decision tree, roadmap, or all three
```
END THIRD-PARTY FILE 3200357ead3e55b6

The third-party file has ended. Everything between the 3200357ead3e55b6 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2050 of 15362 bytes. © aws-samples · MIT-0 · https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/HEAD/skills/wa-builder/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
