$ show aws-samples/sample-well-architected-skills-and-steering
This repository is a comprehensive, tool-agnostic skills and steering pack that teaches AI coding agents to perform AWS Well-Architected Framework reviews. It contains a curated reference corpus of over 2,000 markdown files (6 pillars, 307 best practices, 27 industry lenses) derived from official AWS documentation, plus per-tool adapters for 15 AI coding assistants (Claude Code, Cursor, Codex, GitHub Copilot, etc.). The repo also ships production-grade supporting tooling: a CI gating tool (wa-ci) that diffs structured review JSON against a baseline and blocks PRs on regressed gaps; an evaluation harness with blind multi-reviewer adversarial adjudication; a crawler to regenerate the reference corpus from AWS docs; and one-command installers. The core skill dispatches six parallel subagents (one per pillar) to keep the 2.2 MB corpus out of any single context window. Despite the extensive content, the repository has notable maintenance challenges: the reference snapshot will drift as AWS documentation evolves (users are responsible for regeneration); lens files are duplicated across `powers/` and `skills/` directories creating a sync hazard; and the flagship skill is explicitly deprecated in favor of a successor in Agent Toolkit for AWS. The evaluation harnesses and CI tooling are well-crafted and reusable, but the sheer scale of markdown files and platform-specific adapters makes ongoing synchronization complex.
The LLM identified 4 files worth highlighting for reuse:
A production-grade crawler that scrapes AWS Well-Architected documentation from docs.aws.amazon.com, handles three content modes (BP-style, Dotted-BP-style, Topic-page-style), converts HTML to clean markdown, and outputs per-question reference files. Supports --pillar, --lens, --dry-run flags. The HTML-to-markdown conversion pipeline (`html_to_markdown`, `extract_content`, `strip_tags`) and TOC parsing logic (`discover_bp_pages`, etc.) are reusable for any AWS documentation scraping task.
A stdlib-only CLI tool that diffs a structured Well-Architected review JSON against a committed baseline, classifying findings as Resolved, Still-open, New, or Regressed. Treats `cannot_determine` as neither pass nor gap, and fails closed: any new or regressed gap without severity always blocks the PR. The diff logic is clean, parameterized, and could be extracted to gate any structured audit output.
A sophisticated evaluation harness that uses two independent reviewer models (different families) and a third-family adversary to assess evidence, status, severity, recommendations, and uncertainty in Well-Architected reviews. Computes candidate overturn rate, Cohen's kappa agreement, uncertainty-handling rate, and unsupported-assertion detection. The blind prompt pattern, evidence catalog system, and provenance-validated scoring are reusable for any verbal-workload evaluation task.
A robust shell installer that auto-detects the target AI coding tool (Claude Code, Cursor, Windsurf, GitHub Copilot, etc.), copies or symlinks the appropriate skill files, and supports uninstall. Includes version checking against GitHub releases and handles both global and project-local installations. The pattern of per-tool adapter discovery and idempotent symlink/copy logic is reusable for any multi-platform skill distribution.