/amazon-dynamodb

name: amazon-dynamodb
description: Designs, reviews, and debugs DynamoDB data layers from design axioms — enumerates access patterns, chooses partition/sort keys and GSIs, decides single-table vs. multi-table, configures Streams, Global Tables, TTL, vector indexes for similarity search, and zero-ETL integrations to OpenSearch/Redshift/SageMaker Lakehouse, and produces a defensible data-layer design with a monthly cost estimate and optional live validation. Applies whenever a user is designing, reviewing, or refactoring anything backed by DynamoDB — schemas, access patterns, GSIs, single- vs. multi-table choices, Streams consumers, transactional outboxes, Global Tables, zero-ETL pipelines, or storing embeddings and running semantic/vector similarity search with SearchVectors on items already in DynamoDB — even when they don't say "axioms" or "design review." Also applies when debugging hot partitions, throttling, unbounded Scans, LWW conflicts, or surprise bills on DynamoDB workloads.
version: 3

DynamoDB Axioms

This document is a set of design axioms for DynamoDB applications. It is intended to be read by an agent with no other context about the application and used to produce a defensible data-layer design.

Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference or running a script:

• **Loaded through the AWS MCP `retrieve_skill` tool:** The skill is not

installed on the local filesystem. You MUST fetch each reference or script via `retrieve_skill` with the `file` parameter (e.g. `file="references/vector-search.md"` or `file="scripts/calculate_costs.py"`), and run the script from the returned content. Do NOT `file_read` these paths locally — they do not exist on disk.

• **Installed locally** (e.g. `.kiro/skills/amazon-dynamodb/` or

`~/.claude/skills/amazon-dynamodb/`): Read and run files from the local skill directory using relative paths.

This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory. Never fetch or write customer data through `retrieve_skill`.

Separately from where these files live: this skill calls real AWS APIs when it validates a design, deploys a scratch table or benchmarks one. **The AWS MCP server is recommended for those AWS interactions where it is available** — it gives consistent credential handling and region resolution across hosts. It is **not required**: every script here uses boto3 and the AWS CLI against the ambient credential chain, so the skill works unchanged when no MCP server is present.

The `${SKILL_DIR}` resolution below applies to the **locally installed** case: over MCP there is no directory to resolve, and the scripts this skill ships cannot be executed from a returned string — so a cost estimate or live validation requires the locally installed form.

Resolving the skill's own paths

This skill is host-agnostic — it runs under Claude Code, Kiro, Codex, Cursor, a plain terminal, or CI. Where it lives on disk depends on the host (`~/.claude/skills/…`, `~/.kiro/…`, `~/.codex/…`, `~/.cursor/…`, a repo checkout, anywhere). The agent's working directory is the **user's project**, not the skill bundle, so relative paths like `scripts/calculate_costs.py` will not resolve. Throughout this document, `${SKILL_DIR}` means **the absolute path of the directory that contains this SKILL.md file** (the skill root, which holds `scripts/` and `references/`).

**Resolve `${SKILL_DIR}` once per session, then reuse it.** Pick the first method that works in your host:

1. **You already know it.** You loaded SKILL.md from a path — `${SKILL_DIR}` is the directory that file is in. This is the most reliable source; prefer it. 2. **An environment variable.** If `$DDB_SKILL_DIR` is set, trust it. 3. **The bundled resolver** (host-neutral, no host assumptions). It searches the common install roots *and* verifies the hit against sentinel files, so it never returns the wrong directory silently:

   # If you already know the path to the script, just run it directly:
   #   SKILL_DIR="$(sh /path/to/amazon-dynamodb/scripts/find_skill_dir.sh)"
   # If you don't, this host-neutral one-liner searches the common roots
   # (~/.claude, ~/.kiro, ~/.codex, ~/.cursor, ~/.config, ~/.local/share, $PWD):
   SKILL_DIR="$(find "$HOME" "$PWD" -maxdepth 7 -type f -name SKILL.md -path '*amazon-dynamodb*' 2>/dev/null \
                | head -1 | xargs -I{} dirname {})"
   # Verify it before trusting it (sentinel check), then hand off to the resolver
   # for its loud-on-failure diagnostics:
   SKILL_DIR="$(sh "$SKILL_DIR/scripts/find_skill_dir.sh" 2>/dev/null || echo "$SKILL_DIR")"

The resolver prints the verified skill root and exits 0, or prints nothing and exits non-zero with a fix-it message — so `SKILL_DIR="$(sh …/find_skill_dir.sh)"` is safe to trust when it succeeds. It is plain POSIX `sh`, so it behaves identically across hosts.

Once resolved, **export it so every later command is a clean substitution** and the scripts can also pick it up:

export DDB_SKILL_DIR="$SKILL_DIR"
python3 "$DDB_SKILL_DIR/scripts/calculate_costs.py" --model dynamodb_data_model.json --output cost_report.md

Internally the scripts locate their own siblings (other scripts, `scripts/benchmark_lambda.py`) relative to themselves, so you only ever need the **root** path — never each individual script path.

**Rules:**

• Always invoke scripts with an absolute path (the `$DDB_SKILL_DIR/…` form). Do **not** `cd` into the skill directory — the user's working directory must stay put so their artifacts (`dynamodb_data_model.json`, `cost_report.md`, …) land where they expect.
• If none of the three methods resolves the directory, **stop and ask the user where the skill is inst