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, 13 supported tools.

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

Kiro · Claude Code · Cursor · Codex · Windsurf · GitHub Copilot · Gemini CLI · Antigravity · Junie · Amp · OpenClaw · Cline · 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.

🎯 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 13 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 review across all 6 pillars
  security-assessment/                IAM, detection, data protection, incident response
  reliability-improvement-plan/       SPOFs, recovery, scaling, change management
  cost-optimization-review/            Waste, right-sizing, pricing models
  performance-efficiency/             Resource selection, scaling, caching
  sustainability-optimization/        Utilization, managed services, data lifecycle
  operational-excellence/             CI/CD, observability, incidents, automation
  migration-readiness/                7 Rs assessment with migration plan
  architecture-decision-record/       WA-aligned ADRs with pillar impact

assets/                             Shared reference material
  well-architected-best-practices.md  Per-pillar investigation checklists
  cloudwatch-metrics-reference.md     Metric thresholds + composite alarm patterns
  incident-investigation-patterns.md  Triage, RCA, mitigation playbooks
  skill-authoring-guide.md            DevOps Agent skill authoring guide

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
  devops-agent/                       Packaging for AWS DevOps Agent

powers/                             Kiro Powers (coming soon)

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
  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

Tip

Use --symlink (bash) or -Symlink (PowerShell) to create symbolic links instead of copies. When this repo updates, your project gets the changes automatically without reinstalling. On Windows, symlinks require elevated permissions.

Note

Global installs place files in your home directory (~/CLAUDE.md, ~/.kiro/, ~/.cursor/, etc.) and apply to all projects without their own config. Use project-level installation (the default) if you only want WA guidance for specific projects.

Existing files — the installer prompts before overwriting. Use --force to skip confirmation.

Manual installation

🔹 Kiro

macOS / Linux:

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/

Windows (PowerShell):

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\

🔹 Claude Code

macOS / Linux:

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

Windows (PowerShell):

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

🔹 Cursor

macOS / Linux:

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

Windows (PowerShell):

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

🔹 Codex (OpenAI)

macOS / Linux:

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

Windows (PowerShell):

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

🔹 Windsurf

macOS / Linux:

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

Windows (PowerShell):

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

🔹 GitHub Copilot

macOS / Linux:

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

Windows (PowerShell):

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

🔹 Gemini CLI

macOS / Linux:

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

Windows (PowerShell):

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

🔹 Antigravity

macOS / Linux:

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

Windows (PowerShell):

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"
}

🔹 Junie (JetBrains)

macOS / Linux:

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/

Windows (PowerShell):

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\

🔹 Amp

macOS / Linux:

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

Windows (PowerShell):

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\

🔹 OpenClaw

macOS / Linux:

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

Windows (PowerShell):

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\

🔹 Cline

macOS / Linux:

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

Windows (PowerShell):

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

🔹 AWS DevOps Agent

macOS / Linux:

# 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

Windows (PowerShell):

# 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]

Component	What it does
Skills (`skills/*/SKILL.md`)	Self-contained, tool-agnostic playbooks. Any AI agent can follow them step-by-step. They don't depend on steering or on each other.
Steering (`steering/*.md`)	Always-on context loaded into every Kiro conversation. Other tools use equivalent mechanisms via adapters.
Powers (`powers/*/`)	Bundled, installable units for Kiro. Package steering + MCP tools + hooks into a single activatable power.
Adapters (`adapters/`)	Translate steering into each tool's native config format and wire up skills as commands or rules.
Assets (`assets/`)	Shared reference material (metrics, patterns, best practices) bundled with skills for tools that support it.

Tool compatibility matrix

Tool	Steering mechanism	Skills mechanism
Kiro	`.kiro/steering/*.md`	`.kiro/skills/*/SKILL.md`
Claude Code	`CLAUDE.md`	`.claude/commands/*.md` (slash commands)
Cursor	`.cursor/rules/*.md`	Rules with conditional activation
Codex	`AGENTS.md`	References `skills/` directory
Windsurf	`.windsurfrules`	References `skills/` directory
GitHub Copilot	`.github/copilot-instructions.md`	Inline (no separate skill mechanism)
Cline	`.clinerules`	References `skills/` directory
Gemini CLI	`GEMINI.md`	References `skills/` directory
Antigravity	`.agents/rules/*.md`	`.agents/skills/*/SKILL.md`
Junie	`.junie/guidelines/*.md`	`.junie/skills/*/SKILL.md`
Amp	`AGENTS.md`	`.agents/skills/*/SKILL.md`
OpenClaw	`AGENTS.md`	`.agents/skills/*/SKILL.md`
AWS DevOps Agent	N/A (skills are self-contained)	`SKILL.md` zip upload to Agent Space

📋 Skills overview

Skill	Pillar(s)	Use when you need to...
`wa-review`	All 6	Run a full Well-Architected review
`security-assessment`	🔒 Security	Assess IAM, detection, data protection, incident response
`reliability-improvement-plan`	🔄 Reliability	Find and eliminate single points of failure
`cost-optimization-review`	💰 Cost Optimization	Identify waste and right-sizing opportunities
`performance-efficiency`	⚡ Performance Efficiency	Evaluate resource selection, scaling, and caching
`sustainability-optimization`	🌱 Sustainability	Reduce carbon footprint and resource waste
`operational-excellence`	🛠️ Operational Excellence	Assess CI/CD, observability, incident management
`migration-readiness`	All 6	Assess readiness to migrate a workload to AWS
`architecture-decision-record`	All 6	Document a design decision with WA pillar impact

✅ 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.

Tip

Claude Code users: try /wa-review to invoke the full review skill as a slash command.

Kiro users: the steering loads automatically — just start discussing architecture and the agent applies WA principles.

🧪 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 Claude Sonnet and Haiku 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

Note

On Windows, ensure your AWS credentials are configured via aws configure or environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN). If using AWS IAM Identity Center (SSO), run aws sso login --profile your-profile first.

How it works:

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
An LLM-as-judge grades each assertion as PASS/FAIL against both outputs
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:

Scope	Generation calls	Grading calls	Estimated cost
Single skill (3 cases)	6 (Opus)	6 (Opus)	~$1.50 – $2.50
All 9 skills (27 cases)	54 (Opus)	54 (Opus)	~$12 – $20

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.

Tip

Experiment with other models! The eval runner works with any model available in Bedrock — try Amazon Nova, Meta Llama, Mistral, or others to see how different foundation models respond to skill guidance. Use the discovery utility to see what's available in your region:

uv run python list_models.py

Then update generation_model in config.yaml to try a different model. The grading model should remain a strong model (Claude Opus/Sonnet) for reliable assertion grading. Note: Opus 4.8 does not support the temperature parameter — the runner handles this automatically.

Tip

Start by running a single skill eval (--skill wa-review --verbose) to see detailed per-assertion grading. The delta between baseline and with-skill scores quantifies the value each skill adds.

📈 Effectiveness

All skills are evaluated using an automated LLM-as-judge framework with paired comparison (same prompt, with and without skill context). Results with Claude Opus 4.8 (generation and grading), 16k token output:

Skill	Baseline	With Skill	Delta
`wa-review`	82%	100%	+18%
`architecture-decision-record`	81%	100%	+19%
`cost-optimization-review`	93%	100%	+7%
`migration-readiness`	85%	100%	+15%
`operational-excellence`	90%	100%	+10%
`performance-efficiency`	90%	100%	+10%
`reliability-improvement-plan`	95%	100%	+5%
`security-assessment`	94%	100%	+6%
`sustainability-optimization`	85%	100%	+15%
Average	88%	100%	+12%

All 9 skills score 100% on behavioral assertions with skill context loaded
Average +12% improvement over the same model without skill guidance
Skills never produce worse output than baseline — they improve or match

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

🤝 Contributing

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

Note

This is a community-driven project. Anyone can collaborate and improve the skills and steering docs through Pull Requests. Adapt them to your domain, add new patterns, and share back.

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, 13 supported tools.

🎯 Why this exists

📦 What's inside

🚀 Quick start

One-liner (no clone needed)

Via skills.sh

Via bootstrap script

Install script (from local clone)

Manual installation

⚙️ How it works

Tool compatibility matrix

📋 Skills overview

✅ Verifying it works

🧪 Evaluating skills

Automated eval runner

📈 Effectiveness

🤝 Contributing

🔒 Security

📄 License

📚 Related Resources