AWS Best Practices Skill

Ask your AI coding agent "how should I secure my S3 bucket" and get sourced, locally cataloged AWS best practices, skipping both stale training data and costly live research.

A skill for Claude Code and OpenAI Codex that collects the best
practices of every AWS service, and nothing else. Find recommendations by
use case: security, reliability, performance, cost, operations,
sustainability, each one linked to its official AWS source.

Project page: https://ferdinandobons.github.io/AWSBestPracticesSkill/

Latest release: v0.1.5

Unofficial project: this is an independent community-maintained skill.
It is not an official AWS skill, AWS product, or AWS-maintained resource,
and it is not affiliated with or endorsed by Amazon Web Services.

Scope: this skill contains only best practices. No service
descriptions, no pricing, no tutorials, no code walkthroughs. Just what AWS
recommends you do, organized so you can act on it, each item linked to its
official AWS source.

Why this instead of just asking the model directly

There are three ways an AI agent can answer "what are the best practices for
this AWS service":

1. From memory: free and instant, but the model's training data goes
   stale the moment AWS ships a new feature, renames a service, or updates its
   Well-Architected guidance. It will still answer confidently even when it's
   wrong or out of date.
2. Live research: the agent runs web searches or queries an AWS
   documentation MCP server on the spot, every time. This gets it right, but
   it's expensive: several search → fetch → read round-trips, burning tens of
   thousands of tokens, repeated for every question, even the same one asked
   twice.
3. This skill: the research is already done, once, per service, and
   stored as a small, source-linked file. The agent opens exactly
   services/<category>/<service>.md, reads a few hundred lines, and
   answers, no live search needed and no repeated token cost, while every
   practice is still traceable to an official docs.aws.amazon.com /
   aws.amazon.com / wa.aws.amazon.com page. And because content ages, a
   documented refresh loop (below) keeps it from silently drifting back into
   "stale training data" territory.

What it contains / does NOT contain

Quick start

Claude Code (plugin, recommended):

claude plugin marketplace add ferdinandobons/AWSBestPracticesSkill
claude plugin install aws-best-practices@aws-best-practices-skill

Update with claude plugin update aws-best-practices, remove with claude plugin uninstall aws-best-practices. (Same steps work as /plugin marketplace add ... and /plugin install ... from inside an active Claude Code session.)

OpenAI Codex CLI (plugin, recommended):

codex plugin marketplace add ferdinandobons/AWSBestPracticesSkill
codex plugin add aws-best-practices@aws-best-practices-skill

Update with codex plugin marketplace upgrade aws-best-practices-skill, remove with codex plugin remove aws-best-practices@aws-best-practices-skill.

Manual install (backup, works for both):

# Claude Code
git clone https://github.com/ferdinandobons/AWSBestPracticesSkill ~/.claude/skills/aws-best-practices

# OpenAI Codex CLI
git clone https://github.com/ferdinandobons/AWSBestPracticesSkill ~/.codex/skills/aws-best-practices

Update anytime with git -C <path-above> pull.

Restart the tool if it's open. Two ways to use it:

Direct, invoke the skill by name:

• Claude Code: /aws-best-practices (manual install) or
  /aws-best-practices:aws-best-practices (plugin install; plugin skills are
  namespaced as plugin:skill).
• Codex CLI: reference aws-best-practices in your prompt (e.g. "use the
  aws-best-practices skill for...").

Indirect, just ask a question about a service and it triggers
automatically, no invocation needed:

"best practices for securing my S3 bucket" · "how should I run DynamoDB for high traffic" · "AWS account security baseline" · "is my Lambda function set up correctly for production"

Either way, the model reads SKILL.md, opens the matching
services/<category>/<service>.md (or general/<topic>.md), and answers with
sourced best practices; it won't need to open anything else in this repo.

How answers are shaped

The skill is scenario-first. If you ask for a specific case, the agent should
select the relevant practices instead of dumping the whole service file:

• Specific case: "secure my S3 bucket", "SQS queue in production",
  "reduce DynamoDB cost", or "is this Lambda setup production-ready?" returns
  the practices that apply to that workload, grouped by the useful
  Well-Architected pillars.
• No specific case: "best practices for SQS" returns a general production
  baseline across security, reliability, performance, cost, and operations.
• No live web by default: ordinary answers come from the local Markdown
  catalog. Source URLs are copied from those files; the agent should only
  browse or re-check AWS documentation when you explicitly ask for a live
  verification or the local catalog is missing the topic.

The default response shape is compact: recommended baseline, key decisions
when the service has trade-offs, caveats for special cases, and the local file
path plus last_reviewed date when available.

How navigation works

SKILL.md is a router. The model identifies the service + concern from your
use case, opens the matching file under services/, reads the Common
scenarios map, then the relevant pillar sections.

SKILL.md                          # router / index (what the model reads first)
catalog.md                        # human-readable index (generated)
catalog.json                      # machine-readable source of truth
services/<category>/<service>.md  # per-service best practices
general/<topic>.md                # cross-service best practices
scripts/                          # maintainer utilities (check.py, cost.py)
docs/                             # GitHub Pages landing page + SEO metadata
GENERATE.md                       # fills in missing files (maintainers)
REFRESH.md                        # periodic refresh: new services + stale content (maintainers)
.claude-plugin/                   # Claude Code plugin + marketplace manifest
.codex-plugin/                    # Codex CLI plugin manifest
.agents/plugins/                  # Codex CLI marketplace manifest

Browse the full index in catalog.md.

Coverage

• 208 services across 23 AWS categories, plus 9 general cross-service docs: 217 files, all complete.
• Best practices sourced from official AWS documentation and the Well-Architected Framework.
• Every source link verified live (HTTP 200, official AWS host) as of the last full check.

How the catalog stays current

This isn't a one-time snapshot. Two portable, tool-agnostic prompts drive the
catalog's lifecycle: paste either into a Claude Code / Codex CLI chat in this
repo.

• GENERATE.md fills in any catalog entry that doesn't
  have a file yet, researching official AWS docs per service.
• REFRESH.md runs periodically to (1) diff catalog.json
  against AWS's current service list, picking up new services, catching
  renamed or recategorized ones, dropping fully-retired ones, and (2)
  re-review existing files whose content has gone stale, per
  scripts/check.py --stale (default: no review in the last 180 days).

Both are gated by scripts/check.py, which validates
structure, coverage, freshness, and link health with zero external
dependencies (--check-links hits the network; everything else is a pure
stdlib parse), so a maintenance pass can't silently drift from the "only
best practices, always sourced" rule.

Build cost

The entire best-practices corpus is generated by pasting GENERATE.md
into a coding agent's chat. Token usage is tracked from each generation run.

Generation cost so far: ~30.51M tokens (30,510,969) across 481 workflow agents · 217 files. See docs/build-cost.md for the per-phase breakdown.

Maintenance

This is a living collection. The update procedure, generating missing entries
with GENERATE.md, keeping the catalog current with
REFRESH.md, and the validation gate, is documented in
MAINTENANCE.md. Validate locally with:

python3 scripts/check.py                # coverage + conformance + freshness summary
python3 scripts/check.py --strict       # release gate: every catalog entry has a file
python3 scripts/check.py --check-links  # validate all source links (network)
python3 scripts/check.py --stale        # list entries due for a REFRESH.md pass

Contributions welcome, see MAINTENANCE.md before opening a PR.

License

MIT, see LICENSE.