Well-Architected Skills and Steering for AI Coding Agents

AWS has released an open-source project that embeds Well-Architected Framework best practices directly into AI coding agents across 12 development tools including Claude Code, Cursor, and GitHub Copilot. The project provides reusable skills and steering files that run locally without AWS credentials, enabling continuous architecture guidance during code writing rather than separate review gates. The initiative aims to reduce rework by catching misalignments early, as developers increasingly rely on AI assistants instead of consulting documentation.

Reusable skills and steering that teach AI coding agents how to apply the AWS Well-Architected Framework https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html . One set of playbooks, 12 supported tools . Kiro · Claude Code · Cursor · Codex · Windsurf · GitHub Copilot · Gemini CLI · Antigravity · Junie · Amp · 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. 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 https://agentskills.io/ 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 install.sh One-command setup macOS/Linux install.ps1 One-command setup Windows PowerShell Install for a specific tool ./install.sh ~/my-project --tool claude-code ./install.sh ~/my-project --tool cursor ./install.sh ~/my-project --tool kiro 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 Run ./install.sh --help for full usage. Windows PowerShell : .\install.ps1 -TargetDir C:\Projects\my-app -Tool claude-code .\install.ps1 -Tool all -Force 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. 🔹 Kiro 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/ 🔹 Claude Code cp path/to/this-repo/adapters/claude-code/CLAUDE.md ./CLAUDE.md cp -r path/to/this-repo/adapters/claude-code/commands .claude/commands 🔹 Cursor cp -r path/to/this-repo/adapters/cursor/rules .cursor/rules 🔹 Codex OpenAI cp path/to/this-repo/adapters/codex/AGENTS.md ./AGENTS.md cp -r path/to/this-repo/skills ./skills 🔹 Windsurf cp path/to/this-repo/adapters/windsurf/.windsurfrules ./.windsurfrules 🔹 GitHub Copilot mkdir -p .github cp path/to/this-repo/adapters/github-copilot/.github/copilot-instructions.md .github/ 🔹 Gemini CLI cp path/to/this-repo/adapters/gemini-cli/GEMINI.md ./GEMINI.md cp -r path/to/this-repo/skills ./skills 🔹 Antigravity 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 🔹 Junie JetBrains 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/ 🔹 Amp cp path/to/this-repo/adapters/amp/AGENTS.md ./AGENTS.md mkdir -p .agents/skills cp -r path/to/this-repo/skills/ .agents/skills/ 🔹 Cline cp path/to/this-repo/adapters/cline/.clinerules ./.clinerules 🔹 AWS DevOps Agent 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 php 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 | 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. | Adapters adapters/ | Translate steering into each tool's native config format and wire up skills as commands or rules. | Assets assets/ | Shared reference material v13 best practices, metrics, patterns bundled with skills for tools that support it. | | 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 | | AWS DevOps Agent | N/A skills are self-contained | SKILL.md zip upload to Agent Space | | 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-audit | 💰 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 | 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. We welcome contributions from the community and internal teams alike See CONTRIBUTING.md /aws-samples/sample-well-architected-skills-and-steering/blob/main/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. See CONTRIBUTING /aws-samples/sample-well-architected-skills-and-steering/blob/main/CONTRIBUTING.md security-issue-notifications for more information. This project is licensed under the MIT-0 License /aws-samples/sample-well-architected-skills-and-steering/blob/main/LICENSE .