sample-well-architected-skills-and-steering

# Well-Architected Skills & Steering for AI Coding Agents

> **Status: deprecated.** AWS now ships an actively maintained equivalent — the `aws-well-architected-review` skill in [Agent Toolkit for AWS](https://github.com/aws/agent-toolkit-for-aws) (https://aws.amazon.com/products/developer-tools/agent-toolkit-for-aws/). New feature/skill work is not accepted here; this repo remains available as a compatibility/regression suite. See SUCCESSOR_HANDOFF.md and https://github.com/aws-samples/sample-well-architected-skills-and-steering/issues/147.

> Reusable skills and steering that teach AI coding agents how to apply the AWS Well-Architected Framework. One set of playbooks, 15 supported tools.

## What this repo contains

This repository provides ready-to-use instruction sets that make AI coding agents Well-Architected aware. When loaded, you should apply the six pillars (Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, Sustainability) to architecture discussions, code reviews, and design decisions.

## Installation

Install via [skills.sh](https://skills.sh) (no clone needed):

```
npx skills add aws-samples/sample-well-architected-skills-and-steering
```

Or via bootstrap script:

```
curl -sL https://raw.githubusercontent.com/aws-samples/sample-well-architected-skills-and-steering/main/bootstrap.sh | bash
```

## How to use this content

### If you are an AI agent assisting a developer:

1. Read `steering/well-architected.md` for always-on principles (pillars, design principles, trade-offs, response format).
2. When the user requests a specific assessment, read the corresponding skill file from `skills/{skill-name}/SKILL.md` and follow its steps.
3. Skills are self-contained — each one is a complete playbook you can execute independently.

### Available skills:

- `skills/aws-well-architected-framework-review/SKILL.md` — Full or pillar-scoped Well-Architected review with BP-level citations
- `skills/wa-builder/SKILL.md` — Learn WA for your workload and produce visual artifacts (diagrams, decision trees, roadmaps, ADRs)
- `skills/wa-guardrails/SKILL.md` — Generate preventive controls (Config rules, SCPs, CI checks, alarms) for ongoing adherence to WA guidance
- `skills/wafr-facilitator/SKILL.md` — Prepare conversational WAFR facilitation with customers
- `skills/migration-readiness/SKILL.md` — 7 Rs assessment with migration plan
- `skills/example-skill/SKILL.md` — Template for authoring a new skill

Pillar deep-dives (`security-assessment`, `reliability-improvement-plan`,
`cost-optimization-review`, `performance-efficiency`, `sustainability-optimization`,
`operational-excellence`) and `architecture-decision-record` are aliases: they route to
`aws-well-architected-framework-review` with a pillar scope, or to `wa-builder` in ADR mode.
There is no separate SKILL.md for them.

### Reference material:

- `skills/aws-well-architected-framework-review/references/manifest.md` — Catalog of every canonical Best Practice ID across the 6 pillars
- `skills/aws-well-architected-framework-review/references/pillars/` — One merged reference file per pillar (every question, every best practice)
- `skills/aws-well-architected-framework-review/references/pillar-playbooks/` — Per-pillar evidence-collection checklists and anti-patterns
- `skills/aws-well-architected-framework-review/references/lenses/` — Lens-specific best-practice extensions
- `skills/aws-well-architected-framework-review/references/wa-questions.md` — The WA question set

## Architecture of this repo

```
steering/       → Always-on context (principles, pillars, format guidance)
skills/         → On-demand playbooks (step-by-step assessment procedures)
powers/         → Kiro Powers (bundled installable units with contextual activation)
schemas/        → JSON Schema for the machine-readable review artifact
tools/          → wa-ci, the CI gate that consumes that artifact
adapters/       → Tool-specific packaging (Claude Code, Cursor, Kiro, OpenClaw, etc.)
evals/          → Automated evaluation runner (Amazon Bedrock)
plugin.json     → Agent Plugins 1.0.0 manifest (portable plugin package)
install.sh      → Setup script for macOS/Linux
install.ps1     → Setup script for Windows
```

Skills are tool-agnostic. Adapters translate them into each tool's native format. Powers bundle steering + MCP tools for Kiro's installable unit system. You do not need to read adapter files — read skills directly.

## Key principles to apply

When giving Well-Architected guidance:
- Lead with the most critical finding
- Group findings by pillar
- Use severity labels: 🔴 High Risk, 🟡 Medium Risk, 🟢 Best Practice
- Include "Why it matters" for each finding
- Provide concrete next steps with AWS service recommendations
- Acknowledge trade-offs explicitly (security vs latency, availability vs cost, etc.)
- For well-architected systems, focus on advanced improvements rather than critical findings

## Design principles to recommend

- Favor managed services over self-managed infrastructure
- Design for failure — assume any component can fail at any time
- Decouple components to reduce blast radius
- Use multiple Availability Zones for high availability
- Implement least-privilege access for all identities
- Automate everything that can be automated
- Use infrastructure as code for all environments
- Design for observability from day one

## Evaluations

Each skill includes test cases in `skills/*/evals/evals.json`. The `evals/` directory contains an automated runner powered by Amazon Bedrock that measures skill impact (baseline vs with-skill) using LLM-as-judge grading. Run it yourself to see the delta in your own environment; this repository publishes the harness, not its results.