AWS Cost Audit

Overview

Audit a live AWS account the way a careful FinOps engineer would: attribute every dollar, find waste, and produce an evidence-backed savings plan with confidence levels and reversible, gated actions, for anyone's account, with zero hardcoded prices and zero secrets.

Core principle: every number is verified against a primary source before it is stated, and nothing destructive runs unless it is proven-unused, reversible, tested, and certain. A claim you did not verify is not a finding, it is a guess, and guesses do not ship.

This skill targets Claude Code (it shells out to the AWS CLI). Work read-only by default; treat any change as gated (see below).

The Iron Laws (non-negotiable)

These five laws exist because, without them, agents reliably fail in specific ways (see references/why-these-laws.md for the recorded baseline). Violating the letter of a law violates its spirit, so do not look for loopholes.

1. No unverified price. Ever. Never state a unit price, a monthly cost, or a "$X saved" figure from memory. Every dollar figure must come from BOTH (a) the live unit price for the user's exact Region (AWS Price List Query API or the service's pricing page) and (b) the user's actual usage (Cost Explorer / CUR). Always show: unit price → math → source. Never hardcode a price in this skill, a script, or a report. Prices change and are Region-specific; memorized prices are how two runs produce two different wrong numbers.
2. Attribute every dollar, or say "unknown." For each resource state cost · plain-language purpose · owning app/repo · creator (CloudTrail) · created-when · last-used (CloudWatch / access logs / last-invocation). If any cannot be determined, write "unknown, could not verify". Never invent an owner, a date, or a last-used.
3. Nothing destructive unless proven-unused + reversible + tested + 100% sure. Otherwise it is a recommendation, not an action. See the decision flow below and references/safety-and-gating.md.
4. No single probe becomes a fleet-wide fact. Fan out checks across resources/Regions. A separate skeptic pass must re-derive every load-bearing claim (headline savings, each "safe-to-delete" verdict) from the primary source, not from another agent's summary.
5. Every finding carries its evidence. Output contract per item: current $/mo → after $/mo → $ saved → confidence (High/Med/Low) + evidence + reversibility. Split the total into "save now safely" (High-confidence, reversible, tested) vs "max theoretical save". See references/output-and-reporting.md.

Workflow

Run the steps in order. Heavy detail lives in references/; load a reference only when you reach its step (token-efficient progressive disclosure).

1. Re-baseline live. Confirm identity (aws sts get-caller-identity), then pull Cost Explorer: total + by-service + by-Region + by-usage-type + daily + 90-day trend + forecast. State today's spend, reconciled to the dollar. Save raw JSON.
2. Inventory every Region and service. Loop aws ec2 describe-regions and sweep each service. Work the hunt list in references/hunt-list.md (the high-ROI checks, each with a verified detection command). Run the managed detectors first (Cost Optimization Hub, Compute Optimizer, Trusted Advisor); they pre-compute most findings and net out existing commitments.
3. Classify each resource KEEP / OPTIMIZE / SAFE-TO-DELETE, and justify every dollar.
4. Build the savings model using the output contract (Law 5). Per item: current → after, $ saved, confidence + evidence + reversibility.
5. Verify prices live + skeptic pass. Every dollar figure is re-derived from the live price source and actual usage by a separate check (Law 1 + Law 4). See references/pricing-verification.md.
6. Gated remediation. Only High-confidence, reversible, tested, certain items may auto-run, and only with the executor → verifier → rollback gate. Everything else is a labeled recommendation.
7. Deliver. A plain-language report (references/output-and-reporting.md), an optional generated HTML dashboard (references/dashboard.md + assets/dashboard-template.html), a health/monitoring view, and budget + anomaly-detection guardrails. Finish with a completeness pass: "what Region / service / cost driver did we NOT inspect?"; it must come back empty.

Decision: auto-execute vs recommend

The only non-obvious call in this skill. When in doubt, recommend.

digraph gate {
  rankdir=TB; node [shape=box];
  q1 [shape=diamond, label="Proven UNUSED by live evidence\n(multiple signals, 30–90d)?"];
  q2 [shape=diamond, label="Reversible?\n(snapshot/backup/versioning/detach-first)"];
  q3 [shape=diamond, label="Tested in dry-run AND\n100% sure of blast radius?"];
  rec [label="RECOMMEND only\n(put on report w/ confidence, do NOT run)"];
  run [label="May auto-run\nvia executor → verifier → rollback"];
  q1 -> rec [label="no / unsure"];
  q1 -> q2 [label="yes"];
  q2 -> rec [label="no"];
  q2 -> q3 [label="yes"];
  q3 -> rec [label="no"];
  q3 -> run [label="yes"];
}

Irreversible actions (release EIP, delete snapshot/AMI, terminate, Savings Plan/RI purchase) are never auto-run; they are always recommendations requiring explicit human sign-off.

Quick reference: highest-ROI checks

Full hunt list with verified commands, reversibility, and price source: references/hunt-list.md.

One worked example: an unattached EBS volume

This shows the full method on a single finding. Apply the same shape to every item.

# 1. DETECT (read-only)
aws ec2 describe-volumes --region "$REGION" \
  --filters Name=status,Values=available \
  --query 'Volumes[].{id:VolumeId,gb:Size,type:VolumeType,created:CreateTime,az:AvailabilityZone}'

# 2. ATTRIBUTE (never guess; "unknown" is a valid answer)
aws ec2 describe-volumes --volume-ids "$VOL" --query 'Volumes[0].Tags'        # owner/app? else unknown
aws cloudtrail lookup-events --lookup-attributes \
  AttributeKey=ResourceName,AttributeValue="$VOL" \
  --query 'Events[?contains(EventName,`CreateVolume`)].[Username,EventTime]'  # creator/when, or "unknown, predates trail"
aws cloudwatch get-metric-statistics --namespace AWS/EBS --metric-name VolumeReadOps \
  --dimensions Name=VolumeId,Value="$VOL" --start-time "$START" --end-time "$NOW" \
  --period 86400 --statistics Sum --region "$REGION"                          # last-used signal

# 3. VERIFY PRICE LIVE (never from memory): gp3 storage $/GB-month for THIS region
aws pricing get-products --service-code AmazonEC2 --region us-east-1 \
  --filters "Type=TERM_MATCH,Field=productFamily,Value=Storage" \
            "Type=TERM_MATCH,Field=volumeApiName,Value=gp3" \
            "Type=TERM_MATCH,Field=regionCode,Value=$REGION" \
  --query 'PriceList' --output text     # parse the returned JSON for the per-GB-mo USD rate
# savings $/mo = (live $/GB-mo) × (provisioned GB).  Show the math and the source.

Finding (the shape every item takes):

• What / purpose: 100 GB gp3 volume, available (detached). Tags: none → owner unknown.
• Creator / created / last-used: CreateVolume by unknown, predates CloudTrail window; created <date>; VolumeReadOps = 0 for 90 days → strong unused signal.
• Cost now → after: (live gp3 $/GB-mo from Price List API) × 100 → $0.
• $ saved: that figure. Confidence: High (zero I/O 90d, detached, no references). Evidence: the three commands above. Reversibility: snapshot first, then delete (recoverable).
• Verdict: SAFE-TO-DELETE as a recommendation; auto-run only after snapshot + dry-run + sign-off.

Rationalization table: STOP if you catch yourself thinking this

Red flags: these mean STOP and re-read the Iron Laws

• A dollar figure in your answer that you did not pull from the live price source + actual usage.
• A delete/terminate/release/rm you are about to run without a snapshot/rollback and sign-off.
• An owner, creation date, or "last used" you inferred rather than read from an API.
• A fleet-wide conclusion drawn from one resource.
• A headline savings total that no separate skeptic pass re-derived from primaries.

Reference files (load on demand)

• references/hunt-list.md: every high-ROI check: verified detection command, why it saves, reversibility, where to verify the price.
• references/pricing-verification.md: how to get a live, Region-correct price and reconcile it with actual usage; the skeptic re-derivation routine.
• references/safety-and-gating.md: the executor → verifier → rollback pattern; reversibility techniques; what may never auto-run.
• references/output-and-reporting.md: the per-item output contract, the report structure, "save now" vs "max theoretical".
• references/dashboard.md: how to generate the optional HTML dashboard from verified data (template in assets/).
• references/why-these-laws.md: the recorded baseline failures the Iron Laws fix (the TDD evidence).
• scripts/: generic, parameterized, dry-run-by-default helpers (no hardcoded account/ARN/price).