Well-Architected Skills & Steering for AI Coding Agents

Reusable skills and steering that teach AI coding agents how to apply the AWS Well-Architected Framework. Works with Kiro, Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and Cline.

⚠️ 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.

What's inside

steering/                           Steering (Kiro) — always-on context
  well-architected.md                 WA Framework pillars, design principles, review process

skills/                             Skills — standalone step-by-step playbooks (tool-agnostic)
  wa-review/                          Full Well-Architected review across all 6 pillars
  reliability-improvement-plan/       Identify SPOFs and produce a reliability remediation plan
  security-assessment/                Deep-dive security posture assessment
  cost-optimization-audit/            Find waste, right-sizing, pricing model improvements
  performance-efficiency/             Resource selection, scaling, caching, optimization
  sustainability-optimization/        Carbon footprint reduction via utilization and architecture
  migration-readiness/                7 Rs assessment with migration plan
  operational-excellence/              CI/CD, observability, incident mgmt, operational maturity
  architecture-decision-record/       WA-aligned ADRs with pillar impact analysis

assets/                             Shared reference material (WA best practices, metrics, patterns)
  v13/                                Well-Architected Framework v13 best practices by ID
  well-architected-best-practices.md  Per-pillar best practices with investigation checklists
  cloudwatch-metrics-reference.md     Metric thresholds by service + composite alarm patterns
  incident-investigation-patterns.md  Triage, RCA, mitigation playbooks, post-mortem template
  skill-authoring-guide.md            Guide for writing effective DevOps Agent skills

adapters/                           Tool-specific config files
  claude-code/                        CLAUDE.md + .claude/commands/*.md
  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
  devops-agent/                       Assets + packaging for AWS DevOps Agent

install.sh                          Setup script for any tool

Quick start

Install script (recommended)

# 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
./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.

Note on --global: Global installation places configuration files directly in your home directory (e.g., ~/CLAUDE.md, ~/AGENTS.md, ~/.clinerules, ~/.windsurfrules) or in global tool-specific directories (e.g., ~/.kiro/, ~/.claude/, ~/.cursor/). These files apply to all projects that don't have their own project-level configuration. Use project-level installation (the default) if you only want Well-Architected guidance for specific projects.

Note on existing files: The installer will prompt before overwriting any existing files. Use --force to skip the prompt and overwrite without confirmation.

Manual installation

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/

Cline

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

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

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

How it works

Skills (skills/*/SKILL.md) are self-contained, tool-agnostic playbooks. Any AI coding agent can follow them step-by-step. They don't depend on steering or on each other.

Steering (steering/*.md) is Kiro-specific always-on context loaded into every conversation. Other tools use equivalent mechanisms (see adapters).

Adapters (adapters/) translate the steering into each tool's native config format and wire up skills as commands or rules.

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. For Claude Code, try /wa-review to invoke the full review skill.

Security

See CONTRIBUTING for more information.

Contributing

See CONTRIBUTING.md for guidelines on adding skills or modifying steering files.

License

This project is licensed under the MIT-0 License.

Related Resources

• AWS Well-Architected Framework
• AWS Well-Architected Tool
• Kiro — AI-powered IDE
• AWS DevOps Agent