upskill

#!/usr/bin/env bash
set -Eeo pipefail
IFS=$'\n\t'

PROGRAM_NAME="upskill"
VERSION="0.1.0"

usage() {
  cat <<USAGE
${PROGRAM_NAME} ${VERSION}
Install Agent Skills from another GitHub repository.
Implements the agentskills.io specification: https://agentskills.io

Usage:
  ${PROGRAM_NAME} [-i] [-g] <owner/repo> [-b <branch>] [--dest-path <path>] [--list] [--skill <name>] [--all]

Examples:
  ${PROGRAM_NAME} anthropics/skills --list
  ${PROGRAM_NAME} anthropics/skills --skill pdf --skill xlsx
  ${PROGRAM_NAME} anthropics/skills --all
  ${PROGRAM_NAME} -g anthropics/skills --skill pdf  # Install to ~/.skills
  ${PROGRAM_NAME} anthropics/skills --dest-path .claude/skills  # Custom destination

Options:
  -i                        Add created files to .gitignore
  -g, --global              Install skills to ~/.skills (personal skills)
  -b, --branch <branch>     Branch, tag, or commit to clone (default: repo default)
  --dest-path <path>        Custom destination path for skills (overrides -g)
  --list                    List available skills without installing
  --skill <name>            Install specific skill(s) (can be used multiple times)
  --all                     Install all skills from SKILL.md files
  -q, --quiet               Reduce output
  -h, --help                Show help
  -v, --version             Show version

Note: Skills are discovered by scanning for **/SKILL.md files per the agentskills.io spec.
      Your agent likely already supports this spec natively - this tool may not be needed.
USAGE
}

log() {
  if [[ -z "${QUIET:-}" ]]; then
    printf '%s\n' "$*" >&2
  fi
}

die() {
  printf 'Error: %s\n' "$*" >&2
  exit 1
}

require_cmd() {
  command -v "$1" >/dev/null 2>&1 || die "Required command not found: $1"
}

cleanup() {
  if [[ -n "${_UPS_TMPDIR:-}" && -d "${_UPS_TMPDIR}" ]]; then
    rm -rf "${_UPS_TMPDIR}" || true
  fi
}
trap cleanup EXIT

insert_or_replace_block() {
  # $1: target file
  # $2: start marker
  # $3: end marker
  # stdin: block content (without markers)
  local file="$1"; shift
  local start_marker="$1"; shift
  local end_marker="$1"; shift

  local block tmp blockfile
  block=$(cat)

  if [[ ! -f "$file" ]]; then
    printf '%s\n\n%s\n%s\n%s\n' "# AGENTS.md" "$start_marker" "$block" "$end_marker" >"$file"
    return 0
  fi

  if grep -qF "$start_marker" "$file" && grep -qF "$end_marker" "$file"; then
    tmp=$(mktemp)
    blockfile=$(mktemp)
    printf '%s\n' "$block" >"$blockfile"
    awk -v start="$start_marker" -v end="$end_marker" -v fblock="$blockfile" '
      BEGIN{skip=0}
      $0 ~ start {
        print $0
        # print replacement content
        cmd = "cat " fblock
        while ((cmd | getline line) > 0) print line
        close(cmd)
        skip=1
        next
      }
      $0 ~ end && skip==1 { print $0; skip=0; next }
      skip==1 { next }
      { print $0 }
    ' "$file" >"$tmp"
    mv "$tmp" "$file"
    rm -f "$blockfile"
  else
    {
      printf '\n%s\n' "$start_marker"
      printf '%s\n' "$block"
      printf '%s\n' "$end_marker"
    } >>"$file"
  fi
}

generate_discover_skills() {
  cat <<'SCRIPT'
#!/usr/bin/env bash
set -Eo pipefail
IFS=$'\n\t'

# Discover available skills in both project and global directories
# Usage: .agents/discover-skills

PROJECT_SKILLS_DIR=".skills"
PROJECT_SKILLS_DIR_LEGACY=".claude/skills"
GLOBAL_SKILLS_DIR="$HOME/.skills"
GLOBAL_SKILLS_DIR_LEGACY="$HOME/.claude/skills"

process_skills_directory() {
  local skills_dir="$1"
  local location_label="$2"

  if [[ ! -d "$skills_dir" ]]; then
    return 0
  fi

  local count=0
  # Count skills first
  while IFS= read -r -d '' skill_file; do
    count=$((count + 1))
  done < <(find "$skills_dir" -type f -name 'SKILL.md' -print0)

  if [[ $count -eq 0 ]]; then
    return 0
  fi

  echo "$location_label ($count skill(s)):"
  # Generate underline matching label length
  local len=${#location_label}
  if [[ $len -gt 0 ]]; then
    local underline=""
    for ((i=0; i<len; i++)); do
      underline+="="
    done
    echo "$underline"
  fi
  echo ""

  # Iterate SKILL.md files robustly (handles spaces)
  while IFS= read -r -d '' skill_file; do
    skill_dir=$(dirname "$skill_file")
    skill_name=$(basename "$skill_dir")

    # Check for YAML frontmatter
    if head -n 1 "$skill_file" | grep -q "^---$"; then
      # Extract lines between first pair of --- delimiters
      frontmatter=$(awk 'BEGIN{inside=0; c=0} /^---$/ {inside=!inside; if(++c==3) exit} inside==1 {print}' "$skill_file")
      name=$(printf '%s\n' "$frontmatter" | awk -F': *' '/^name:/ {sub(/^name: */,"",$0); print substr($0, index($0,$2))}' 2>/dev/null)
      description=$(printf '%s\n' "$frontmatter" | awk -F': *' '/^description:/ {sub(/^description: */,"",$0); print substr($0, index($0,$2))}' 2>/dev/null)

      echo "Skill: ${name:-$skill_name}"
      echo "Path: $skill_file"
      if [[ -n "$description" ]]; then
        echo "Description: $description"
      fi
    else
      echo "Skill: $skill_name"
      echo "Path: $skill_file"
      echo "Description:"
      head -n 5 "$skill_file"
    fi

    echo ""
    echo "---"
    echo ""
  done < <(find "$skills_dir" -type f -name 'SKILL.md' -print0)
}

echo "Available Skills:"
echo "=================="
echo ""

# Check project skills (new location first, then legacy)
process_skills_directory "$PROJECT_SKILLS_DIR" "Project Skills (.skills)"
process_skills_directory "$PROJECT_SKILLS_DIR_LEGACY" "Project Skills (.claude/skills - legacy)"

# Check global skills (new location first, then legacy)
process_skills_directory "$GLOBAL_SKILLS_DIR" "Personal Skills (~/.skills)"
process_skills_directory "$GLOBAL_SKILLS_DIR_LEGACY" "Personal Skills (~/.claude/skills - legacy)"

# If no skills found at all
if [[ ! -d "$PROJECT_SKILLS_DIR" && ! -d "$PROJECT_SKILLS_DIR_LEGACY" && ! -d "$GLOBAL_SKILLS_DIR" && ! -d "$GLOBAL_SKILLS_DIR_LEGACY" ]]; then
  echo "No skills directories found."
  echo "- Project skills: $PROJECT_SKILLS_DIR (or $PROJECT_SKILLS_DIR_LEGACY)"
  echo "- Personal skills: $GLOBAL_SKILLS_DIR (or $GLOBAL_SKILLS_DIR_LEGACY)"
fi
SCRIPT
}

copy_tree() {
  # $1: src dir, $2: dest dir
  local src="$1" dest="$2"
  if command -v rsync >/dev/null 2>&1; then
    rsync -a "$src/" "$dest/"
  else
    tar -C "$src" -cf - . | tar -C "$dest" -xpf -
  fi
}

discover_skill_files() {
  # $1: directory to search
  # Outputs: skill_name|skill_path pairs, one per line
  local search_dir="$1"

  while IFS= read -r -d '' skill_file; do
    local skill_dir skill_name name description
    skill_dir=$(dirname "$skill_file")
    skill_name=$(basename "$skill_dir")

    # Try to extract name from YAML frontmatter
    if head -n 1 "$skill_file" | grep -q "^---$"; then
      frontmatter=$(awk 'BEGIN{inside=0; c=0} /^---$/ {inside=!inside; if(++c==3) exit} inside==1 {print}' "$skill_file")
      name=$(printf '%s\n' "$frontmatter" | awk -F': *' '/^name:/ {sub(/^name: */,"",$0); print substr($0, index($0,$2))}' 2>/dev/null)
      description=$(printf '%s\n' "$frontmatter" | awk -F': *' '/^description:/ {sub(/^description: */,"",$0); print substr($0, index($0,$2))}' 2>/dev/null)
    fi

    # Output: skill_name|skill_path|description
    printf '%s|%s|%s\n' "${name:-$skill_name}" "$skill_file" "$description"
  done < <(find "$search_dir" -type f -name 'SKILL.md' -print0)
}

list_skills() {
  # $1: directory to search
  # $2: optional repo name for examples
  local search_dir="$1"
  local repo="${2:-<repo>}"

  # ANSI color codes
  local bold='\033[1m'
  local cyan='\033[36m'
  local reset='\033[0m'

  echo "Available skills in repository:"
  echo "==============================="
  echo ""

  local count=0
  local -a skill_names=()
  while IFS='|' read -r name path description; do
    count=$((count + 1))
    skill_names+=("$name")

    # Make path relative to search_dir
    local rel_path="${path#"$search_dir"/}"

    # Bold skill name, cyan relative path in parentheses
    printf "${bold}%s${reset} ${cyan}(%s)${reset}\n" "$name" "$rel_path"

    # Description on next line if present
    if [[ -n "$description" ]]; then
      echo "$description"
    fi
    echo ""
  done < <(discover_skill_files "$search_dir")

  if [[ $count -eq 0 ]]; then
    echo "No SKILL.md files found in $search_dir"
    return 1
  fi

  echo "Found $count skill(s)"
  echo ""
  echo "To install specific skills:"
  # Use first two skills in example if available
  if [[ ${#skill_names[@]} -ge 2 ]]; then
    echo "  $PROGRAM_NAME $repo --skill ${skill_names[0]} --skill ${skill_names[1]}"
  elif [[ ${#skill_names[@]} -eq 1 ]]; then
    echo "  $PROGRAM_NAME $repo --skill ${skill_names[0]}"
  else
    echo "  $PROGRAM_NAME $repo --skill <name> [--skill <name> ...]"
  fi
  echo ""
  echo "To install all skills:"
  echo "  $PROGRAM_NAME $repo --all"
}

copy_skill() {
  # $1: skill file path, $2: destination skills dir
  local skill_file="$1"
  local dest_dir="$2"
  local skill_dir skill_name

  skill_dir=$(dirname "$skill_file")
  skill_name=$(basename "$skill_dir")

  log "Installing skill: $skill_name"

  # Copy the entire skill directory
  mkdir -p "$dest_dir/$skill_name"
  copy_tree "$skill_dir" "$dest_dir/$skill_name"
}

main() {
  local repo=""
  local branch=""
  local dest_path=""
  local add_to_gitignore=""
  local list_only=""
  local install_all=""
  local global_install=""
  local -a selected_skills=()

  while [[ $# -gt 0 ]]; do
    case "$1" in
      -h|--help) usage; exit 0 ;;
      -v|--version) echo "$PROGRAM_NAME $VERSION"; exit 0 ;;
      -q|--quiet) QUIET=1; shift ;;
      -i) add_to_gitignore=1; shift ;;
      -g|--global) global_install=1; shift ;;
      -b|--branch) branch="$2"; shift 2 ;;
      --dest-path) dest_path="$2"; shift 2 ;;
      --list) list_only=1; shift ;;
      --all) install_all=1; shift ;;
      --skill) selected_skills+=("$2"); shift 2 ;;
      -*) die "Unknown option: $1" ;;
      *) repo="$1"; shift ;;
    esac
  done

  [[ -n "$repo" ]] || { usage; die "Missing required <owner/repo>"; }

  # Validate mutually exclusive options
  if [[ -n "$list_only" && -n "$install_all" ]]; then
    die "--list and --all are mutually exclusive"
  fi
  if [[ -n "$list_only" && ${#selected_skills[@]} -gt 0 ]]; then
    die "--list and --skill are mutually exclusive"
  fi
  if [[ -n "$install_all" && ${#selected_skills[@]} -gt 0 ]]; then
    die "--all and --skill are mutually exclusive"
  fi

  require_cmd gh
  require_cmd git
  require_cmd awk
  require_cmd sed
  require_cmd tar

  _UPS_TMPDIR=$(mktemp -d)
  log "Created temp dir: $_UPS_TMPDIR"

  local clone_dir
  clone_dir="$_UPS_TMPDIR/src"

  if [[ -n "$branch" ]]; then
    log "Cloning $repo (branch: $branch) ..."
    gh repo clone "$repo" "$clone_dir" -- -b "$branch" >/dev/null
  else
    log "Cloning $repo ..."
    gh repo clone "$repo" "$clone_dir" >/dev/null
  fi

  # Scan for all SKILL.md files (per agentskills.io spec)
  log "Scanning for SKILL.md files..."
  local tmpfile
  tmpfile=$(mktemp)
  discover_skill_files "$clone_dir" >"$tmpfile"

  if [[ ! -s "$tmpfile" ]]; then
    rm -f "$tmpfile"
    die "No skills found in repository (no SKILL.md files)"
  fi

  local total_count
  total_count=$(wc -l <"$tmpfile" | tr -d ' ')
  log "Found $total_count skill(s)"

  # Handle --list flag
  if [[ -n "$list_only" ]]; then
    list_skills "$clone_dir" "$repo"
    rm -f "$tmpfile"
    exit 0
  fi

  # Determine destination: --dest-path > --global > default (.skills)
  local dest_skills_dir
  if [[ -n "$dest_path" ]]; then
    dest_skills_dir="$dest_path"
    log "Installing skills to custom path: $dest_skills_dir"
  elif [[ -n "$global_install" ]]; then
    dest_skills_dir="$HOME/.skills"
    log "Installing skills globally to $dest_skills_dir"
  else
    dest_skills_dir=".skills"
  fi
  mkdir -p "$dest_skills_dir"

  # Install skills
  local skill_count=0

  if [[ -n "$install_all" ]]; then
    log "Installing all $total_count skills..."
    while IFS='|' read -r name path description; do
      copy_skill "$path" "$dest_skills_dir"
      skill_count=$((skill_count + 1))
    done <"$tmpfile"
  elif [[ ${#selected_skills[@]} -gt 0 ]]; then
    log "Installing ${#selected_skills[@]} selected skill(s)..."
    for skill_name in "${selected_skills[@]}"; do
      local found=""
      while IFS='|' read -r name path description; do
        if [[ "$name" == "$skill_name" ]]; then
          copy_skill "$path" "$dest_skills_dir"
          skill_count=$((skill_count + 1))
          found=1
          break
        fi
      done <"$tmpfile"
      if [[ -z "$found" ]]; then
        rm -f "$tmpfile"
        die "Skill not found: $skill_name (use --list to see available skills)"
      fi
    done
  else
    # No flags - show available skills and prompt
    list_skills "$clone_dir" "$repo"
    echo ""
    rm -f "$tmpfile"
    die "Please specify which skills to install using --skill or --all"
  fi

  rm -f "$tmpfile"
  log "Installed $skill_count skill(s)"

  # For local installs, write .agents/discover-skills and update AGENTS.md
  if [[ -z "$global_install" ]]; then
    # Write .agents/discover-skills
    mkdir -p .agents
    local discover
    discover=".agents/discover-skills"
    log "Updating $discover ..."
    generate_discover_skills >"$discover"
    chmod +x "$discover"

    # Extract Skills section from source AGENTS.md
    local src_agents
    src_agents="$clone_dir/AGENTS.md"
    if [[ -f "$src_agents" ]]; then
      log "Updating AGENTS.md skills section ..."
      local block
      block=$(awk '/^## Skills/{flag=1; print; next} /^## / && flag{exit} flag{print}' "$src_agents")
      if [[ -z "$block" ]]; then
        log "Warning: could not extract Skills section from $src_agents"
      else
        local start_marker end_marker
        start_marker='<!-- upskill:skills:start -->'
        end_marker='<!-- upskill:skills:end -->'
        insert_or_replace_block "AGENTS.md" "$start_marker" "$end_marker" <<<"$block"
      fi
    else
      log "Warning: AGENTS.md not found in source repo, skipping skills section"
    fi

    # Optionally append ignore rules
    if [[ -n "$add_to_gitignore" ]]; then
      local start_marker end_marker
      start_marker="# upskill:gitignore:start"
      end_marker="# upskill:gitignore:end"
      local block
      block=$(cat <<'EOB'
.skills/
.agents/discover-skills
EOB
)
      insert_or_replace_block ".gitignore" "$start_marker" "$end_marker" <<<"$block"
      log "Updated .gitignore with upskill block"
    fi
  fi

  log "Done."
}

main "$@"