Amazon Dynamodb

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 installed rather than guessing. A wrong ${SKILL_DIR} produces confusing "file not found" failures downstream; one clarifying question is cheaper.

The pipeline at a glance

The skill is one tool per stage. The default path touches no AWS: most work is stage 1 (a design you can discuss and refine conversationally). Stage 2 (cost) runs on request or when the design is being finalized — not reflexively every turn. Stages 3–6 are a distinctly opt-in, heavyweight fork that creates real AWS resources and incurs a real bill; enter it only on explicit user agreement. Each stage's detailed contract is in the section named in the last column.

Who reads what. You (the agent) read the compact artifacts: cost_report.md, design_findings.json, loop_state.json. The user reads performance_report.md. Never read perf_raw.jsonl (large) — it only feeds stage 5.

Consent gates. Stage 3+ needs --yes-deploy; the benchmark refuses to spend over cost_guardrail_usd without --allow-spend; teardown needs the user's attested review and intent before you run bash teardown.sh --confirm. Details in Live validation.