aws-samples/sample-well-architected-skills-and-ste: reusable skills and steering that teach AI coding

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

[!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 12 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

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-audit/            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
  v13/                                307 WA Framework best practices (by ID)
  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
  devops-agent/                       Packaging for AWS DevOps Agent

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)

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

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\

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/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 --> CL[Cline]
    A --> DA[DevOps Agent]

Tool compatibility matrix

📋 Skills overview

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

cd evals
uv sync

Run evaluations:

macOS / Linux:

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

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

# Evaluate all skills
uv run python run.py

# Verbose output (shows per-assertion grades)
uv run python run.py --skill security-assessment --verbose

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

Windows (PowerShell):

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

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

# Evaluate all skills
uv run python run.py

# Verbose output (shows per-assertion grades)
uv run python run.py --skill security-assessment --verbose

# Save results for historical tracking
uv run python run.py --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:

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-sonnet-4-5-20250929-v1:0
grading_model: us.anthropic.claude-haiku-4-5-20251001-v1:0

Estimated cost per run:

Cost breakdown assumes ~1K input tokens and ~2K output tokens per generation call, and ~3K input / ~500 output per grading call. Actual cost depends on response length and Bedrock pricing in your region. The max_cost_usd setting in config.yaml acts as a soft budget guard.

[!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 Sonnet/Haiku) for reliable assertion grading.

[!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.

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

🔒 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