refactor: unified setup.sh replaces sync-skills.sh

- Single script handles skills, agents, and instructions
- Works locally (cloned repo) and remotely (curl, no clone)
- Auto-generated manifests (agents.list, instructions.list)
- update-lists command regenerates manifests from directory contents
- Removed sync-skills.sh (folded into setup.sh)
- Rewrote assets README to be concise and actionable
- Updated all references in Agents.md and skills.md

Agents.md

@@ -76,8 +76,11 @@ If you update any file in this repo, commit and push right away so other develop
 This repo uses a skills manifest to standardize skills across developers.
 
 1. Review the curated list under assets/.
-2. Run ./assets/sync-skills.sh (uses the `npx skills` CLI).
+2. Run `./assets/setup.sh skills` (or `skills ios`, `skills android`).
-3. Restart your editor if needed.
+3. Run `./assets/setup.sh agents` to install agents.
+4. Run `./assets/setup.sh instructions` to install instructions.
+5. Or run `./assets/setup.sh all ios` to install everything at once.
+6. Restart your editor if needed.
 
 ## Suggested Agent Request Template
 - Goal: (one sentence)

assets/README.md

@@ -1,80 +1,97 @@
-# Assets (Staging)
+# AI Assets
 
-This folder stages non-guide assets for a future migration to a dedicated distribution repo.
+One script installs everything. No manual copy/paste. No cloning required.
 
-Contents:
+## Quick Start
-- agents/: Agent prompt files
-- instructions/: Repo-level instruction files
-- ios-skills.yaml, android-skills.yaml, shared-skills.yaml: Curated skills lists
-- sync-skills.sh: Installs skills from a curated list using the skills CLI
 
-Do not add handbook content here. Use docs/ai for the guide.
+### Option 1 — You Cloned This Repo
 
-## Install Skills (Platform Lists)
-Run the sync script with the list you want. Restart your editor if skills do not appear.
-
-### iOS
 ```bash
-SKILLS_FILE=./assets/ios-skills.yaml ./assets/sync-skills.sh
+# Install everything for iOS
+./assets/setup.sh all ios
+
+# Or pick what you need
+./assets/setup.sh skills ios
+./assets/setup.sh agents
+./assets/setup.sh instructions
 ```
 
-### Android
+### Option 2 — No Clone (Run Remotely)
+
+Point the script at the repo and run. Nothing to download first.
+
 ```bash
-SKILLS_FILE=./assets/android-skills.yaml ./assets/sync-skills.sh
+# Set the base URL once (get this from your team lead)
+export ASSETS_BASE_URL="https://gitlab.com/<org>/mobile-ai-docs/-/raw/develop/assets"
+
+# Install everything for iOS — one command
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") all ios
+
+# Or pick what you need
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") skills ios
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") agents
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") instructions
 ```
 
-### Shared (All Platforms)
+That's it.
+
+---
+
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `setup.sh skills [platform]` | Install skills from a curated YAML list |
+| `setup.sh agents` | Install all agent prompt files |
+| `setup.sh instructions` | Install all instruction rule files |
+| `setup.sh all [platform]` | All of the above in one shot |
+| `setup.sh update-lists` | Regenerate manifests from directory contents (local only) |
+| `setup.sh help` | Print usage |
+
+### Platforms (for skills)
+
+| Platform | List File |
+|----------|-----------|
+| `ios` | ios-skills.yaml |
+| `android` | android-skills.yaml |
+| `shared` (default) | shared-skills.yaml |
+
+## Where Things Get Installed
+
+| Asset | Default Location | Override |
+|-------|-----------------|----------|
+| Skills | Managed by `npx skills` CLI | — |
+| Agents | `~/.copilot/agents/` | `AGENTS_DIR` |
+| Instructions | `./instructions/` | `INSTRUCTIONS_DIR` |
+
+## Adding New Assets
+
+When you add a new agent or instruction file to `assets/agents/` or `assets/instructions/`, run:
+
 ```bash
-SKILLS_FILE=./assets/shared-skills.yaml ./assets/sync-skills.sh
+./assets/setup.sh update-lists
 ```
 
-### iOS + Shared
+This regenerates `agents.list` and `instructions.list` so remote installs pick up the new files. Commit the updated lists.
-```bash
+
-SKILLS_FILE=./assets/shared-skills.yaml ./assets/sync-skills.sh
+## Folder Structure
-SKILLS_FILE=./assets/ios-skills.yaml ./assets/sync-skills.sh
+
+```
+assets/
+  setup.sh                  ← the installer
+  agents.list               ← auto-generated manifest
+  instructions.list         ← auto-generated manifest
+  ios-skills.yaml           ← curated iOS skills
+  android-skills.yaml       ← curated Android skills
+  shared-skills.yaml        ← curated cross-platform skills
+  agents/                   ← agent prompt files
+  instructions/             ← instruction rule files
 ```
 
-### Android + Shared
+## Environment Variables
-```bash
-SKILLS_FILE=./assets/shared-skills.yaml ./assets/sync-skills.sh
-SKILLS_FILE=./assets/android-skills.yaml ./assets/sync-skills.sh
-```
 
-## Run Without Cloning The Repo (All Assets)
+| Variable | Purpose | Required? |
-This installs skills, agents, and instructions without cloning. Set the base URL once and reuse it.
+|----------|---------|-----------|
-
+| `ASSETS_BASE_URL` | Base URL for remote downloads | Only without a clone |
-```bash
+| `AGENTS_DIR` | Custom agents install path | No |
-export ASSETS_BASE_URL="https://<host>/org/ai-assets/raw/main/assets"
+| `INSTRUCTIONS_DIR` | Custom instructions install path | No |
-
-curl -fsSL "$ASSETS_BASE_URL/sync-skills.sh" -o /tmp/sync-skills.sh
-curl -fsSL "$ASSETS_BASE_URL/ios-skills.yaml" -o /tmp/ios-skills.yaml
-
-chmod +x /tmp/sync-skills.sh
-SKILLS_FILE=/tmp/ios-skills.yaml /tmp/sync-skills.sh
-
-mkdir -p ~/.agents/agents ./instructions
-curl -fsSL "$ASSETS_BASE_URL/agents/<agent-file>.agent.md" -o ~/.agents/agents/<agent-file>.agent.md
-curl -fsSL "$ASSETS_BASE_URL/instructions/<name>.instructions.md" -o ./instructions/<name>.instructions.md
-```
-
-Notes:
-- The base URL is only defined once.
-- Cloning the repo is still recommended if you want updates and version history.
-
-## Install Agents (Clone And Copy)
-Agents are prompt files that live under assets/agents.
-
-```bash
-git clone git@<host>:org/ai-assets.git
-mkdir -p ~/.agents/agents
-cp -R ai-assets/agents/* ~/.agents/agents/
-```
-
-## Install Instructions (Clone And Copy)
-Instructions are repo-level rule files. Copy them into your project.
-
-```bash
-git clone git@<host>:org/ai-assets.git
-mkdir -p ./instructions
-cp -R ai-assets/instructions/* ./instructions/
-```

assets/agents.list

@@ -0,0 +1,10 @@
+arch.agent.md
+debug.agent.md
+principal-software-engineer.agent.md
+prompt-builder.agent.md
+prompt-engineer.agent.md
+software-engineer-agent-v1.agent.md
+task-planner.agent.md
+task-researcher.agent.md
+tech-debt-remediation-plan.agent.md
+thinking-beast-mode.agent.md

assets/instructions.list

@@ -0,0 +1 @@
+swift.instructions.md

assets/setup.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ─────────────────────────────────────────────────────────────────────
+# Mobile AI Assets Installer
+#
+# One script to install skills, agents, and instructions.
+# Works both locally (cloned repo) and remotely (curl, no clone).
+#
+# Local:   ./assets/setup.sh agents
+# Remote:  export ASSETS_BASE_URL="https://..."
+#          bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") agents
+# ─────────────────────────────────────────────────────────────────────
+
+VERSION="1.0.0"
+
+# ── Configuration (override with env vars) ───────────────────────────
+ASSETS_BASE_URL="${ASSETS_BASE_URL:-}"
+AGENTS_DIR="${AGENTS_DIR:-$HOME/.copilot/agents}"
+INSTRUCTIONS_DIR="${INSTRUCTIONS_DIR:-./instructions}"
+
+# ── Colors ───────────────────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# ── Helpers ──────────────────────────────────────────────────────────
+info()    { printf "${BLUE}▸${NC} %s\n" "$*"; }
+ok()      { printf "${GREEN}✓${NC} %s\n" "$*"; }
+warn()    { printf "${YELLOW}!${NC} %s\n" "$*"; }
+fail()    { printf "${RED}✗${NC} %s\n" "$*" >&2; exit 1; }
+heading() { printf "\n${BOLD}── %s ──${NC}\n" "$*"; }
+
+# ── Mode Detection ───────────────────────────────────────────────────
+# Detect if running from a cloned repo or remotely via curl.
+MODE=""
+ASSETS_DIR=""
+
+detect_mode() {
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" || script_dir=""
+
+  if [[ -n "$script_dir" && -f "$script_dir/agents.list" ]]; then
+    MODE="local"
+    ASSETS_DIR="$script_dir"
+  elif [[ -n "$ASSETS_BASE_URL" ]]; then
+    MODE="remote"
+  else
+    fail "Set ASSETS_BASE_URL to run without a clone. Example:
+  export ASSETS_BASE_URL=\"https://gitlab.com/org/repo/-/raw/main/assets\"
+  bash <(curl -fsSL \"\$ASSETS_BASE_URL/setup.sh\") agents"
+  fi
+}
+
+# ── Fetch / Download ────────────────────────────────────────────────
+# Read a file from the local clone or download it from the remote URL.
+fetch() {
+  local path="$1"
+  if [[ "$MODE" == "local" ]]; then
+    cat "$ASSETS_DIR/$path"
+  else
+    curl -fsSL "$ASSETS_BASE_URL/$path"
+  fi
+}
+
+# Download a file to a destination path.
+download_to() {
+  local src="$1" dest="$2"
+  mkdir -p "$(dirname "$dest")"
+  if [[ "$MODE" == "local" ]]; then
+    cp "$ASSETS_DIR/$src" "$dest"
+  else
+    curl -fsSL "$ASSETS_BASE_URL/$src" -o "$dest"
+  fi
+}
+
+# ── Commands ─────────────────────────────────────────────────────────
+
+# -- skills [platform] ------------------------------------------------
+cmd_skills() {
+  local platform="${1:-shared}"
+  local manifest="${platform}-skills.yaml"
+
+  heading "Skills ($platform)"
+
+  local yaml
+  yaml="$(fetch "$manifest")" || fail "Could not fetch $manifest"
+
+  local installs
+  installs=$(echo "$yaml" | sed -n 's/^[[:space:]]*install:[[:space:]]*//p' | sed 's/^"//;s/"$//')
+
+  if [[ -z "$installs" ]]; then
+    warn "No install entries in $manifest — nothing to do."
+    return 0
+  fi
+
+  local count=0
+  while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    read -r -a args <<< "$entry"
+    info "npx skills add ${args[*]}"
+    npx skills add "${args[@]}"
+    count=$((count + 1))
+  done <<< "$installs"
+
+  ok "$count skill(s) installed. Restart your editor if they don't appear."
+}
+
+# -- agents ------------------------------------------------------------
+cmd_agents() {
+  heading "Agents → $AGENTS_DIR"
+
+  local list
+  list="$(fetch "agents.list")" || fail "Could not fetch agents.list"
+
+  mkdir -p "$AGENTS_DIR"
+
+  local count=0
+  while IFS= read -r file; do
+    [[ -z "$file" || "$file" == \#* ]] && continue
+    info "$file"
+    download_to "agents/$file" "$AGENTS_DIR/$file"
+    count=$((count + 1))
+  done <<< "$list"
+
+  ok "$count agent(s) installed."
+}
+
+# -- instructions ------------------------------------------------------
+cmd_instructions() {
+  heading "Instructions → $INSTRUCTIONS_DIR"
+
+  local list
+  list="$(fetch "instructions.list")" || fail "Could not fetch instructions.list"
+
+  mkdir -p "$INSTRUCTIONS_DIR"
+
+  local count=0
+  while IFS= read -r file; do
+    [[ -z "$file" || "$file" == \#* ]] && continue
+    info "$file"
+    download_to "instructions/$file" "$INSTRUCTIONS_DIR/$file"
+    count=$((count + 1))
+  done <<< "$list"
+
+  ok "$count instruction(s) installed."
+}
+
+# -- all [platform] ----------------------------------------------------
+cmd_all() {
+  local platform="${1:-shared}"
+  cmd_skills "$platform"
+  cmd_agents
+  cmd_instructions
+  printf "\n"
+  ok "All done."
+}
+
+# -- update-lists (local only) -----------------------------------------
+# Regenerate agents.list and instructions.list from directory contents.
+cmd_update_lists() {
+  if [[ "$MODE" != "local" ]]; then
+    fail "update-lists only works from a cloned repo."
+  fi
+
+  heading "Updating manifests"
+
+  # agents.list
+  local agents_dir="$ASSETS_DIR/agents"
+  if [[ -d "$agents_dir" ]]; then
+    find "$agents_dir" -maxdepth 1 -type f -name '*.agent.md' \
+      | xargs -I{} basename {} \
+      | sort > "$ASSETS_DIR/agents.list"
+    ok "agents.list  → $(wc -l < "$ASSETS_DIR/agents.list" | tr -d ' ') file(s)"
+  else
+    warn "No agents/ directory found — skipping."
+  fi
+
+  # instructions.list
+  local instr_dir="$ASSETS_DIR/instructions"
+  if [[ -d "$instr_dir" ]]; then
+    find "$instr_dir" -maxdepth 1 -type f -name '*.instructions.md' \
+      | xargs -I{} basename {} \
+      | sort > "$ASSETS_DIR/instructions.list"
+    ok "instructions.list → $(wc -l < "$ASSETS_DIR/instructions.list" | tr -d ' ') file(s)"
+  else
+    warn "No instructions/ directory found — skipping."
+  fi
+}
+
+# -- help --------------------------------------------------------------
+cmd_help() {
+  cat <<EOF
+
+${BOLD}Mobile AI Assets Installer${NC} v${VERSION}
+
+${BOLD}USAGE${NC}
+  setup.sh <command> [platform]
+
+${BOLD}COMMANDS${NC}
+  skills [platform]   Install skills from a curated list
+  agents              Install all agent prompt files
+  instructions        Install all instruction files
+  all [platform]      Install everything at once
+  update-lists        Regenerate agents.list / instructions.list (local only)
+  help                Show this message
+
+${BOLD}PLATFORMS${NC} (for skills)
+  ios        iOS-specific skills
+  android    Android-specific skills
+  shared     Cross-platform skills (default)
+
+${BOLD}EXAMPLES${NC}
+  ${GREEN}# Cloned repo${NC}
+  ./assets/setup.sh skills ios
+  ./assets/setup.sh agents
+  ./assets/setup.sh all ios
+
+  ${GREEN}# No clone — run directly from the remote repo${NC}
+  export ASSETS_BASE_URL="https://gitlab.com/org/repo/-/raw/main/assets"
+  bash <(curl -fsSL "\$ASSETS_BASE_URL/setup.sh") skills ios
+  bash <(curl -fsSL "\$ASSETS_BASE_URL/setup.sh") agents
+  bash <(curl -fsSL "\$ASSETS_BASE_URL/setup.sh") all ios
+
+${BOLD}ENVIRONMENT VARIABLES${NC}
+  ASSETS_BASE_URL      Base URL for remote downloads (required without clone)
+  AGENTS_DIR           Install location for agents   (default: ~/.copilot/agents)
+  INSTRUCTIONS_DIR     Install location for instructions (default: ./instructions)
+  SKILLS_FILE          Override the skills YAML path  (local mode only)
+
+EOF
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+detect_mode
+
+case "${1:-help}" in
+  skills)        cmd_skills "${2:-shared}" ;;
+  agents)        cmd_agents ;;
+  instructions)  cmd_instructions ;;
+  all)           cmd_all "${2:-shared}" ;;
+  update-lists)  cmd_update_lists ;;
+  help|--help|-h) cmd_help ;;
+  *)             fail "Unknown command: $1. Run 'setup.sh help' for usage." ;;
+esac

assets/sync-skills.sh

@@ -1,26 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-MANIFEST_DEFAULT="$ROOT_DIR/assets/shared-skills.yaml"
-MANIFEST="${SKILLS_FILE:-$MANIFEST_DEFAULT}"
-
-if [[ ! -f "$MANIFEST" ]]; then
-  echo "Missing skills manifest: $MANIFEST" >&2
-  exit 1
-fi
-
-INSTALLS=$(sed -n 's/^[[:space:]]*install:[[:space:]]*//p' "$MANIFEST" | sed 's/^"//;s/"$//')
-
-if [[ -z "$INSTALLS" ]]; then
-  echo "No install entries found in: $MANIFEST" >&2
-  exit 1
-fi
-
-while IFS= read -r INSTALL; do
-  [[ -z "$INSTALL" ]] && continue
-  read -r -a ARGS <<< "$INSTALL"
-  npx skills add "${ARGS[@]}"
-done <<< "$INSTALLS"
-
-echo "Done. Restart your editor if skills do not appear."

docs/ai/skills.md

@@ -46,6 +46,9 @@ Keep the approved list in a single repo and organize by platform. This repo alre
 
 ```text
 /assets/
+	setup.sh              ← single installer script
+	agents.list           ← auto-generated manifest
+	instructions.list     ← auto-generated manifest
 	ios-skills.yaml
 	android-skills.yaml
 	shared-skills.yaml
@@ -68,20 +71,21 @@ skills:
 
 ### Sync Workflow
 1. Update the curated list in assets (shared, iOS, or Android).
-2. Run the sync script.
+2. Run `./assets/setup.sh skills ios` (or `android`, `shared`).
 3. The script installs each skill using the `npx skills` CLI.
-3. Restart your editor if required.
+4. Restart your editor if required.
 
-### Example Sync Command
+### Example Sync Commands
 ```bash
-./assets/sync-skills.sh
+# Install iOS skills
-```
+./assets/setup.sh skills ios
 
-### Platform-Specific Install
+# Install everything (skills + agents + instructions)
-Set `SKILLS_FILE` to install a platform list:
+./assets/setup.sh all ios
 
-```bash
+# Remote — no clone required
-SKILLS_FILE=./assets/ios-skills.yaml ./assets/sync-skills.sh
+export ASSETS_BASE_URL="https://gitlab.com/<org>/mobile-ai-docs/-/raw/develop/assets"
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") all ios
 ```
 
 ## Skills CLI (Single Path)
@@ -94,7 +98,7 @@ We use a single, approved path: update the curated list under assets/ and run th
 
 ### How It Works (High-Level)
 1. You update assets/shared-skills.yaml (or a platform list) with approved install entries.
-2. Run ./assets/sync-skills.sh.
+2. Run `./assets/setup.sh skills` (or `skills ios`, `skills android`).
 3. The script uses `npx skills` to install each skill.
 
 ### Install The CLI (No Global Install Required)
@@ -127,21 +131,28 @@ npx skills init [name]       Create a new skill
 ![Skills Find](images/skills-find.png)
 
 ## How to Download Existing Skills
-1. Locate the skill in the team or org repository.
+Run the setup script:
-2. Add the skill to your local skills directory following team guidance.
-3. Restart the editor or chat if required so the skill is recognized.
-
-## How to Download Agents
-Agents are distributed in the curated repo under an agents folder. A simple approach is to clone the repo and copy the agents into your user-level agents directory.
-
-Example:
 ```bash
-git clone git@<host>:org/ai-assets.git
+./assets/setup.sh skills ios
-mkdir -p ~/.agents/agents
-cp -R ai-assets/agents/* ~/.agents/agents/
 ```
 
-If your team provides a sync script, use that instead of manual copy.
+Or remotely without cloning:
+```bash
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") skills ios
+```
+
+## How to Download Agents
+Run the setup script:
+```bash
+./assets/setup.sh agents
+```
+
+Or remotely without cloning:
+```bash
+bash <(curl -fsSL "$ASSETS_BASE_URL/setup.sh") agents
+```
+
+Agents are installed to `~/.copilot/agents/` by default. Override with the `AGENTS_DIR` environment variable.
 
 ## How to Enable or Configure Skills
 - Follow the instructions provided in each skill's README or SKILL file.