fix: ensure_skills_clone helper semantics + correct operator messaging

packs/claude-code/install.sh

@@ -157,10 +157,13 @@ ok "claude --version: ${CLAUDE_VER}"
 # ── Done ─────────────────────────────────────────────────────────────────────
 
 # ── Install loki-skills library ───────────────────────────────────────────────
-# Best-effort: pre-install skills (shared or pack-specific).
+# Best-effort: pre-install skills for auto-discovery.
 PACK_SKILLS_DIR="${HOME}/.claude/skills"
-ensure_skills_clone "${PACK_SKILLS_DIR}" || true
-log "Skills installed to ${PACK_SKILLS_DIR}"
+if ensure_skills_clone "${PACK_SKILLS_DIR}"; then
+  ok "Skills installed to ${PACK_SKILLS_DIR} (auto-discovered)"
+else
+  warn "Skills clone failed (optional; claude is still usable without skills)"
+fi
 write_done_marker "claude-code"
 printf "\n[PACK:claude-code] INSTALLED — claude CLI ready (model: %s via Bedrock region: %s)\n" \
   "${MODEL}" "${REGION}"

packs/codex-cli/install.sh

@@ -292,9 +292,12 @@ NOTICE
 # ── Done ──────────────────────────────────────────────────────────────────────
 
 # ── Install loki-skills library ───────────────────────────────────────────────
-# Best-effort: pre-install skills (shared or pack-specific).
+# Best-effort: pre-install skills for auto-discovery.
 PACK_SKILLS_DIR="${HOME}/.codex/skills"
-ensure_skills_clone "${PACK_SKILLS_DIR}" || true
-log "Skills installed to ${PACK_SKILLS_DIR}"
+if ensure_skills_clone "${PACK_SKILLS_DIR}"; then
+  ok "Skills installed to ${PACK_SKILLS_DIR} (auto-discovered)"
+else
+  warn "Skills clone failed (optional; codex is still usable without skills)"
+fi
 write_done_marker "codex-cli"
 printf "\n[PACK:codex-cli] INSTALLED — codex CLI ready (model: %s)\n" "${MODEL}"

packs/common.sh

@@ -26,7 +26,6 @@ ensure_skills_clone() {
   local repo_url="${2:-${LOKI_SKILLS_REPO_URL}}"
   local branch="${3:-main}"
   local mode="${4:-warn}"
-  local rc=0
 
   # Check git available
   if ! command -v git &>/dev/null; then
@@ -35,41 +34,62 @@ ensure_skills_clone() {
     return 0
   fi
 
-  # Existing repo: try update
+  # Existing repo: try update if same origin
   if [[ -d "$target_dir" ]] && [[ -d "$target_dir/.git" ]]; then
     local origin_url="$(cd "$target_dir" && git config --get remote.origin.url 2>/dev/null)"
     if [[ "$origin_url" == "$repo_url" ]]; then
-      # Same origin, safe to update
-      if (cd "$target_dir" && git fetch origin "$branch" && git checkout "$branch") &>/dev/null; then
-        log "Skills repo updated at $target_dir"
+      # Same origin, safe to update: reset to remote tip
+      if (cd "$target_dir" && git fetch origin "$branch" 2>&1 && git reset --hard "origin/$branch" 2>&1) &>/dev/null; then
+        log "Skills repo updated at $target_dir (branch: $branch)"
         return 0
       else
-        log "Skills repo update failed; moving aside and re-cloning"
-        mv "$target_dir" "${target_dir}.bak.$RANDOM" || true
+        # Update failed: preserve existing rather than move aside in warn mode
+        if [[ "$mode" == "fail" ]]; then
+          log "Skills repo update failed (FATAL)"
+          return 1
+        else
+          log "Skills repo update failed; keeping existing checkout (warn mode)"
+          return 0
+        fi
       fi
     else
-      # Different origin: move aside and re-clone
-      log "Skills origin mismatch; moving aside and re-cloning"
-      mv "$target_dir" "${target_dir}.bak.$RANDOM" || true
+      # Different origin: only move aside if clone will succeed
+      # Preserve existing in warn mode if replacement fails
+      log "Skills origin mismatch; attempting re-clone..."
     fi
   fi
 
   # Partial dir (no .git): remove and re-clone
-  if [[ -d "$target_dir" ]] && [[ ! -d "$target_dir/.git" ]]; then
-    log "Incomplete skills dir; removing and re-cloning"
-    rm -rf "$target_dir" || true
+  local backup_dir=""
+  if [[ -d "$target_dir" ]]; then
+    if [[ ! -d "$target_dir/.git" ]]; then
+      log "Incomplete skills dir; removing and re-cloning"
+      rm -rf "$target_dir" || true
+    else
+      # Save as backup in case clone fails (warn mode recovery)
+      backup_dir="${target_dir}.bak.$RANDOM"
+      mv "$target_dir" "$backup_dir" || true
+    fi
   fi
 
-  # Fresh clone (shallow)
-  if ! git clone --depth 1 --branch "$branch" "$repo_url" "$target_dir" &>/dev/null; then
-    local msg="Skills clone failed (repo: $repo_url, branch: $branch)"
-    [[ "$mode" == "fail" ]] && { log "$msg (FATAL)"; return 1; } || log "$msg (warn, continuing)"
-    rc=1
-  else
+  # Fresh clone (shallow) — only commit to move if clone succeeds
+  if git clone --depth 1 --branch "$branch" "$repo_url" "$target_dir" &>/dev/null; then
+    # Clone succeeded: remove backup if one exists
+    [[ -n "$backup_dir" ]] && rm -rf "$backup_dir" || true
     log "Skills cloned to $target_dir"
+    return 0
+  else
+    # Clone failed: restore backup if we have one (warn mode)
+    if [[ -n "$backup_dir" ]] && [[ -d "$backup_dir" ]]; then
+      mv "$backup_dir" "$target_dir" || true
+      local msg="Skills clone failed; restored backup at $target_dir"
+      [[ "$mode" == "fail" ]] && { log "$msg (FATAL)"; return 1; } || { log "$msg (warn)"; return 0; }
+    else
+      # No backup to restore
+      local msg="Skills clone failed (repo: $repo_url, branch: $branch)"
+      [[ "$mode" == "fail" ]] && { log "$msg (FATAL)"; return 1; } || { log "$msg (warn, no fallback)"; return 1; }
+    fi
   fi
-
-  return $rc
 }
 
 # Colors

packs/hermes/install.sh

@@ -145,10 +145,13 @@ fi
 # ── Done ──────────────────────────────────────────────────────────────────────
 
 # ── Install loki-skills library ───────────────────────────────────────────────
-# Best-effort: pre-install skills (shared or pack-specific).
+# Best-effort: pre-install skills for auto-discovery.
 PACK_SKILLS_DIR="${HOME}/.hermes/skills"
-ensure_skills_clone "${PACK_SKILLS_DIR}" || true
-log "Skills installed to ${PACK_SKILLS_DIR}"
+if ensure_skills_clone "${PACK_SKILLS_DIR}"; then
+  ok "Skills installed to ${PACK_SKILLS_DIR} (auto-discovered)"
+else
+  warn "Skills clone failed (optional; hermes is still usable without skills)"
+fi
 write_done_marker "hermes"
 printf "\n[PACK:hermes] INSTALLED — hermes CLI ready (model: %s via bedrockify:%s)\n" \
   "${MODEL}" "${BEDROCKIFY_PORT}"

packs/ironclaw/install.sh

@@ -365,9 +365,9 @@ ok "Systemd service installed with EnvironmentFile + --no-onboard"
 
 # ── Done ─────────────────────────────────────────────────────────────────────
 
-# ── IronClaw Skills Configuration (MCP-native, no direct skills auto-discovery) ─
-# IronClaw uses MCP servers (Model Context Protocol) for extensions, not local skills.
-# Skill reference docs: see ~/.openclaw/workspace/skills/ + BOOTSTRAP-MCPORTER.md
+# ── IronClaw MCP Configuration ──────────────────────────────────────────────────────
+# IronClaw uses MCP servers (Model Context Protocol) for extensions.
+# For skills reference docs, see: https://github.com/inceptionstack/loki-skills
 log "IronClaw configured for MCP servers (no local skills pre-install needed)"
 write_done_marker "ironclaw"
 printf "\n[PACK:ironclaw] INSTALLED — ironclaw CLI ready\n"

packs/kiro-cli/install.sh

@@ -360,10 +360,13 @@ if [[ -f "${SHELL_PROFILE}" && -d /etc/profile.d ]]; then
 fi
 
 # ── Install loki-skills library ───────────────────────────────────────────────
-# Best-effort: pre-install skills to kiro workspace.
+# Best-effort: pre-install skills for auto-discovery.
 PACK_SKILLS_DIR="${HOME}/.kiro/skills"
-ensure_skills_clone "${PACK_SKILLS_DIR}" || true
-log "Skills auto-installed to ${PACK_SKILLS_DIR}"
+if ensure_skills_clone "${PACK_SKILLS_DIR}"; then
+  ok "Skills auto-installed to ${PACK_SKILLS_DIR} (auto-discovered)"
+else
+  warn "Skills clone failed (optional; kiro is still usable without skills)"
+fi
 
 # ── Done ──────────────────────────────────────────────────────────────────────
 write_done_marker "kiro-cli"

packs/pi/install.sh

@@ -127,12 +127,15 @@ chmod 600 "${HOME}/.pi/agent/models.json"
 ok "Pi config written: ${HOME}/.pi/agent/models.json"
 
 # ── Install loki-skills library ───────────────────────────────────────────────
-# Best-effort: pre-install skills as reference docs for Pi users.
-# Skills are stored per-agent (not auto-discovered), so users must manually
-# create TypeScript extensions to use them. This ensures they're always available.
+# Best-effort: pre-install skills for auto-discovery.
+# Pi auto-discovers SKILL.md folders in ~/.pi/agent/extensions/.
+# Users can also create manual TypeScript extension adapters if needed.
 PACK_SKILLS_DIR="${HOME}/.pi/agent/extensions"
-ensure_skills_clone "${PACK_SKILLS_DIR}" || true
-log "Skills installed to ${PACK_SKILLS_DIR} (reference docs; manual extension creation needed)"
+if ensure_skills_clone "${PACK_SKILLS_DIR}"; then
+  ok "Skills installed to ${PACK_SKILLS_DIR} (auto-discovered by pi)"
+else
+  warn "Skills clone failed (optional; pi is still usable without skills)"
+fi
 
 # ── Sanity check ─────────────────────────────────────────────────────────────
 step "Sanity check"