GitHub - aws-samples/sample-well-architected-skills-and-steering: Reusable skills and steering that teach AI coding agents how to apply the AWS Well-Architected Framework. One set of playbooks, 14 supported tools.

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

Kiro · Kiro CLI · Claude Code · Cursor · Codex · Windsurf · GitHub Copilot · Gemini CLI · Antigravity · Junie · Amp · OpenClaw · Cline · Cortex Code · AWS DevOps Agent

🎯 Why this exists

Developers don't stop to consult documentation — they ask their AI assistant. If the assistant doesn't know the Well-Architected Framework, the guidance never reaches the code.

This project embeds WA best practices where development actually happens: in the IDE, at the moment code is being written. Instead of treating architecture reviews as a separate gate, teams get continuous, contextual guidance that:

• ✅ Reduces rework by catching misalignments early
• ✅ Works across 14 AI coding tools with a single source of truth
• ✅ Requires no AWS credentials, no API calls — everything runs locally
• ✅ Follows the open Agent Skills specification

📦 What's inside

steering/                           Always-on context (Kiro)
  well-architected.md                 Pillars, design principles, review process
  wa-review.md                        Deep multi-step WA review (evidence-based, constrained)

skills/                             Step-by-step playbooks (tool-agnostic)
  wa-review/                          Full or pillar-scoped review (all 6 pillars + 27 lenses)
    references/manifest.md              Canonical catalog of all 307 BP IDs (loaded first)
    references/pillars/                 6 pillar-merged files (one per pillar; subagent references)
    references/lenses/                  Lens-specific references (27 lenses)
    references/pillar-playbooks/        Per-pillar deep-dive discovery procedures
  wa-builder/                         Learn WA + produce artifacts (diagrams, trees, roadmaps, ADRs)
  wa-guardrails/                      Preventive controls (Config rules, SCPs, CI checks)
  wafr-facilitator/                   Conversational WAFR facilitation with customers
  migration-readiness/                7 Rs assessment with migration plan

scripts/                            Maintenance tooling
  crawl-wa-framework.py               Crawl AWS docs to regenerate reference files

adapters/                           Tool-specific configuration
  claude-code/                        CLAUDE.md + slash commands
  cursor/                             .cursor/rules/*.md
  codex/                              AGENTS.md
  windsurf/                           .windsurfrules
  github-copilot/                     .github/copilot-instructions.md
  cline/                              .clinerules
  gemini-cli/                         GEMINI.md
  antigravity/                        .agents/rules/*.md
  junie/                              .junie/guidelines + .junie/skills
  amp/                                .agents/skills/*.md
  openclaw/                           AGENTS.md + .agents/skills/*.md
  cortex-code/                        AGENTS.md + skills/*.md (Snowflake)
  devops-agent/                       Packaging for AWS DevOps Agent

powers/                             Kiro Powers
  wa-review/                          Full WA review with auto-activation and progressive references

evals/                              Automated evaluation runner (Bedrock)
  run.py                              CLI entry point
  grade.py                            LLM-as-judge grader
  report.py                           Scoring and terminal output
  config.yaml                         Bedrock region and model config
  benchmark.py                        Multi-model comparison runner
  benchmark_report.py                 Generate markdown tables from benchmark results
  benchmark_config.yaml               Models, prompt, and grading criteria
  pyproject.toml                      Dependencies (use uv sync)

install.sh                          One-command setup (macOS/Linux)
install.ps1                         One-command setup (Windows PowerShell)

🚀 Quick start

One-liner (no clone needed)

Via skills.sh

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

Auto-detects your AI agent and installs skills directly. Use --list to preview available skills, or --skill <name> to install a specific one:

# List available skills
npx skills add aws-samples/sample-well-architected-skills-and-steering --list

# Install a specific skill
npx skills add aws-samples/sample-well-architected-skills-and-steering --skill wa-review

# Install globally (user-level, applies to all projects)
npx skills add aws-samples/sample-well-architected-skills-and-steering -g

Via bootstrap script

macOS / Linux:

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

Windows (PowerShell):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/aws-samples/sample-well-architected-skills-and-steering/main/bootstrap.ps1)))

Auto-detects your AI tools (.cursor/, .claude/, .kiro/, .junie/, .openclaw/, etc.), installs for all of them, and cleans up.

To install for a specific tool instead:

# macOS / Linux
curl -sL .../bootstrap.sh | bash -s -- --tool kiro

# Windows (PowerShell)
& ([scriptblock]::Create((irm .../bootstrap.ps1))) -Tool kiro

Install script (from local clone)

macOS / Linux:

# Auto-detect tools in your project
./install.sh ~/my-project --tool auto

# Install for a specific tool
./install.sh ~/my-project --tool claude-code

# Install for multiple tools at once
./install.sh ~/my-project --tool kiro --tool claude-code --tool cursor

# Install for all supported tools
./install.sh ~/my-project --tool all

# Use symlinks for automatic updates
./install.sh ~/my-project --tool claude-code --symlink

# Install globally (applies to all projects)
./install.sh --global --tool claude-code

Windows (PowerShell):

# Auto-detect tools in your project
.\install.ps1 -TargetDir C:\Projects\my-app -Tool auto

# Install for a specific tool
.\install.ps1 -TargetDir C:\Projects\my-app -Tool claude-code

# Install for multiple tools at once
.\install.ps1 -Tool kiro, claude-code, cursor

# Install for all supported tools
.\install.ps1 -Tool all -Force

# Install globally (applies to all projects)
.\install.ps1 -Global -Tool claude-code

Manual installation

mkdir -p .kiro/steering .kiro/skills
cp path/to/this-repo/steering/well-architected.md .kiro/steering/
cp -r path/to/this-repo/skills/* .kiro/skills/

New-Item -ItemType Directory -Force -Path .kiro\steering, .kiro\skills
Copy-Item path\to\this-repo\steering\well-architected.md .kiro\steering\
Copy-Item -Recurse path\to\this-repo\skills\* .kiro\skills\

git clone https://github.com/aws-samples/sample-well-architected-skills-and-steering.git

cp path/to/this-repo/adapters/claude-code/CLAUDE.md ./CLAUDE.md
cp -r path/to/this-repo/adapters/claude-code/commands .claude/commands

Copy-Item path\to\this-repo\adapters\claude-code\CLAUDE.md .\CLAUDE.md
Copy-Item -Recurse path\to\this-repo\adapters\claude-code\commands .claude\commands

cp -r path/to/this-repo/adapters/cursor/rules .cursor/rules

Copy-Item -Recurse path\to\this-repo\adapters\cursor\rules .cursor\rules

cp path/to/this-repo/adapters/codex/AGENTS.md ./AGENTS.md
cp -r path/to/this-repo/skills ./skills

Copy-Item path\to\this-repo\adapters\codex\AGENTS.md .\AGENTS.md
Copy-Item -Recurse path\to\this-repo\skills .\skills

cp path/to/this-repo/adapters/windsurf/.windsurfrules ./.windsurfrules

Copy-Item path\to\this-repo\adapters\windsurf\.windsurfrules .\.windsurfrules

mkdir -p .github
cp path/to/this-repo/adapters/github-copilot/.github/copilot-instructions.md .github/

New-Item -ItemType Directory -Force -Path .github
Copy-Item path\to\this-repo\adapters\github-copilot\.github\copilot-instructions.md .github\

cp path/to/this-repo/adapters/gemini-cli/GEMINI.md ./GEMINI.md
cp -r path/to/this-repo/skills ./skills

Copy-Item path\to\this-repo\adapters\gemini-cli\GEMINI.md .\GEMINI.md
Copy-Item -Recurse path\to\this-repo\skills .\skills

mkdir -p .agents/rules .agents/skills
cp -r path/to/this-repo/adapters/antigravity/rules/* .agents/rules/
for skill_dir in path/to/this-repo/skills/*/; do
  skill_name=$(basename "$skill_dir")
  mkdir -p ".agents/skills/$skill_name"
  cp "$skill_dir/SKILL.md" ".agents/skills/$skill_name/SKILL.md"
done

New-Item -ItemType Directory -Force -Path .agents\rules, .agents\skills
Copy-Item -Recurse path\to\this-repo\adapters\antigravity\rules\* .agents\rules\
Get-ChildItem path\to\this-repo\skills -Directory | ForEach-Object {
    New-Item -ItemType Directory -Force -Path ".agents\skills\$($_.Name)"
    Copy-Item "$($_.FullName)\SKILL.md" ".agents\skills\$($_.Name)\SKILL.md"
}

mkdir -p .junie/guidelines .junie/skills
cp path/to/this-repo/adapters/junie/guidelines.md .junie/guidelines/well-architected.md
cp -r path/to/this-repo/skills/* .junie/skills/

New-Item -ItemType Directory -Force -Path .junie\guidelines, .junie\skills
Copy-Item path\to\this-repo\adapters\junie\guidelines.md .junie\guidelines\well-architected.md
Copy-Item -Recurse path\to\this-repo\skills\* .junie\skills\

cp path/to/this-repo/adapters/amp/AGENTS.md ./AGENTS.md
mkdir -p .agents/skills
cp -r path/to/this-repo/skills/* .agents/skills/

Copy-Item path\to\this-repo\adapters\amp\AGENTS.md .\AGENTS.md
New-Item -ItemType Directory -Force -Path .agents\skills
Copy-Item -Recurse path\to\this-repo\skills\* .agents\skills\

cp path/to/this-repo/adapters/openclaw/AGENTS.md ./AGENTS.md
mkdir -p .agents/skills
cp -r path/to/this-repo/skills/* .agents/skills/

Copy-Item path\to\this-repo\adapters\openclaw\AGENTS.md .\AGENTS.md
New-Item -ItemType Directory -Force -Path .agents\skills
Copy-Item -Recurse path\to\this-repo\skills\* .agents\skills\

cp path/to/this-repo/adapters/cline/.clinerules ./.clinerules

Copy-Item path\to\this-repo\adapters\cline\.clinerules .\.clinerules

# Package all skills as zip files for upload to your Agent Space
./install.sh ~/output-dir --tool devops-agent
# Then upload each .zip from ~/output-dir/devops-agent-skills/ via the Operator Web App

# Package all skills as zip files for upload to your Agent Space
.\install.ps1 -TargetDir C:\output-dir -Tool devops-agent
# Then upload each .zip from C:\output-dir\devops-agent-skills\ via the Operator Web App

⚙️ How it works

graph LR
    S[skills/] --> A[adapters/]
    ST[steering/] --> A
    A --> K[Kiro]
    A --> CC[Claude Code]
    A --> CU[Cursor]
    A --> CO[Codex]
    A --> W[Windsurf]
    A --> GH[GitHub Copilot]
    A --> G[Gemini CLI]
    A --> AG[Antigravity]
    A --> J[Junie]
    A --> AM[Amp]
    A --> OC[OpenClaw]
    A --> CL[Cline]
    A --> DA[DevOps Agent<br/>generic skills]
    A --> DAR[DevOps Agent<br/>wa-review autonomous]

Tool compatibility matrix

🤖 Agent runtime effectiveness

Skills work across all supported runtimes, but effectiveness varies by runtime architecture — specifically whether the runtime supports parallel subagent dispatch (the mechanism wa-review's full-review path uses to achieve 100% BP coverage).

The table below summarises measured results. The "Full review" path dispatches 6 parallel Task subagents; runtimes without this capability run sequentially.

📋 Skills overview

Pillar aliases (route to wa-review with pillar scope):

📊 Reference data and token consumption

The wa-review skill includes 307 best practices across 57 framework questions plus 27 lens extensions — sourced directly from the AWS Well-Architected public documentation. This reference data lives in skills/wa-review/references/ and is loaded one pillar file at a time (via parallel Task subagents in v4.2+), not all at once.

Reference data summary

Token strategies

A full review loads all 6 pillar files (~500K–600K input tokens of reference material). Most single-context models have limits below that, which is why v4.2+ dispatches one Task subagent per pillar — each subagent loads only its own pillar file (~150–580 KB), so no single context holds the whole corpus. Alternative modes for smaller footprints:

Estimated costs

Token estimates assume ~4 characters per token. Costs use Claude Opus 4 pricing ($15/M input, $75/M output) as a reference — actual costs vary by model, provider, and whether you use caching. Pricing checked June 2026; verify current rates at the link above.

Total cost includes output tokens (the report itself, typically 8K–30K tokens depending on findings).

Cost-saving tips:

• Use the two-pass approach (default) — only loads files for questions with gaps
• Scope to specific pillars — e.g., "review security only" loads ~10 files instead of 57
• Use a smaller model for Pass 1 (quick scan) and a stronger model for Pass 2 (deep dive)
• Enable prompt caching if your provider supports it — the reference files are static and cache well

Regenerating reference data

The reference files are committed to this repo as a snapshot of the AWS Well-Architected public docs at the time of the last crawl. You are responsible for checking whether the data needs updating before use — AWS updates the framework and lens pages over time, and stale references can produce outdated guidance. If in doubt, compare a few BP pages against the live AWS docs or re-run the crawler. To refresh:

# Regenerate all 6 pillar-merged framework files
uv run scripts/crawl-wa-framework.py

# Regenerate a single pillar
uv run scripts/crawl-wa-framework.py --pillar security

# Add or refresh a lens
uv run scripts/crawl-wa-framework.py --lens https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/welcome.html

# Lenses that use the dotted best-practice ID format (e.g. DevOps Guidance)
uv run scripts/crawl-wa-framework.py --lens https://docs.aws.amazon.com/wellarchitected/latest/devops-guidance/devops-guidance.html --lens-name devops-guidance

Data strategy — why static pillar files, not MCP

The reference corpus lives in skills/wa-review/references/pillars/*.md as 6 pre-crawled markdown files, not as an MCP retrieval server. This is a deliberate choice backed by measurement, not convention. The trade-offs:

Static pillar files (what this repo ships):

• One file load per subagent. wa-review's full-review dispatches 6 parallel Task subagents; each subagent loads exactly one pillar file and holds the entire pillar (30–55 BPs) in a single context window. Zero back-and-forth.
• Snapshot in time. The files are a snapshot of the AWS Well-Architected docs at the last crawl. Users must check freshness before use (see the regeneration section above). This is honest — we can't lie about live data if we hold static data.
• Predictable token cost. Loading a pillar file is a one-shot input-token charge (~50–150K tokens per subagent, cache-friendly since the corpus is static). Total review cost stays deterministic per invocation.
• No infrastructure to run. No MCP server, no auth, no availability concerns. The skill works offline once installed.

Why not MCP retrieval per BP?

MCP servers do incremental retrieval — the agent asks "give me guidance for SEC03-BP02," gets a chunk, decides what to look up next, and iterates. That model has real drawbacks for this workload:

• Turn explosion. Full-review coverage needs 307 BPs evaluated. If retrieval is one BP per call, the agent spends 300+ tool-use turns on retrieval alone — before it's written a single finding.
• Empirical plateau. In our exhaustive study of retrieval strategies, models that had to iteratively fetch citations reliably plateaued at 20–60 BPs cited before stopping. This wasn't a prompt problem — no amount of "evaluate all 307" pressure changed the behavior. Once the agent has enough material to write some findings, it converges on writing them.
• Token overhead. Each MCP call carries protocol overhead, tool-use framing, and the accumulated agent context. Pre-loading one pillar file per subagent uses 30–50% fewer input tokens than the same content retrieved incrementally, because the pillar file amortizes the framing cost once.
• Cache-unfriendly. MCP responses vary by query; static pillar files are byte-identical across runs and cache perfectly.

The pillar-merged shape specifically (not 57 per-question files) — this was also measured. Per-question files force the agent to navigate 57 file names to figure out what to read; pillar-merged files map 1:1 to the subagent dispatch pattern, and the subagent sees the pillar as a coherent whole. The pillar-file layout was validated in the subagent-coverage empirical study.

When to use each review mode (CI/CD guidance)

Full-review mode (v2.2) achieves recall = 1.00 with F1 ≈ 0.96, but at ~$7 per invocation and ~11 min wall clock. That's designed for one-shot architecture assessments — the kind of review that would take a human reviewer half a day. Not designed for per-commit CI checks.

For CI/CD workflows, reach for lighter modes:

Practical guidance:

• PR gates: Score or pillar-scoped for the pillar most affected by the change (e.g. IaC change → REL + SEC scope, not full review). Wall clock stays under 5 min so PR feedback loops don't stall.
• Weekly / monthly audits: Full review is appropriate. Cost amortizes over the audit cycle.
• Deployment gates: Score mode filtered to Critical/High severity — fast, actionable, doesn't block on Medium/Low findings.
• Human review supplement: Full review before a human WA session; the ledger becomes the reviewer's checklist. Human catches nuance; the skill catches nothing missed.

✅ Verifying it works

Ask your AI coding agent:

What Well-Architected pillars should I consider for this architecture?

If configured correctly, it will reference all six pillars with specific guidance rather than giving a generic answer.

🧪 Evaluating skills

Each skill includes structured evaluations in skills/*/evals/evals.json following the Agent Skills eval spec. Evals let you measure whether the skills produce better outputs than a bare agent.

Each test case includes:

• A realistic user prompt
• Expected output description
• 5-7 concrete assertions (gradable as PASS/FAIL)

Automated eval runner

The evals/ directory contains an automated evaluation runner powered by Amazon Bedrock.

Prerequisites:

• Python 3.13+ and uv
• AWS credentials configured with Bedrock access (aws configure or SSO)
• Bedrock model access enabled for the models in evals/config.yaml (Claude Opus 4.8 by default) in your region

Setup:

Run evaluations:

macOS / Linux / Windows (PowerShell):

# List available skills
uv run python run.py --list

# Evaluate a single skill
uv run python run.py --skill wa-review --verbose

# Evaluate all skills with parallel case execution
uv run python run.py --parallel --verbose

# Save results for historical tracking
uv run python run.py --parallel --save

How it works:

1. For each test case, generates two responses via Bedrock Converse API:
   • Baseline — prompt only, no skill context
   • With skill — prompt + SKILL.md injected as system context
2. An LLM-as-judge grades each assertion as PASS/FAIL against both outputs
3. Reports a score comparison showing the skill's impact

Configuration (evals/config.yaml):

provider: bedrock
region: us-east-1
generation_model: us.anthropic.claude-opus-4-8
grading_model: us.anthropic.claude-opus-4-8
max_tokens: 16384

Estimated cost per run:

Cost breakdown assumes ~1K input tokens and ~8K output tokens per generation call (16k max), and ~9K input / ~500 output per grading call. Actual cost depends on response length and Bedrock pricing in your region. Use --parallel for ~3x faster wall-clock time. You can use cheaper models (Sonnet, Haiku) by updating config.yaml.

Using this framework for your own skills

The evals/ runner is skill-agnostic — it reads skills/{name}/SKILL.md and skills/{name}/evals/evals.json from wherever you point it. To evaluate a skill you're developing:

1. Drop your skill directory under skills/ (or fork this repo and add it there).
2. Author an evals.json with 3–7 realistic prompts and PASS/FAIL assertions per case (spec).
3. Run uv run python run.py --skill your-skill --verbose.
4. Iterate on SKILL.md until the with-skill score meaningfully beats baseline.

The paired-comparison approach (with skill vs bare model, same prompts) is the fair way to measure whether SKILL.md content is actually earning the tokens it costs. If your skill's delta is <10%, the guidance is probably too generic to move the model — worth revisiting.

📈 Effectiveness

Two frameworks measure different kinds of skills. Both compare with-skill against a matched baseline; the metric differs by framework:

† wa-review is measured in the real Agents CLI runtime because its full-review path depends on the Task tool (6 parallel pillar subagents per review, v4.2+). Raw Bedrock Converse has no Task tool, so it can't execute the skill's subagent-dispatch pattern; scoring wa-review there produces misleading numbers. See Real Agent evaluation below for the measurement setup, and evals/cli_effectiveness/ for the harness code + ground truth to reproduce.

Real agent evaluation

To measure what the skill actually delivers in production, we run it inside real agent runtimes against 6 eval cases × 3 runs each, scored against a ground truth built from a 2-model × 5-run consensus panel (270–306 applicable BPs per case).

Results by runtime (wa-review v2.2, Opus-tier models, 18 runs per runtime):

† Case 4 is a pillar-scoped test ("Review only Security and Reliability"). Scored against the SEC + REL subset of the ground truth (116 of 280 BPs).

Takeaways:

• Skill vs baseline: +0.70 F1 — without the skill, agents cite ~15% of applicable BPs regardless of runtime. With it, parallel-dispatch runtimes reach 100% recall deterministically.
• Claude Code and Kiro: identical results — same model (claude-opus-4.6), same F1, zero variance. The skill's architecture determines effectiveness, not which runtime runs it.
• Codex (GPT-5.5): mean F1 0.684, high variance (stdev up to 0.28). Pillar-scoped mode significantly improves Codex — Case 4 averaged 0.902, near-parity with parallel runtimes. One Codex run hit F1 = 0.998 (Case 2), confirming full coverage is possible but non-deterministic on sequential runtimes.
• Cost: Claude Code/Kiro ~$7/run at Opus tier; Codex ~$5–12/run at GPT-5.5 tier (token usage varies 270K–835K). Baseline (no skill) ~$0.10/run.

Other modes (score / quick / pillar-scoped) work in raw Converse and improve output there (case-level scores 80–100%). Skills never produce catastrophically worse output than baseline.

The evaluation framework is included in evals/ so you can reproduce results on your own models and prompts. Use --parallel for ~3x faster runs.

🏎️ Model Benchmark

Compare how different foundation models perform on Well-Architected review tasks — measuring quality, latency, throughput, and token cost side by side. All models are consumed through Amazon Bedrock (bedrock-runtime for Converse API models, bedrock-mantle for OpenAI Responses/Chat Completions API models) — no direct provider APIs used.

The benchmark below measures subagent-mode full reviews — the shipped skill's default path for wa-review full reviews, which dispatches 6 parallel Converse calls (one per pillar) per model with pre-loaded pillar references. This is what real users experience. Cost figures include all 6 subagent calls per review.

Model Benchmark Results

Last run: 2026-07-11T00:24:45Z | Region: us-east-1 | Prompt: 1,595 chars | Max tokens: 4,096

Run it yourself:

cd evals
uv sync

# Quick run (no grading) — just latency and token counts
uv run python benchmark.py

# Full run with quality grading
uv run python benchmark.py --grade

# Test specific models
uv run python benchmark.py --models us.anthropic.claude-sonnet-5 us.amazon.nova-pro-v1:0

# Publish results to this README
uv run python benchmark_report.py results/benchmark-YYYYMMDD-HHMMSS.json --update-readme

Configure models and prompts in evals/benchmark_config.yaml. Add new models as they become available in Bedrock and re-run to keep the table current.

AWS DevOps Agent

The AWS DevOps Agent operates differently from coding agents — it runs autonomously in response to incidents and operational events, not developer prompts. wa-review ships a dedicated variant that fits this model.

Key differences in SKILL-devops-agent.md:

• Triggers on post-incident root cause analysis and explicit on-demand requests — not on generic "WA review" phrases
• Workload discovery derives context from the incident ticket, investigation findings, metrics, logs, and source code already accessed — never asks the user
• No interactive checkpoints — the ---STOP--- confirmation blocks are replaced with non-blocking progress notes
• Post-incident framing — connects WA findings to the incident timeline, elevates severity for proven failure modes, leads the Executive Summary with the incident trigger
• On-premises support — when no IaC exists, uses metrics, logs, and source code as evidence
• Agent type targeting — INCIDENT_RCA + ON_DEMAND instead of GENERIC

To upload to your Agent Space:

# Generate a DevOps Agent-compatible zip for wa-review (16 files, <1 MB)
zip wa-review-devops-agent.zip \
  skills/wa-review/SKILL-devops-agent.md \
  skills/wa-review/metadata-devops-agent.json \
  skills/wa-review/references/manifest.md \
  skills/wa-review/references/pillars/*.md \
  skills/wa-review/references/pillar-playbooks/*.md
# Then upload via the Operator Web App

🤝 Contributing

We welcome contributions from the community! See CONTRIBUTING.md for guidelines on adding skills, modifying steering files, or adding new tool adapters.

🔒 Security

See CONTRIBUTING for more information.

📄 License

This project is licensed under the MIT-0 License.

📚 Related Resources

• AWS Well-Architected Framework
• Kiro — AI-powered IDE
• AWS DevOps Agent
• Agent Skills Specification
• skills.sh — Skills directory for AI agents