Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aws-samples/sample-well-architected-skills-and-steering/llms.txt

Use this file to discover all available pages before exploring further.

OpenAI Codex picks up AGENTS.md from the root of your project and uses it as persistent context for every session. Pairing that steering file with the skills/ directory gives Codex access to 11 structured Well-Architected playbooks it can follow step-by-step whenever you request a review or assessment.

​
What gets installed

AGENTS.md

Steering context that tells Codex to apply the six Well-Architected pillars, surface trade-offs, and route review requests to the correct skill playbook.

skills/ directory

Eleven skill directories, each containing a SKILL.md playbook covering a distinct assessment area — from full WA review to cost optimization to ADRs.

​
Installation

1

Clone or download the source repo

If you haven’t already, clone the sample repository to a local path you can reference:
git clone https://github.com/aws-samples/sample-well-architected-skills-and-steering.git
2

Copy files into your project

Run the commands below from the root of your project directory, substituting path/to/this-repo with the actual clone location.
cp path/to/this-repo/adapters/codex/AGENTS.md ./AGENTS.md
cp -r path/to/this-repo/skills ./skills
3

Verify the layout

Your project root should now contain:
AGENTS.md
skills/
  wa-review/SKILL.md
  security-assessment/SKILL.md
  reliability-improvement-plan/SKILL.md
  cost-optimization-review/SKILL.md
  performance-efficiency/SKILL.md
  sustainability-optimization/SKILL.md
  operational-excellence/SKILL.md
  migration-readiness/SKILL.md
  architecture-decision-record/SKILL.md
  wa-builder/SKILL.md
  wa-guardrails/SKILL.md

​
Install via script

If you prefer the one-command approach from a local clone, the install script handles copying automatically: 
./install.sh ~/my-project --tool codex

​
Usage

Once the files are in place, Codex reads AGENTS.md on startup. Trigger any skill by describing what you want in natural language: 
Run a Well-Architected review of this architecture.
When Codex detects a review keyword, it reads the corresponding skills/{skill-name}/SKILL.md and follows the structured steps inside it.
The AGENTS.md steering groups findings by pillar and applies severity labels (🔴 High Risk, 🟡 Medium Risk, 🟢 Best Practice) so output is easy to triage. Ask for a “quick review” first to identify gaps, then drill into specific pillars for deeper analysis.

​
Available skills

SkillWhat it does
wa-reviewFull 6-pillar review with prioritized findings report
security-assessmentDeep-dive into IAM, detection, data protection, incident response
reliability-improvement-planFind SPOFs, assess recovery, produce remediation plan
cost-optimization-reviewIdentify waste, right-sizing, pricing model improvements
performance-efficiencyResource selection, scaling, caching, optimization
sustainability-optimizationUtilization, architecture efficiency, carbon reduction
operational-excellenceCI/CD, observability, incident management, operational maturity
migration-readiness7 Rs assessment, dependency analysis, migration plan
architecture-decision-recordADR with WA pillar impact analysis
wa-builderLearn WA for your workload and generate visual artifacts
wa-guardrailsGenerate preventive controls (Config rules, SCPs, CI checks)

Build docs developers (and LLMs) love

Get started for freeTalk to us