design-agent-skills 1.4.2

package/install.sh

@@ -0,0 +1,689 @@
+#!/usr/bin/env bash
+# design-agent-skills installer — works with bash 3.2+
+# Usage: ./install.sh [--scope=user|project] [install|status|update|fix|help]
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILLS_SRC="$REPO_DIR/skills"
+LOCKFILE="$REPO_DIR/design-agent-skills.lock"
+
+# ── Parse global flags ────────────────────────────────────────────────────────
+SCOPE="user"
+INCLUDE_EXPERIMENTAL=0
+ARGS=()
+for arg in "$@"; do
+  case "$arg" in
+    --scope=user)             SCOPE="user"             ;;
+    --scope=project)          SCOPE="project"          ;;
+    --include-experimental)   INCLUDE_EXPERIMENTAL=1   ;;
+    *) ARGS+=("$arg") ;;
+  esac
+done
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+# ── Agent registry (name:config_root:skills_dir) ──────────────────────────────
+USER_AGENTS="
+claude:$HOME/.claude:$HOME/.claude/skills
+cursor:$HOME/.cursor:$HOME/.cursor/skills
+codex:$HOME/.codex:$HOME/.codex/skills
+opencode:$HOME/.config/opencode:$HOME/.config/opencode/skills
+droid:$HOME/.factory:$HOME/.factory/skills
+"
+
+PROJECT_AGENTS="
+claude:$(pwd)/.claude:$(pwd)/.claude/skills
+cursor:$(pwd)/.cursor:$(pwd)/.cursor/skills
+opencode:$(pwd)/.opencode:$(pwd)/.opencode/skills
+"
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+agent_list_for_scope() {
+  if [ "$SCOPE" = "project" ]; then
+    echo "$PROJECT_AGENTS"
+  else
+    echo "$USER_AGENTS"
+  fi
+}
+
+detected_agents() {
+  agent_list_for_scope | grep -v '^$' | while IFS=: read -r name root _skills; do
+    if [ "$SCOPE" = "project" ]; then
+      # Project scope: include if the config dir exists OR we're creating it
+      [ -d "$(dirname "$root")" ] && echo "$name:$root:$_skills"
+    else
+      [ -d "$root" ] && echo "$name:$root:$_skills"
+    fi
+  done
+}
+
+stub_yaml_value() {
+  # $1=key  $2=stub.yaml path — minimal key: value parser
+  grep "^${1}:" "$2" | sed 's/^[^:]*: *//' | tr -d '"'
+}
+
+stub_yaml_list() {
+  # $1=key  $2=stub.yaml path — parse block-sequence list (- item per line)
+  awk -v key="$1" '
+    $0 ~ ("^" key ":") { in_list=1; next }
+    in_list && /^[[:space:]]*-[[:space:]]/ {
+      line=$0; sub(/^[[:space:]]*-[[:space:]]+/,"",line); gsub(/"/,"",line)
+      print line; next
+    }
+    in_list && /^[^[:space:]]/ { exit }
+  ' "$2"
+}
+
+stub_tier() {
+  local yaml="$1/stub.yaml"
+  [ -f "$yaml" ] && stub_yaml_value tier "$yaml" 2>/dev/null || echo "experimental"
+}
+
+is_allowed_tier() {
+  local src="$1"
+  [ "$INCLUDE_EXPERIMENTAL" -eq 1 ] && return 0
+  local tier
+  tier="$(stub_tier "$src")"
+  [ "$tier" != "experimental" ]
+}
+
+stub_type() {
+  local yaml="$1/stub.yaml"
+  if [ -f "$yaml" ]; then
+    local t
+    t="$(stub_yaml_value type "$yaml")"
+    echo "${t:-skill}"
+  else
+    echo "skill"
+  fi
+}
+
+raw_url_from_stub() {
+  # Derive raw GitHub URL from stub.yaml fields
+  local yaml="$1"
+  local upstream upstream_path version repo branch
+  upstream="$(stub_yaml_value upstream "$yaml")"
+  upstream_path="$(stub_yaml_value upstream_path "$yaml")"
+  version="$(stub_yaml_value version "$yaml")"
+  repo="$(echo "$upstream" | sed 's|https://github.com/||')"
+  branch="$([ "$version" = "latest" ] && echo "main" || echo "$version")"
+  echo "https://raw.githubusercontent.com/$repo/$branch/$upstream_path"
+}
+
+is_stub() {
+  # Stub = SKILL.md still has das: frontmatter block
+  local md="$1/SKILL.md"
+  [ -f "$md" ] && grep -q "^das:" "$md"
+}
+
+has_stub_manifest() {
+  [ -f "$1/stub.yaml" ]
+}
+
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
+
+lockfile_sha() {
+  # $1=skill — returns stored sha256 from lockfile, empty if not found
+  [ -f "$LOCKFILE" ] || return
+  awk -v s="$1" -F'\t' 'NF>=2 && $1==s { print $2; exit }' "$LOCKFILE"
+}
+
+lockfile_upsert() {
+  # $1=skill  $2=sha256  $3=upstream_url
+  local skill="$1" sha="$2" url="$3"
+  local ts
+  ts="$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u)"
+  local tmp
+  tmp="$(mktemp)"
+  # Copy header and all lines except existing entry for this skill
+  if [ -f "$LOCKFILE" ]; then
+    grep -v "^${skill}	" "$LOCKFILE" > "$tmp" || true
+  else
+    printf '# design-agent-skills.lock — generated by install.sh\n' >> "$tmp"
+    printf '# skill\tsha256\tupstream\tlocked_at\n' >> "$tmp"
+  fi
+  printf '%s\t%s\t%s\t%s\n' "$skill" "$sha" "$url" "$ts" >> "$tmp"
+  mv "$tmp" "$LOCKFILE"
+}
+
+skill_state() {
+  local target="$1" src="$2"
+  local stype
+  stype="$(stub_type "$src")"
+  if [ "$stype" = "package" ] || [ "$stype" = "platform" ]; then
+    local yaml="$src/stub.yaml"
+    local skills_dir
+    skills_dir="$(dirname "$target")"
+    # Check for block-list installed_as first
+    local list_items
+    list_items="$(stub_yaml_list installed_as "$yaml" 2>/dev/null || true)"
+    if [ -n "$list_items" ]; then
+      local total=0 found=0
+      while IFS= read -r item; do
+        total=$((total + 1))
+        local t="$skills_dir/$item"
+        if [ -d "$t" ] && ! grep -q "^das:" "$t/SKILL.md" 2>/dev/null; then
+          found=$((found + 1))
+        fi
+      done <<< "$list_items"
+      if [ "$found" -eq 0 ]; then
+        echo "package"
+      elif [ "$found" -eq "$total" ]; then
+        echo "installed"
+      else
+        echo "${found}/${total}"
+      fi
+      return
+    fi
+    # Scalar installed_as
+    local installed_as
+    installed_as="$(stub_yaml_value installed_as "$yaml" 2>/dev/null || true)"
+    [ -z "$installed_as" ] && installed_as="$(basename "$src")"
+    local installed_target="$skills_dir/$installed_as"
+    if [ -d "$installed_target" ] && ! grep -q "^das:" "$installed_target/SKILL.md" 2>/dev/null; then
+      echo "installed"
+    else
+      echo "package"
+    fi
+    return
+  fi
+  if [ -L "$target" ] && [ ! -e "$target" ]; then
+    echo "BROKEN"
+  elif [ -L "$target" ] && is_stub "$src"; then
+    echo "stub"
+  elif [ -L "$target" ]; then
+    echo "upgraded"
+  elif [ -d "$target" ]; then
+    is_stub "$target" && echo "stub" || echo "upgraded"
+  else
+    echo "-"
+  fi
+}
+
+skill_names() {
+  for d in "$SKILLS_SRC"/*/; do
+    [ -d "$d" ] && basename "${d%/}"
+  done
+}
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+cmd_install() {
+  local agent_list
+  agent_list="$(detected_agents)"
+  [ -z "$agent_list" ] && { echo "No supported agents found."; exit 0; }
+
+  while IFS=: read -r name _root skills_dir; do
+    mkdir -p "$skills_dir"
+    local linked=0 skipped=0
+    while IFS= read -r skill; do
+      local target="$skills_dir/$skill"
+      local stype
+      stype="$(stub_type "$SKILLS_SRC/$skill")"
+      if [ "$stype" = "skill" ] || [ "$stype" = "navigator" ]; then
+        if ! is_allowed_tier "$SKILLS_SRC/$skill"; then
+          skipped=$((skipped + 1))
+        elif [ -L "$target" ] || [ -d "$target" ]; then
+          skipped=$((skipped + 1))
+        else
+          ln -s "$SKILLS_SRC/$skill" "$target"
+          linked=$((linked + 1))
+        fi
+      else
+        skipped=$((skipped + 1))
+      fi
+    done < <(skill_names)
+    printf "  %-12s  +%d linked  %d skipped\n" "$name" "$linked" "$skipped"
+  done <<< "$agent_list"
+
+  echo
+  if [ "$INCLUDE_EXPERIMENTAL" -eq 0 ]; then
+    printf "scope: %s  |  experimental skills skipped (add --include-experimental to install all)\n" "$SCOPE"
+  else
+    printf "scope: %s  |  run './install.sh status' to inspect states.\n" "$SCOPE"
+  fi
+
+  # Warn about user-scope-only agents when running project scope
+  if [ "$SCOPE" = "project" ]; then
+    local skipped_agents=""
+    for _entry in "codex:$HOME/.codex" "droid:$HOME/.factory"; do
+      local _aname _aroot
+      IFS=: read -r _aname _aroot <<< "$_entry"
+      [ -d "$_aroot" ] && skipped_agents="${skipped_agents:+$skipped_agents, }$_aname"
+    done
+    if [ -n "$skipped_agents" ]; then
+      printf "note: %s detected but not linked (user-scope only) — omit --scope=project to include.\n" "$skipped_agents"
+    fi
+  fi
+}
+
+cmd_status() {
+  local agent_list
+  agent_list="$(detected_agents)"
+  [ -z "$agent_list" ] && { echo "No supported agents found."; exit 0; }
+
+  local names=() dirs=()
+  while IFS=: read -r name _root skills_dir; do
+    names+=("$name")
+    dirs+=("$skills_dir")
+  done <<< "$agent_list"
+
+  local ncols=${#names[@]}
+
+  printf "\n%-22s  %-4s" "skill" "tier"
+  for name in "${names[@]}"; do printf "  %-10s" "$name"; done
+  echo
+
+  printf "%-22s  %-4s" "──────────────────────" "────"
+  for _ in "${names[@]}"; do printf "  %-10s" "──────────"; done
+  echo
+
+  while IFS= read -r skill; do
+    local src="$SKILLS_SRC/$skill"
+    local tier_char
+    case "$(stub_tier "$src")" in
+      official)     tier_char="O" ;;
+      community)    tier_char="C" ;;
+      experimental) tier_char="E" ;;
+      *)            tier_char="?" ;;
+    esac
+    printf "%-22s  %-4s" "$skill" "$tier_char"
+    local i=0
+    while [ $i -lt $ncols ]; do
+      local target="${dirs[$i]}/$skill"
+      printf "  %-10s" "$(skill_state "$target" "$src")"
+      i=$((i + 1))
+    done
+    echo
+  done < <(skill_names)
+
+  echo
+  printf "scope: %s\n" "$SCOPE"
+  echo "tier: O=official  C=community  E=experimental"
+  echo "stub=pending  upgraded=full  installed=package installed  package=not installed  BROKEN=run fix"
+  echo
+}
+
+cmd_update() {
+  local dry_run=0 frozen=0
+  for arg in "$@"; do
+    case "$arg" in
+      --dry-run) dry_run=1 ;;
+      --frozen)  frozen=1  ;;
+    esac
+  done
+
+  if [ "$frozen" -eq 1 ] && [ ! -f "$LOCKFILE" ]; then
+    echo "Error: --frozen requires a lockfile. Run './install.sh lock' first."
+    exit 1
+  fi
+
+  local agent_list
+  agent_list="$(detected_agents)"
+  local refreshed=0 linked=0 shown=0
+
+  [ "$dry_run" -eq 1 ] && echo "(dry run — no changes will be made)"
+  echo
+
+  while IFS= read -r skill; do
+    local src="$SKILLS_SRC/$skill"
+    local yaml="$src/stub.yaml"
+
+    # Package/platform types — print install command instead of symlinking
+    local stype
+    stype="$(stub_type "$src")"
+    if [ "$stype" = "package" ] || [ "$stype" = "platform" ]; then
+      local install_cmd
+      install_cmd="$(stub_yaml_value install_default "$yaml" 2>/dev/null || true)"
+      if [ -n "$install_cmd" ]; then
+        printf "  package  %-18s  run: %s\n" "$skill" "$install_cmd"
+        shown=$((shown + 1))
+      fi
+      continue
+    fi
+
+    # Upgraded stub with manifest → re-fetch from upstream
+    if has_stub_manifest "$src" && ! is_stub "$src"; then
+      local url
+      url="$(raw_url_from_stub "$yaml")"
+      if [ "$dry_run" -eq 1 ]; then
+        printf "  would refresh  %s  ←  %s\n" "$skill" "$url"
+        refreshed=$((refreshed + 1))
+      elif [ "$frozen" -eq 1 ]; then
+        local locked_sha current_sha
+        locked_sha="$(lockfile_sha "$skill")"
+        current_sha="$(sha256_file "$src/SKILL.md" 2>/dev/null || true)"
+        if [ -n "$locked_sha" ] && [ "$current_sha" != "$locked_sha" ]; then
+          printf "  DRIFT  %s — content changed since lockfile was written\n" "$skill"
+        fi
+        # Skip re-fetch; keep current content
+      else
+        # Backup before overwrite
+        cp "$src/SKILL.md" "$src/SKILL.md.bak" 2>/dev/null || true
+        printf "  updating  %s ... " "$skill"
+        local upstream_url
+        upstream_url="$(stub_yaml_value upstream "$yaml" 2>/dev/null || true)"
+        if curl -fsSL "$url" -o "$src/SKILL.md" 2>/dev/null; then
+          echo "ok"
+          refreshed=$((refreshed + 1))
+          # Record in lockfile
+          local new_sha
+          new_sha="$(sha256_file "$src/SKILL.md" 2>/dev/null || true)"
+          [ -n "$new_sha" ] && lockfile_upsert "$skill" "$new_sha" "$upstream_url"
+        else
+          # Restore backup on failure
+          mv "$src/SKILL.md.bak" "$src/SKILL.md" 2>/dev/null || true
+          echo "failed (upstream unreachable — backup restored)"
+        fi
+      fi
+      continue
+    fi
+
+    # New stub not yet linked to all agents → add missing links (respects tier filter)
+    [ "$stype" = "skill" ] || [ "$stype" = "navigator" ] || continue
+    is_allowed_tier "$src" || continue
+    while IFS=: read -r name _root skills_dir; do
+      local target="$skills_dir/$skill"
+      if [ ! -L "$target" ] && [ ! -d "$target" ]; then
+        if [ "$dry_run" -eq 1 ]; then
+          printf "  would link  %-18s  →  %s\n" "$skill" "$name"
+        else
+          mkdir -p "$skills_dir"
+          ln -s "$src" "$target"
+          printf "  added  %-18s  %s\n" "$skill" "$name"
+        fi
+        linked=$((linked + 1))
+      fi
+    done <<< "$agent_list"
+
+  done < <(skill_names)
+
+  if [ "$refreshed" -eq 0 ] && [ "$linked" -eq 0 ] && [ "$shown" -eq 0 ]; then
+    echo "Nothing to update."
+  else
+    if [ "$dry_run" -eq 1 ]; then
+      [ "$refreshed" -gt 0 ] && echo "$refreshed skill(s) would be refreshed from upstream."
+      [ "$linked" -gt 0 ]    && echo "$linked new link(s) would be added."
+      [ "$shown" -gt 0 ]     && echo "$shown package install command(s) shown."
+    else
+      [ "$refreshed" -gt 0 ] && echo "$refreshed skill(s) refreshed from upstream."
+      [ "$linked" -gt 0 ]    && echo "$linked new link(s) added."
+      [ "$shown" -gt 0 ]     && echo "$shown package install command(s) shown."
+    fi
+  fi
+}
+
+cmd_fix() {
+  local agent_list
+  agent_list="$(detected_agents)"
+  local fixed=0
+
+  while IFS=: read -r _name _root skills_dir; do
+    [ -d "$skills_dir" ] || continue
+    for target in "$skills_dir"/*/; do
+      target="${target%/}"
+      [ -L "$target" ] || continue
+      if [ ! -e "$target" ]; then
+        rm "$target"
+        printf "  removed broken link: %s\n" "$target"
+        fixed=$((fixed + 1))
+      fi
+    done
+  done <<< "$agent_list"
+
+  [ "$fixed" -eq 0 ] && echo "No broken links found." || echo "Fixed $fixed broken link(s)."
+}
+
+cmd_lock() {
+  echo "Generating lockfile: $LOCKFILE"
+  local tmp
+  tmp="$(mktemp)"
+  printf '# design-agent-skills.lock — generated by install.sh\n' > "$tmp"
+  printf '# skill\tsha256\tupstream\tlocked_at\n' >> "$tmp"
+
+  local ts locked=0
+  ts="$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u)"
+
+  while IFS= read -r skill; do
+    local src="$SKILLS_SRC/$skill"
+    local md="$src/SKILL.md"
+    local yaml="$src/stub.yaml"
+    [ -f "$md" ] || continue
+    is_stub "$src" && continue  # only lock upgraded (non-stub) skills
+    local sha upstream
+    sha="$(sha256_file "$md")"
+    upstream="$(stub_yaml_value upstream "$yaml" 2>/dev/null || true)"
+    printf '%s\t%s\t%s\t%s\n' "$skill" "$sha" "$upstream" "$ts" >> "$tmp"
+    echo "  locked  $skill"
+    locked=$((locked + 1))
+  done < <(skill_names)
+
+  mv "$tmp" "$LOCKFILE"
+  if [ "$locked" -eq 0 ]; then
+    echo "No upgraded skills found — lockfile written (empty)."
+  else
+    printf "%d skill(s) locked.\n" "$locked"
+  fi
+}
+
+cmd_doctor() {
+  local strict=0 show_substr=0
+  for arg in "$@"; do
+    case "$arg" in
+      --strict) strict=1 ;;
+      --substr) show_substr=1 ;;
+    esac
+  done
+
+  local tmp
+  tmp="$(mktemp)"
+
+  local skill_count
+  skill_count=$(skill_names | wc -l | tr -d ' ')
+  printf "Scanning %d skills for trigger collisions...\n\n" "$skill_count"
+
+  # Collect (trigger TAB skill) pairs into temp file
+  while IFS= read -r skill; do
+    local md="$SKILLS_SRC/$skill/SKILL.md"
+    [ -f "$md" ] || continue
+    awk -v skill="$skill" '
+      BEGIN { in_front=0; in_trig=0 }
+      /^---$/ { if(in_front==0){in_front=1}else{exit}; next }
+      in_front && /^triggers:/ { in_trig=1; next }
+      in_front && in_trig && /^[[:space:]]*-[[:space:]]/ {
+        line=$0; sub(/^[[:space:]]*-[[:space:]]+/,"",line); gsub(/"/,"",line)
+        print line "\t" skill; next
+      }
+      in_front && in_trig && /^[^[:space:]]/ { in_trig=0 }
+    ' "$md"
+  done < <(skill_names) > "$tmp"
+
+  local issues=0
+
+  # ── Exact collisions ─────────────────────────────────────────────────────────
+  local exact_out
+  exact_out=$(sort "$tmp" | awk -F'\t' '
+    {
+      key=$1; skill=$2
+      if (key != prev_key) {
+        if (cnt > 1) print prev_key "\t" list
+        prev_key=key; list=skill; cnt=1
+      } else { list=list ", " skill; cnt++ }
+    }
+    END { if (cnt > 1) print prev_key "\t" list }
+  ')
+
+  if [ -n "$exact_out" ]; then
+    local exact_count
+    exact_count=$(printf '%s\n' "$exact_out" | grep -c . || true)
+    printf "Exact trigger collisions (%d):\n" "$exact_count"
+    printf '%s\n' "$exact_out" | awk -F'\t' '{ printf "  %-34s → %s\n", "\"" $1 "\"", $2 }'
+    echo
+    issues=$((issues + exact_count))
+  fi
+
+  # ── Substring overlaps (opt-in via --substr) ──────────────────────────────────
+  if [ "$show_substr" -eq 1 ]; then
+    local substr_out
+    substr_out=$(cut -f1 "$tmp" | sort -u | awk '
+      { t[NR]=$0 }
+      END {
+        n=NR
+        for(i=1;i<=n;i++) for(j=1;j<=n;j++) {
+          if(i!=j && index(t[i],t[j])>0 && length(t[j])<length(t[i]))
+            printf "%s\t%s\n", t[j], t[i]
+        }
+      }
+    ' | sort -u)
+
+    if [ -n "$substr_out" ]; then
+      local substr_count
+      substr_count=$(printf '%s\n' "$substr_out" | grep -c . || true)
+      printf "Substring overlaps — shorter trigger subsumed by longer (%d):\n" "$substr_count"
+      printf '%s\n' "$substr_out" | awk -F'\t' '{ printf "  %-20s  ⊇  %s\n", "\"" $1 "\"", "\"" $2 "\"" }'
+      echo
+      issues=$((issues + substr_count))
+    fi
+  fi
+
+  rm -f "$tmp"
+
+  # ── Symlink fragility scan ──────────────────────────────────────────────────
+  local orphaned=0 relocated=0
+  while IFS=: read -r _name _root skills_dir; do
+    [ -d "$skills_dir" ] || continue
+    while IFS= read -r link; do
+      [ -L "$link" ] || continue
+      local target
+      target="$(readlink "$link")"
+      if [ ! -e "$link" ]; then
+        orphaned=$((orphaned + 1))
+      elif [ "${target#"$SKILLS_SRC"}" = "$target" ]; then
+        relocated=$((relocated + 1))
+      fi
+    done < <(find "$skills_dir" -maxdepth 1 -type l 2>/dev/null)
+  done < <(detected_agents)
+
+  if [ "$orphaned" -gt 0 ]; then
+    printf "BROKEN     %d orphaned symlink(s) — target missing (repo moved?).\n" "$orphaned"
+    printf "           Run: ./install.sh fix && ./install.sh install\n\n"
+    issues=$((issues + orphaned))
+  fi
+  if [ "$relocated" -gt 0 ]; then
+    printf "RELOCATED  %d symlink(s) point outside current install dir.\n" "$relocated"
+    printf "           Likely caused by moving the repo. Run: ./install.sh fix && ./install.sh install\n\n"
+    issues=$((issues + relocated))
+  fi
+  if [ "$orphaned" -eq 0 ] && [ "$relocated" -eq 0 ]; then
+    echo "Symlinks OK — all links resolve inside current install dir."
+  fi
+
+  echo
+  if [ "$issues" -eq 0 ]; then
+    echo "All checks OK — no issues found."
+  else
+    printf "%d issue(s) found.\n" "$issues"
+    if [ "$strict" -eq 1 ]; then
+      echo "Exiting 1 (--strict)."
+      exit 1
+    fi
+  fi
+}
+
+cmd_remove() {
+  local skill="${1:-}"
+  if [ -z "$skill" ]; then
+    echo "Usage: ./install.sh remove <skill-name>"
+    echo "       ./install.sh remove --all"
+    exit 1
+  fi
+
+  local agent_list
+  agent_list="$(detected_agents)"
+  local removed=0
+
+  if [ "$skill" = "--all" ]; then
+    while IFS=: read -r _name _root skills_dir; do
+      [ -d "$skills_dir" ] || continue
+      while IFS= read -r sk; do
+        local target="$skills_dir/$sk"
+        [ -L "$target" ] || continue
+        rm "$target"
+        printf "  removed: %s\n" "$target"
+        removed=$((removed + 1))
+      done < <(skill_names)
+    done <<< "$agent_list"
+    printf "%d link(s) removed.\n" "$removed"
+    return
+  fi
+
+  if [ ! -d "$SKILLS_SRC/$skill" ]; then
+    echo "Unknown skill: $skill"
+    echo "Run './install.sh status' to see available skills."
+    exit 1
+  fi
+
+  while IFS=: read -r name _root skills_dir; do
+    local target="$skills_dir/$skill"
+    if [ -L "$target" ] || [ -d "$target" ]; then
+      rm -rf "$target"
+      printf "  removed from %s\n" "$name"
+      removed=$((removed + 1))
+    fi
+  done <<< "$agent_list"
+
+  [ "$removed" -eq 0 ] \
+    && echo "No links found for: $skill" \
+    || printf "%d link(s) removed.\n" "$removed"
+}
+
+cmd_help() {
+  cat <<HELP
+Usage: ./install.sh [flags] [command]
+
+Global flags:
+  --scope=user              Link to agent user-level dirs (default): ~/.claude/skills/
+  --scope=project           Link to project-level dirs: ./.claude/skills/
+  --include-experimental    Also install experimental-tier skills (default: official+community only)
+
+Commands:
+  install          Symlink all stubs to detected agents (default)
+  status           Show stub / upgraded / installed / BROKEN state per agent
+  update           Re-fetch upgraded skills from upstream; add links for new stubs
+    --dry-run        Show what would change without making any changes
+    --frozen         Skip re-fetching; warn if content has drifted from lockfile
+  lock             Generate design-agent-skills.lock from current upgraded skill state
+  fix              Remove broken symlinks
+  remove <skill>   Remove a specific skill's links from all agents
+  remove --all     Remove all skill links (uninstall)
+  doctor           Scan for trigger collisions and orphaned/relocated symlinks
+    --strict         Exit 1 if any issues found (useful for CI)
+    --substr         Also report substring overlaps (broad triggers subsuming narrow ones)
+  help             Show this message
+
+Skill tiers:  official (28)  community (35)  experimental (60)
+User-scope agents:  claude  cursor  codex  opencode  droid
+Project-scope agents: claude  cursor  opencode
+HELP
+}
+
+# ── Entry ─────────────────────────────────────────────────────────────────────
+CMD="${1:-install}"
+shift 2>/dev/null || true
+case "$CMD" in
+  install) cmd_install ;;
+  status)  cmd_status  ;;
+  update)  cmd_update  "$@" ;;
+  fix)     cmd_fix        ;;
+  remove)  cmd_remove "$@" ;;
+  lock)    cmd_lock       ;;
+  doctor)  cmd_doctor  "$@" ;;
+  help|-h) cmd_help ;;
+  *) echo "Unknown command: $CMD"; cmd_help; exit 1 ;;
+esac