Reusable skills and steering that teach AI coding agents how to apply the AWS Well-Architected Framework. One set of playbooks, 15 supported tools.
$ npx -y skills add aws-samples/sample-well-architected-skills-and-steering --agent claude-code
Repo: 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, 15 supported tools.
Kiro · Kiro CLI · Claude Code · Cursor · Codex · Windsurf · GitHub Copilot · Gemini CLI · Antigravity · Junie · Amp · OpenClaw · Cline · Cortex Code · AWS DevOps Agent
[!IMPORTANT] This sample is provided for educational and demonstrative purposes. It is not intended for production use without additional review and testing appropriate to your environment. Reference content is current as of the download date — keeping it up to date is the responsibility of the user.
[!NOTE] Deprecated. AWS now ships an actively maintained equivalent — the
aws-well-architected-reviewskill in Agent Toolkit for AWS (product page). New feature/skill contributions to this repo are no longer accepted. This repository remains the portable contract, fixture, and regression source — see SUCCESSOR_HANDOFF.md and issue #147 for the full migration plan.
aws-well-architected-review in Agent Toolkit for AWSNew users should install from Agent Toolkit for AWS directly rather than from this repo. The skill ships as part of the aws-core plugin, at skills/core-skills/aws-well-architected-review — it fetches Well-Architected Framework and Lens content live from AWS documentation at review time, rather than a periodically-crawled snapshot.
Claude Code, Codex, or Cursor (plugin install — bundles the AWS MCP Server too):
# Claude Code (plugins are on the official Anthropic marketplace by default)
/plugin install aws-core@claude-plugins-official
# Codex
codex plugin marketplace add aws/agent-toolkit-for-aws
# then in Codex: /plugins, and install aws-core
For Cursor: Settings → Plugins → Team Marketplaces → Add Marketplace → Import from Repo, pointing at aws/agent-toolkit-for-aws, then install aws-core from the Plugins panel.
Kiro, fx, or any other agent (skill only, no plugin marketplace):
npx skills add aws/agent-toolkit-for-aws/skills
This installs the full Agent Toolkit skill set, including aws-well-architected-review. Browse skills/ in that repo to install selectively. Kiro discovers installed skills automatically; fx also picks up skills already installed under .agents/skills/, .claude/skills/, or .codex/skills/.
Once installed, use it the same way you'd request any Well-Architected review — describe the workload and ask for a review; the agent discovers and loads the skill on demand. Prerequisites and full setup (including the optional AWS MCP Server for live AWS API access) are in the Agent Toolkit for AWS user guide.
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:
evals/ are the exception; they call models and need credentials)steering/ Always-on context (Kiro)
well-architected.md Pillars, design principles, review process
aws-well-architected-framework-review.md Deep multi-step WA review (evidence-based, constrained)
skills/ Step-by-step playbooks (tool-agnostic)
aws-well-architected-framework-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
schemas/ Structured output contracts
aws-well-architected-framework-review-v1.schema.json Versioned JSON Schema for aws-well-architected-framework-review.json
README.md Contract, versioning policy, guarantees
tools/ Standalone tooling (stdlib Python, no AWS)
wa-ci/ Gate a PR on the Well-Architected delta
wa_ci.py Diff a review vs a baseline, classify, gate
examples/ Baseline + review + GitHub Actions workflow
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
aws-well-architected-framework-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
pricing.local.yaml.example Template for your own per-token rates (rates not tracked)
pyproject.toml Dependencies (use uv sync)
plugin.json Agent Plugins 1.0.0 manifest (portable plugin package)
install.sh One-command setup (macOS/Linux)
install.ps1 One-command setup (Windows PowerShell)
The 27 lenses under references/lenses/ ship in two layouts, mirroring how AWS
publishes each lens. Both are intentional and the crawler handles both:
government/, migration/) — one file
per pillar, named for the pillar (security.md, cost-optimization.md).iot/, telco/) — one file per
best practice, named for its BP ID (IOTCOST01.md, TELCOOPS02.md).Pillar-lookup contract: a lens file's pillar is given by its **Pillar**:
header. Every pillar-organized lens file carries this field in both layouts, so
consumers walking the reference tree can read the pillar the same way regardless
of a lens's source shape. (Lenses that AWS does not organize by the 6 pillars —
e.g. responsible-ai, devops-guidance — omit the field.) Filenames remain a
secondary signal but are no longer required to derive the pillar.
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 aws-well-architected-framework-review
# Install globally (user-level, applies to all projects)
npx skills add aws-samples/sample-well-architected-skills-and-steering -g
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
This repo is a conformant Agent Plugins 1.0.0 package: the root plugin.json manifest wraps the skills/ core (each skills/*/SKILL.md already carries valid Agent Skills frontmatter) into a single portable plugin. Clients that ship a native Agent Plugins loader can install directly from the repository:
# Point your Agent Plugins-compatible client at the repository
https://github.com/aws-samples/sample-well-architected-skills-and-steering
This path is additive and does not replace the adapters or install scripts. The plugin is intentionally MCP-free (mcp.json is optional in the spec) because the skills read static pillar files rather than calling a server. Kiro-specific behavior (powers/ and the Kiro agent config) is homed under the extensions["dev.kiro"] namespace, keeping the portable core clean. Tool-specific steering and rules translations (.cursor/rules/, .windsurfrules, CLAUDE.md, .clinerules, GEMINI.md, Copilot instructions) remain in adapters/, since they target formats outside the Agent Plugins ecosystem.
macOS / Linux:
View @aws-samples’s profileA library of healthcare and life sciences domain capabilities — reference agents with best practices, reusable skills, and MCP-based tools — serving builders in their IDEs, researchers in Amazon Quick, and developers deploying to AWS.
@aws-samplessample-well-architected-skills-and-steering is a Claude Code plugin with 6 hand-picked skills, indexed on Flowy in the Cloud & Infrastructure category. Install it with the command on its page. It includes aws-well-architected-framework-review, example-skill, migration-readiness. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it