diff --git a/README.md b/README.md
index 4bfea44f..05cf2ba6 100644
--- a/README.md
+++ b/README.md
@@ -164,6 +164,24 @@ COMPOUND_PLUGIN_GITHUB_SOURCE=https://github.com/awslabs/agent-plugins \
 
 Replace `deploy-on-aws` with any plugin name from the table above (e.g., `aws-serverless`, `amazon-location-service`, `migration-to-aws`, `aws-amplify`).
 
+#### Install scripts for aws-architecture-diagram (required)
+
+The `compound-plugin` converter only copies `skills/<name>/` — it does not install the plugin-level `scripts/` folder that the `aws-architecture-diagram` skill depends on. Without this step, diagram validation, badge fixing, and preview URL generation will not work.
+
+Run after the install step above (global scope):
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/awslabs/agent-plugins/main/plugins/deploy-on-aws/scripts/install-kiro-scripts.sh)
+```
+
+Or for a project-scoped install:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/awslabs/agent-plugins/main/plugins/deploy-on-aws/scripts/install-kiro-scripts.sh) --project
+```
+
+This downloads the scripts into `~/.kiro/skills/aws-architecture-diagram/scripts/`, installs their Python dependency (`defusedxml`), and patches the `${PLUGIN_ROOT}` path references in `SKILL.md` to the actual install location.
+
 > [!TIP]
 > If a skill isn't activated automatically, you can explicitly invoke it by saying "Use the deploy skill to ..." in your prompt. Kiro's intent matching may not always auto-trigger skills.
 >
diff --git a/plugins/deploy-on-aws/scripts/install-kiro-scripts.sh b/plugins/deploy-on-aws/scripts/install-kiro-scripts.sh
new file mode 100755
index 00000000..e7dec37c
--- /dev/null
+++ b/plugins/deploy-on-aws/scripts/install-kiro-scripts.sh
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# install-kiro-scripts.sh
+#
+# Installs plugin-level scripts into the Kiro skill directory and patches
+# ${PLUGIN_ROOT} references in SKILL.md to the actual installed path.
+#
+# Required because the compound-plugin converter only copies skills/<name>/
+# and does not install plugin-level scripts/ that some skills depend on.
+#
+# Usage (global install):
+#   bash plugins/deploy-on-aws/scripts/install-kiro-scripts.sh
+#
+# Usage (project-scoped install):
+#   bash plugins/deploy-on-aws/scripts/install-kiro-scripts.sh --project
+
+set -euo pipefail
+
+# ── resolve install root ──────────────────────────────────────────────────────
+PROJECT_SCOPE=false
+for arg in "$@"; do
+  [[ "$arg" == "--project" ]] && PROJECT_SCOPE=true
+done
+
+if [[ "$PROJECT_SCOPE" == "true" ]]; then
+  KIRO_ROOT="${PWD}/.kiro"
+  SCOPE_LABEL="project"
+else
+  KIRO_ROOT="${HOME}/.kiro"
+  SCOPE_LABEL="global"
+fi
+
+SKILL_NAME="aws-architecture-diagram"
+KIRO_SKILLS_DIR="${KIRO_ROOT}/skills/${SKILL_NAME}"
+SCRIPTS_DEST="${KIRO_SKILLS_DIR}/scripts"
+REPO_RAW="https://raw.githubusercontent.com/awslabs/agent-plugins/main/plugins/deploy-on-aws/scripts"
+
+echo ""
+echo "📦  Installing scripts for '${SKILL_NAME}' (${SCOPE_LABEL} scope)"
+echo "    Target: ${KIRO_SKILLS_DIR}"
+echo ""
+
+# ── verify skill is installed ─────────────────────────────────────────────────
+if [[ ! -f "${KIRO_SKILLS_DIR}/SKILL.md" ]]; then
+  echo "❌  '${SKILL_NAME}' skill not found at ${KIRO_SKILLS_DIR}"
+  echo ""
+  echo "    Run the compound-plugin install step first:"
+  echo ""
+  if [[ "$PROJECT_SCOPE" == "true" ]]; then
+    echo "    COMPOUND_PLUGIN_GITHUB_SOURCE=https://github.com/awslabs/agent-plugins \\"
+    echo "      bunx @every-env/compound-plugin install deploy-on-aws --to kiro"
+  else
+    echo "    COMPOUND_PLUGIN_GITHUB_SOURCE=https://github.com/awslabs/agent-plugins \\"
+    echo "      bunx @every-env/compound-plugin install deploy-on-aws --to kiro --output ~/.kiro"
+  fi
+  echo ""
+  exit 1
+fi
+
+# ── download scripts ──────────────────────────────────────────────────────────
+mkdir -p "${SCRIPTS_DEST}/lib"
+
+SCRIPTS=(
+  "lib/drawio_url.py"
+  "lib/fix_step_badges.py"
+  "lib/fix_icon_colors.py"
+  "lib/fix_nesting.py"
+  "lib/post_process_drawio.py"
+  "lib/validate_drawio.py"
+  "lib/aws4-shapes.json"
+  "requirements.txt"
+)
+
+for script in "${SCRIPTS[@]}"; do
+  dest_dir="${SCRIPTS_DEST}/$(dirname "$script")"
+  mkdir -p "$dest_dir"
+  curl -fsSL "${REPO_RAW}/${script}" -o "${SCRIPTS_DEST}/${script}"
+  echo "    ✅  ${script}"
+done
+
+# ── install Python dependencies ───────────────────────────────────────────────
+if command -v pip3 &>/dev/null; then
+  pip3 install -r "${SCRIPTS_DEST}/requirements.txt" -q
+  echo "    ✅  Python dependencies installed (defusedxml)"
+elif command -v pip &>/dev/null; then
+  pip install -r "${SCRIPTS_DEST}/requirements.txt" -q
+  echo "    ✅  Python dependencies installed (defusedxml)"
+else
+  echo "    ⚠️   pip not found — install dependencies manually:"
+  echo "        pip install -r ${SCRIPTS_DEST}/requirements.txt"
+fi
+
+# ── patch ${PLUGIN_ROOT} in SKILL.md ─────────────────────────────────────────
+# ${PLUGIN_ROOT} is a Claude Code runtime variable with no Kiro equivalent.
+# Replace it with the actual installed skill path so script references resolve.
+if grep -q '${PLUGIN_ROOT}' "${KIRO_SKILLS_DIR}/SKILL.md"; then
+  sed -i.bak "s|\${PLUGIN_ROOT}|${KIRO_SKILLS_DIR}|g" "${KIRO_SKILLS_DIR}/SKILL.md"
+  rm -f "${KIRO_SKILLS_DIR}/SKILL.md.bak"
+  echo "    ✅  Patched \${PLUGIN_ROOT} → ${KIRO_SKILLS_DIR} in SKILL.md"
+else
+  echo "    ℹ️   SKILL.md already patched — skipping"
+fi
+
+echo ""
+echo "✅  Done. The '${SKILL_NAME}' skill is fully installed for Kiro."
+echo ""