Reusable skills and steering that teach AI coding agents how to apply the AWS Well-Architected Framework. 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
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.sh ~/my-project --tool claude-code
./install.sh ~/my-project --tool cursor
./install.sh ~/my-project --tool kiro
./install.sh ~/my-project --tool kiro --tool claude-code --tool cursor
./install.sh ~/my-project --tool all
./install.sh ~/my-project --tool claude-code --symlink
./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
./install.sh ~/output-dir --tool devops-agent
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 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 for more information.
This project is licensed under the MIT-0 License.