fix(pi): package warning-free skill mirror and docs

scripts/sync-pi-package-skills.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+TARGET_ROOT="${ROOT_DIR}/pi-package/skills"
+SKILL_FAMILIES=(
+  "atlassian"
+  "create-plan"
+  "do-task"
+  "implement-plan"
+  "web-automation"
+)
+
+extract_skill_name() {
+  local skill_md=$1
+  awk '/^name:/ { print $2; exit }' "$skill_md"
+}
+
+replace_dir() {
+  local source=$1
+  local target=$2
+
+  if [[ -z "$target" || "$target" == "/" || "$target" == "." || "$target" == ".." ]]; then
+    echo "Refusing to sync into unsafe target: $target" >&2
+    exit 1
+  fi
+
+  case "$target" in
+    "${ROOT_DIR}"/*) ;;
+    *)
+      echo "Refusing to remove target outside repo root: $target" >&2
+      exit 1
+      ;;
+  esac
+
+  rm -rf "$target"
+  mkdir -p "$target"
+  cp -R "${source}/." "$target/"
+}
+
+rm -rf "$TARGET_ROOT"
+mkdir -p "$TARGET_ROOT"
+
+for family in "${SKILL_FAMILIES[@]}"; do
+  source_dir="${ROOT_DIR}/skills/${family}/pi"
+  skill_md="${source_dir}/SKILL.md"
+
+  if [[ ! -f "$skill_md" ]]; then
+    echo "Missing source SKILL.md: $skill_md" >&2
+    exit 1
+  fi
+
+  skill_name=$(extract_skill_name "$skill_md")
+  if [[ -z "$skill_name" ]]; then
+    echo "Could not derive skill name from $skill_md" >&2
+    exit 1
+  fi
+
+  replace_dir "$source_dir" "${TARGET_ROOT}/${skill_name}"
+done
+
+echo "Synced pi package skill mirror into ${TARGET_ROOT}."