skill-tags 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steven Light
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# skill-tags
+
+Generate a single consolidated Cursor command file for all installed skills, making it easy to reference your entire skill library using `@skill-tags.md` in Cursor chat.
+
+> [!IMPORTANT]
+> Cursor's Agent Skills feature only loads skill frontmatter into the agent's context window. Skills are "intelligently applied", but I have had little to no success with them unless I explicitly ask the model to apply the skill.
+
+skill-tags bypasses this by generating a single command file (`~/.cursor/commands/skill-tags.md`) that lists all available skills, their paths, and their descriptions. By referencing this single file, you give the agent a complete index of all skills on your system and instruct it to autonomously choose the best skill(s) for the current task.
+
+> [!TIP]
+> Stay tuned for a more permanent solution to this problem: I'm developing an open source community called [Cursor Kits](https://cursorkits.com). Cursor Kits is something I started before Cursor launched their [Plugin Marketplace](https://cursor.com/marketplace). It's the same idea, but built for the community (vs integration providers).
+
+If you're interested in contributing to Cursor Kits, please let me know!
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [Categorized Indexes](#categorized-indexes)
+- [Agent Setup Prompt](#agent-setup-prompt)
+- [Install Options](#install-options)
+- [How It Works](#how-it-works)
+- [CLI Reference](#cli-reference)
+- [Manual Sync](#manual-sync)
+- [Skill Sources Scanned](#skill-sources-scanned)
+- [Generated File Format](#generated-file-format)
+- [Skill Metadata Tags](#skill-metadata-tags)
+- [Uninstall](#uninstall)
+- [Requirements](#requirements)
+- [License](#license)
+
+---
+
+## Quick Start
+
+```bash
+# Install (global, recommended)
+npm install -g skill-tags
+
+# Add the shell auto-trigger wrapper
+skill-tags --setup
+source ~/.zshrc
+
+# Initial sync (generate command file)
+skill-tags
+```
+
+## Usage
+
+In any Cursor chat, attach the full index of your skills by referencing the generated command file:
+
+- `@skill-tags.md`
+
+Example:
+
+```text
+@skill-tags.md Help me refactor this React component to be more performant.
+```
+
+The agent will assess the available skills listed in the file, automatically determine which ones are relevant (e.g., `vercel-react-best-practices`), and apply them to your request. If the agent is in **Plan Mode**, it will also proactively reference specific skills to be used in the generated plan and TODOs.
+
+## Categorized Indexes
+
+For more focused context windows, you can group your skills into category-specific index files using the interactive wizard:
+
+```bash
+skill-tags --categories
+```
+
+This opens a CRUD wizard where you can create, edit, and delete categories. Skill assignment is powered by a two-tier auto-suggestion system:
+
+1. **`metadata.tags` (high confidence)** — if a skill's `SKILL.md` includes a `metadata.tags` frontmatter field, those tags are matched directly against the category.
+2. **Keyword fallback** — for skills without `metadata.tags`, the skill name and description are scanned against a built-in keyword map.
+
+Suggested skills are pre-selected (`[*]`). You can toggle any skill in or out by number before confirming.
+
+Once configured, every `skill-tags` sync automatically regenerates the category files from the saved config at `~/.cursor/skill-tags-categories.conf`.
+
+```bash
+# Inject a focused category index instead of the full list:
+@skills-frontend.md
+@skills-testing.md
+@skills-ai-agents.md
+```
+
+Predefined categories: `frontend`, `backend`, `database`, `testing`, `accessibility`, `performance`, `ai-agents`, `devops`, `design`. You can also create custom categories with any name.
+
+---
+
+## Agent Setup Prompt
+
+Copy and paste this into your Cursor agent to autoconfigure skill-tags:
+
+<details>
+<summary>Click to expand the full setup prompt</summary>
+
+```text
+Install and configure the skill-tags package for me.
+
+First, confirm with me: should this be a global install (adds `skill-tags` to PATH, recommended for most users) or a local project devDependency? Wait for my answer before proceeding.
+
+Once confirmed, use a terminal that runs outside the sandbox with full permissions to avoid permission errors during install. In Cursor, this means using a non-sandboxed terminal session if available (required_permissions: ["all"] if running via agent shell tools).
+
+Steps to perform:
+1. Install the package based on my preference:
+   - Global: `npm install -g skill-tags`
+   - Local: `npm install --save-dev skill-tags`
+2. Run `skill-tags --setup` to install the `skills()` shell wrapper in my rc file (~/.zshrc or ~/.bash_profile)
+3. Run `skill-tags` to perform an initial sync of all installed skills
+4. Source my shell rc file or instruct me to do so manually
+
+When complete, output a summary that includes:
+- Where the command file was generated (~/.cursor/commands/skill-tags.md)
+- How to use it: typing @skill-tags.md in any Cursor chat attaches the full index of skills for the agent to assess
+- How the auto-trigger works: `skills add/remove <pkg>` now automatically syncs after every install/removal
+- How to manually re-sync at any time: run `skill-tags`
+- The total number of skills that were indexed
+```
+
+</details>
+
+---
+
+## Install Options
+
+### Install via npm
+
+```bash
+# Global install (recommended) — adds `skill-tags` to your PATH
+npm install -g skill-tags
+
+# One-off run without installing
+npx skill-tags
+
+# Project devDependency (adds to package.json)
+npm install --save-dev skill-tags
+```
+
+After global install, set up the shell auto-trigger wrapper:
+
+```bash
+skill-tags --setup
+source ~/.zshrc
+```
+
+### Install via curl
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/steve-piece/skill-tags/main/install.sh | bash
+```
+
+Then reload your shell:
+
+```bash
+source ~/.zshrc   # or ~/.bash_profile / ~/.bashrc
+```
+
+## How It Works
+
+After setup, the `skills` command wraps `npx skills` and automatically runs a sync after every `skills add` or `skills remove`:
+
+```bash
+# Install (or remove) a skill — sync runs automatically
+skills add vercel-labs/agent-skills/vercel-react-best-practices
+
+# The single command file is updated:
+# ~/.cursor/commands/skill-tags.md
+
+# Use it in Cursor chat:
+# @skill-tags.md
+```
+
+## CLI Reference
+
+```bash
+skill-tags              # sync all skills, generate/update the command file
+skill-tags --categories # open interactive category wizard (CRUD)
+skill-tags --setup      # install skills() shell wrapper in ~/.zshrc
+skill-tags --global-only  # skip project-level skills
+skill-tags --version    # print version
+skill-tags --help       # show usage
+```
+
+## Manual Sync
+
+Run at any time to regenerate the command file:
+
+```bash
+skill-tags
+
+# Or via bash directly:
+bash ~/.cursor/sync-skill-commands.sh
+```
+
+## Skill Sources Scanned
+
+Skills are discovered from all of these locations automatically. When the same skill name appears in multiple sources, the first match wins (priority order):
+
+| Priority | Directory | Source |
+|---|---|---|
+| 1 | `~/.agents/skills/` | `npx skills add` installs |
+| 2 | `~/.cursor/skills-cursor/` | Cursor built-in skills |
+| 3 | `~/.cursor/plugins/cache/` | Cursor Marketplace plugins |
+| 4 | `~/.claude/plugins/cache/` | Claude plugins |
+| 5 | `~/.codex/skills/` | Codex skills |
+| 6 | `./.agents/skills/` | Project-level skills (CWD) |
+
+## Generated File Format
+
+The `~/.cursor/commands/skill-tags.md` contains:
+
+- An opening instruction for the agent to assess all skills and apply them autonomously.
+- Instructions for the agent on how to plan with skills when in Plan Mode.
+- A full list of available skills, including their titles, directory paths, and descriptions.
+
+This gives the agent a complete map of your skill library when you reference it with `@`.
+
+## Skill Metadata Tags
+
+skill-tags uses the official `metadata` frontmatter field from the [skills.sh](https://skills.sh) spec to improve auto-categorization. If you are authoring a skill, add `metadata.tags` to improve how it is categorized:
+
+```yaml
+---
+name: my-skill
+description: Does X, Y, Z.
+metadata:
+  tags: [frontend, react, animation]
+---
+```
+
+Skills with `metadata.tags` are surfaced as high-confidence matches in the `--categories` wizard and marked `[*]` with the tag source shown inline. Skills without tags fall back to keyword matching.
+
+---
+
+## Uninstall
+
+```bash
+# Via npm
+npm uninstall -g skill-tags
+
+# Clean up generated command file and shell wrapper
+bash uninstall.sh
+```
+
+## Requirements
+
+- macOS or Linux (Windows not supported — requires bash)
+- Node.js >=14 (for npm install)
+- bash or zsh
+- [Cursor IDE](https://cursor.com)
+
+## License
+
+MIT

package/bin/postinstall.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// bin/postinstall.js
+// Runs automatically after `npm install -g skill-tags`.
+// Performs an initial sync of any already-installed skills.
+// Never throws — a failed postinstall should never break npm install.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Skip entirely on Windows
+if (process.platform === 'win32') {
+  process.exit(0);
+}
+
+// Skip on local (non-global) installs to avoid running on every `npm install`
+// in a project. npm sets npm_config_global=true for -g installs.
+if (process.env.npm_config_global !== 'true') {
+  process.exit(0);
+}
+
+const syncScript = path.join(__dirname, '..', 'sync.sh');
+
+if (!fs.existsSync(syncScript)) {
+  process.exit(0);
+}
+
+console.log('\n  skill-tags: running initial sync...\n');
+
+try {
+  const result = spawnSync('bash', [syncScript], { stdio: 'inherit' });
+  if (result.error) throw result.error;
+} catch (_) {
+  // Never fail the install
+}
+
+console.log('  To auto-sync after every `skills add`, run:');
+console.log('    skill-tags --setup\n');
+
+process.exit(0);

package/bin/skill-tags.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// bin/skill-tags.js
+// CLI entry point for skill-tags. Spawns sync.sh with bash and passes all args through.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const VERSION = require('../package.json').version;
+
+// Handle --version before delegating to bash
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  console.log(`skill-tags v${VERSION}`);
+  process.exit(0);
+}
+
+// Windows is not supported (requires bash)
+if (process.platform === 'win32') {
+  console.error('skill-tags requires bash and is not supported on Windows.');
+  console.error('Consider using WSL (Windows Subsystem for Linux) instead.');
+  process.exit(1);
+}
+
+// Locate sync.sh bundled alongside this package
+const syncScript = path.join(__dirname, '..', 'sync.sh');
+
+if (!fs.existsSync(syncScript)) {
+  console.error(`skill-tags: sync.sh not found at ${syncScript}`);
+  console.error('Try reinstalling: npm install -g skill-tags');
+  process.exit(1);
+}
+
+// Pass all CLI arguments through to sync.sh
+const args = process.argv.slice(2);
+const result = spawnSync('bash', [syncScript, ...args], { stdio: 'inherit' });
+
+if (result.error) {
+  console.error(`skill-tags: failed to run bash — ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/install.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# install.sh
+# One-line installer for skill-tags.
+#
+# Usage (curl):
+#   curl -fsSL https://raw.githubusercontent.com/steve-piece/skill-tags/main/install.sh | bash
+#
+# Usage (local):
+#   bash install.sh
+
+set -euo pipefail
+
+REPO="https://raw.githubusercontent.com/steve-piece/skill-tags/main"
+SYNC_SCRIPT_DEST="${HOME}/.cursor/sync-skill-commands.sh"
+CURSOR_COMMANDS_DIR="${HOME}/.cursor/commands"
+WRAPPER_MARKER="# ─── skill-tags / Cursor Skill Command Sync"
+
+# ─── Helpers ───────────────────────────────────────────────────────────────────
+
+info()    { printf "  %s\n" "$*"; }
+success() { printf "  ✓ %s\n" "$*"; }
+warn()    { printf "  ⚠ %s\n" "$*"; }
+die()     { printf "\n  ✗ Error: %s\n\n" "$*" >&2; exit 1; }
+
+# ─── Shell detection ───────────────────────────────────────────────────────────
+
+detect_rc() {
+  local shell_name
+  shell_name="$(basename "${SHELL:-bash}")"
+  if [[ "$shell_name" == "zsh" ]]; then
+    echo "${HOME}/.zshrc"
+  elif [[ "$shell_name" == "bash" ]]; then
+    # macOS uses ~/.bash_profile, Linux uses ~/.bashrc
+    if [[ "$(uname)" == "Darwin" ]]; then
+      echo "${HOME}/.bash_profile"
+    else
+      echo "${HOME}/.bashrc"
+    fi
+  else
+    echo "${HOME}/.profile"
+  fi
+}
+
+# ─── Download or copy sync.sh ──────────────────────────────────────────────────
+
+install_sync_script() {
+  mkdir -p "$(dirname "$SYNC_SCRIPT_DEST")"
+  mkdir -p "$CURSOR_COMMANDS_DIR"
+
+  # If running from a local clone, copy directly
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd || echo "")"
+
+  if [[ -n "$script_dir" && -f "${script_dir}/sync.sh" ]]; then
+    cp "${script_dir}/sync.sh" "$SYNC_SCRIPT_DEST"
+    info "Installed from local copy."
+  else
+    # Download from GitHub
+    if command -v curl &>/dev/null; then
+      curl -fsSL "${REPO}/sync.sh" -o "$SYNC_SCRIPT_DEST"
+    elif command -v wget &>/dev/null; then
+      wget -qO "$SYNC_SCRIPT_DEST" "${REPO}/sync.sh"
+    else
+      die "Neither curl nor wget found. Please install one and retry."
+    fi
+    info "Downloaded sync.sh from GitHub."
+  fi
+
+  chmod +x "$SYNC_SCRIPT_DEST"
+  success "Installed: ${SYNC_SCRIPT_DEST/#$HOME/~}"
+}
+
+# ─── Shell wrapper ─────────────────────────────────────────────────────────────
+
+install_wrapper() {
+  local rc_file="$1"
+
+  # Idempotent: skip if already installed
+  if grep -q "$WRAPPER_MARKER" "$rc_file" 2>/dev/null; then
+    warn "Shell wrapper already present in ${rc_file/#$HOME/~} — skipping."
+    return 0
+  fi
+
+  # Create rc file if it doesn't exist
+  touch "$rc_file"
+
+  cat >> "$rc_file" <<'WRAPPER'
+
+# ─── skill-tags / Cursor Skill Command Sync ────────────────────────────────────
+# Wraps `npx skills` to auto-generate @skill-name.md command files after install.
+# Run manually: skill-tags   (or: bash ~/.cursor/sync-skill-commands.sh)
+function skills() {
+  npx skills "$@"
+  local exit_code=$?
+  if [[ "$1" == "add" && $exit_code -eq 0 ]]; then
+    bash ~/.cursor/sync-skill-commands.sh
+  fi
+  return $exit_code
+}
+# ─────────────────────────────────────────────────────────────────────────────
+WRAPPER
+
+  success "Added skills wrapper to ${rc_file/#$HOME/~}"
+}
+
+# ─── Main ──────────────────────────────────────────────────────────────────────
+
+printf "\n🔧 Installing skill-tags...\n\n"
+
+# 1. Install sync script
+install_sync_script
+
+# 2. Detect shell and install wrapper
+RC_FILE="$(detect_rc)"
+info "Detected shell rc: ${RC_FILE/#$HOME/~}"
+install_wrapper "$RC_FILE"
+
+# 3. Run initial sync
+printf "\n  Running initial sync...\n"
+bash "$SYNC_SCRIPT_DEST" || true
+
+# ─── Done ──────────────────────────────────────────────────────────────────────
+
+printf "  Installation complete!\n\n"
+printf "  Next steps:\n"
+printf "    1. Reload your shell:  source %s\n" "${RC_FILE/#$HOME/~}"
+printf "    2. Install a skill:    skills add <owner/repo/skill-name>\n"
+printf "    3. Use in Cursor chat: @<skill-name>.md\n\n"
+printf "  To sync manually at any time:\n"
+printf "    bash ~/.cursor/sync-skill-commands.sh\n\n"

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "skill-tags",
+  "version": "1.1.0",
+  "description": "Generate a Cursor /skill-tags command file indexing all installed agent skills for autonomous context injection",
+  "bin": {
+    "skill-tags": "bin/skill-tags.js"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "keywords": [
+    "cursor",
+    "cursor-ide",
+    "skills",
+    "agent-skills",
+    "skills.sh",
+    "skill-tags",
+    "ai",
+    "llm",
+    "mcp",
+    "claude",
+    "codex"
+  ],
+  "author": "Steven Light",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steve-piece/skill-tags.git"
+  },
+  "homepage": "https://github.com/steve-piece/skill-tags#readme",
+  "files": [
+    "bin/",
+    "sync.sh",
+    "install.sh",
+    "uninstall.sh",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/sync.sh

@@ -0,0 +1,773 @@
+#!/usr/bin/env bash
+# sync.sh
+# Generates ~/.cursor/commands/skill-tags.md listing all installed skills.
+# Optionally generates categorized skill files via --categories wizard.
+# Scans every known skill location, deduplicates by name (first-found wins).
+# Works on macOS and Linux. bash 3.2 compatible (macOS default).
+#
+# Usage:
+#   bash sync.sh                    # generate skill-tags.md
+#   bash sync.sh --categories       # interactive category wizard (CRUD)
+#   bash sync.sh --global-only      # skip project-level skills
+#   bash sync.sh --setup            # install shell wrapper (skills() auto-trigger)
+#   bash sync.sh --version          # print version
+#   bash sync.sh --help             # show usage
+
+set -euo pipefail
+
+VERSION="1.1.0"
+
+GLOBAL_COMMANDS_DIR="${HOME}/.cursor/commands"
+OUTPUT_FILE="${GLOBAL_COMMANDS_DIR}/skill-tags.md"
+CATEGORIES_CONFIG="${HOME}/.cursor/skill-tags-categories.conf"
+WRAPPER_MARKER="# ─── skill-tags / Cursor Skill Command Sync"
+
+# ─── Priority-ordered skill source directories ─────────────────────────────────
+# Earlier entries take priority when the same skill name exists in multiple locations.
+# Format: "path:label"
+GLOBAL_SKILL_SOURCES=(
+  "${HOME}/.agents/skills:global skills"
+  "${HOME}/.cursor/skills-cursor:cursor built-in skills"
+  "${HOME}/.cursor/plugins/cache:cursor plugin cache"
+  "${HOME}/.claude/plugins/cache:claude plugin cache"
+  "${HOME}/.codex/skills:codex skills"
+)
+
+# ─── Temp files (created early; trap cleans up on any exit) ────────────────────
+
+SKILLS_TEMP="$(mktemp)"
+SKILLS_META_DIR="$(mktemp -d)"
+trap 'rm -f "$SKILLS_TEMP"; rm -rf "$SKILLS_META_DIR"' EXIT
+
+# ─── Shell setup helper ────────────────────────────────────────────────────────
+
+detect_rc() {
+  local shell_name
+  shell_name="$(basename "${SHELL:-bash}")"
+  if [[ "$shell_name" == "zsh" ]]; then
+    echo "${HOME}/.zshrc"
+  elif [[ "$(uname)" == "Darwin" ]]; then
+    echo "${HOME}/.bash_profile"
+  else
+    echo "${HOME}/.bashrc"
+  fi
+}
+
+cmd_setup() {
+  local rc_file
+  rc_file="$(detect_rc)"
+
+  printf "\n  skill-tags: shell setup\n\n"
+
+  if grep -q "$WRAPPER_MARKER" "$rc_file" 2>/dev/null; then
+    printf "  Shell wrapper already installed in %s\n\n" "${rc_file/#$HOME/~}"
+    return 0
+  fi
+
+  local sync_path="${HOME}/.cursor/sync-skill-commands.sh"
+  if [[ ! -f "$sync_path" ]]; then
+    sync_path="$(cd "$(dirname "$0")" && pwd)/sync.sh"
+  fi
+
+  touch "$rc_file"
+  cat >> "$rc_file" <<WRAPPER
+
+${WRAPPER_MARKER} ────────────────────────────────────────────────
+# Wraps \`npx skills\` to auto-generate skill-tags.md after install/removal.
+# Run manually: skill-tags   (or: bash ${sync_path})
+function skills() {
+  npx skills "\$@"
+  local exit_code=\$?
+  if [[ "\$1" == "add" || "\$1" == "remove" ]] && [[ \$exit_code -eq 0 ]]; then
+    bash "${sync_path}"
+  fi
+  return \$exit_code
+}
+# ─────────────────────────────────────────────────────────────────────────────
+WRAPPER
+
+  printf "  Added skills() wrapper to %s\n" "${rc_file/#$HOME/~}"
+  printf "  Reload with: source %s\n\n" "${rc_file/#$HOME/~}"
+}
+
+# ─── Flags ─────────────────────────────────────────────────────────────────────
+
+GLOBAL_ONLY=false
+RUN_CATEGORIES=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --global-only)  GLOBAL_ONLY=true ;;
+    --categories)   RUN_CATEGORIES=true ;;
+    --version|-v)
+      echo "skill-tags v${VERSION}"
+      exit 0
+      ;;
+    --setup)
+      cmd_setup
+      exit 0
+      ;;
+    --help|-h)
+      echo "skill-tags v${VERSION} — Cursor Skill Command Sync"
+      echo ""
+      echo "Usage: skill-tags [options]"
+      echo ""
+      echo "Options:"
+      echo "  (none)           Scan all skill sources and generate skill-tags.md"
+      echo "  --categories     Open interactive category wizard (create/edit/delete groups)"
+      echo "  --global-only    Skip project-level skills (.agents/skills in CWD)"
+      echo "  --setup          Install the skills() shell wrapper in ~/.zshrc (auto-trigger)"
+      echo "  --version, -v    Print version"
+      echo "  --help, -h       Show this help"
+      echo ""
+      echo "Skill sources scanned (priority order — first match wins):"
+      echo "  ~/.agents/skills/              (skills installed via npx skills add)"
+      echo "  ~/.cursor/skills-cursor/       (Cursor built-in skills)"
+      echo "  ~/.cursor/plugins/cache/       (Cursor Marketplace plugin skills)"
+      echo "  ~/.claude/plugins/cache/       (Claude plugin skills)"
+      echo "  ~/.codex/skills/               (Codex skills)"
+      echo "  ./.agents/skills/              (project-level skills, current directory)"
+      echo ""
+      echo "Output:"
+      echo "  ~/.cursor/commands/skill-tags.md          (full index of all skills)"
+      echo "  ~/.cursor/commands/skills-<category>.md   (generated by --categories)"
+      echo ""
+      echo "Category config:"
+      echo "  ~/.cursor/skill-tags-categories.conf"
+      exit 0
+      ;;
+  esac
+done
+
+# ─── Helpers ───────────────────────────────────────────────────────────────────
+
+count_found=0
+count_dupes=0
+
+log()     { printf "  %s\n" "$*"; }
+success() { printf "  ✓ %s\n" "$*"; }
+
+# Tracks which skill names have already been processed (deduplication).
+# Uses a delimited string for bash 3.2 compatibility (no associative arrays).
+seen_skills=":"
+
+# Convert kebab-case or snake_case to Title Case
+to_title_case() {
+  echo "$1" | sed 's/[-_]/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) substr($i,2)}1'
+}
+
+# Extract description: from YAML frontmatter, or fall back to first content line
+extract_description() {
+  local skill_file="$1"
+  local desc
+
+  desc=$(awk '
+    BEGIN { in_fm=0 }
+    /^---/ {
+      if (in_fm == 0) { in_fm=1; next }
+      else { exit }
+    }
+    in_fm==1 && /^description:/ {
+      sub(/^description:[[:space:]]*/, "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      print
+      exit
+    }
+  ' "$skill_file" 2>/dev/null)
+
+  if [[ -n "$desc" ]]; then
+    echo "$desc"
+    return
+  fi
+
+  desc=$(awk '
+    BEGIN { in_fm=0 }
+    /^---/ {
+      if (in_fm == 0) { in_fm=1; next }
+      else { in_fm=0; next }
+    }
+    in_fm { next }
+    /^#/ { next }
+    /^[[:space:]]*$/ { next }
+    { print; exit }
+  ' "$skill_file" 2>/dev/null)
+
+  echo "${desc:-(No description available)}"
+}
+
+# Extract metadata.tags from YAML frontmatter.
+# Returns a colon-delimited string, e.g. "frontend:react:animation"
+extract_metadata_tags() {
+  local skill_file="$1"
+  awk '
+    BEGIN { in_fm=0; in_meta=0 }
+    /^---/ { if (in_fm==0) { in_fm=1; next } else { exit } }
+    in_fm && /^metadata:/ { in_meta=1; next }
+    in_meta && /^[^ ]/ { in_meta=0 }
+    in_meta && /tags:/ {
+      gsub(/.*tags:[[:space:]]*/, "")
+      gsub(/[\[\]]/, "")
+      gsub(/,/, ":")
+      gsub(/[[:space:]]/, "")
+      print
+      exit
+    }
+  ' "$skill_file" 2>/dev/null
+}
+
+collect_skill() {
+  local skill_dir="$1"
+  local skill_name="$2"
+  local skill_file="${skill_dir}/SKILL.md"
+  local display_path="${skill_dir/#$HOME/~}"
+  local title
+  title="$(to_title_case "$skill_name")"
+  local desc
+  desc="$(extract_description "$skill_file")"
+  local tags
+  tags="$(extract_metadata_tags "$skill_file")"
+
+  # Markdown section for skill-tags.md
+  cat >> "$SKILLS_TEMP" <<EOF
+
+### ${title}
+\`${display_path}\`
+
+${desc}
+EOF
+
+  # Pipe-delimited metadata record for categorization lookups
+  # Format: display_path|description|tags
+  printf '%s|%s|%s\n' "$display_path" "$desc" "$tags" > "${SKILLS_META_DIR}/${skill_name}"
+
+  count_found=$(( count_found + 1 ))
+  log "  Found: ${title} (${display_path})"
+}
+
+# Recursively find all SKILL.md files under a directory tree.
+# Handles flat dirs (~/.agents/skills/name/SKILL.md) and
+# nested plugin caches (cache/plugin/version/skills/name/SKILL.md).
+scan_tree() {
+  local base_dir="$1"
+
+  [[ -d "$base_dir" ]] || return 0
+
+  local found=0
+  local base_dir_slash="${base_dir}/"
+
+  while IFS= read -r skill_file; do
+    # Check only the relative portion of the path for hidden components.
+    # The base_dir itself may live inside hidden dirs (e.g. ~/.agents/) so we
+    # must not apply the dot-filter to the full absolute path.
+    local rel="${skill_file#$base_dir_slash}"
+    if echo "$rel" | grep -q '/\.'; then
+      continue
+    fi
+
+    local skill_dir
+    skill_dir="$(dirname "$skill_file")"
+    local skill_name
+    skill_name="$(basename "$skill_dir")"
+
+    # Skip if this skill name was already processed from a higher-priority source
+    if [[ "$seen_skills" == *":${skill_name}:"* ]]; then
+      count_dupes=$(( count_dupes + 1 ))
+      continue
+    fi
+
+    seen_skills="${seen_skills}${skill_name}:"
+    collect_skill "$skill_dir" "$skill_name"
+    found=$(( found + 1 ))
+  done < <(find "$base_dir" -name "SKILL.md" 2>/dev/null | sort)
+
+  if [[ $found -gt 0 ]]; then
+    log "  Found $found skill(s) in ${base_dir/#$HOME/~}"
+  fi
+}
+
+# ─── Category helpers ───────────────────────────────────────────────────────────
+
+PREDEFINED_CATEGORIES="frontend backend database testing accessibility performance ai-agents devops design"
+
+# Hardcoded keyword map for Tier 2 fallback categorization.
+# Returns a colon-delimited keyword string for the given category name.
+get_category_keywords() {
+  case "$1" in
+    frontend)      echo "react:next:vue:svelte:css:html:responsive:component:ui:ux:tailwind:animation:design-system" ;;
+    backend)       echo "api:server:node:express:rest:graphql:stripe:payment:webhook" ;;
+    database)      echo "postgres:sql:supabase:database:schema:query:migration:orm" ;;
+    testing)       echo "test:vitest:playwright:jest:coverage:mock:spec:e2e" ;;
+    accessibility) echo "accessibility:aria:wcag:a11y:screen-reader:keyboard" ;;
+    performance)   echo "performance:optimize:speed:lazy:cache:memoize:bundle:lighthouse" ;;
+    ai-agents)     echo "agent:skill:claude:cursor:mcp:subagent:browser:automation:llm:ai:workflow" ;;
+    devops)        echo "deploy:vercel:docker:ci:cd:build:pipeline:github:actions" ;;
+    design)        echo "design:figma:ux:animation:motion:color:typography:shadow:gradient" ;;
+    *)             echo "" ;;
+  esac
+}
+
+# Two-tier categorization check for a single skill against a category.
+# Tier 1: metadata.tags match (higher confidence)
+# Tier 2: keyword match against skill name + description (fallback)
+# Prints "1" for tier-1 match, "2" for tier-2 match, "" for no match.
+# All interactive output must go to stderr; stdout is reserved for the return value.
+skill_match_tier() {
+  local skill_name="$1"
+  local category="$2"
+  local meta_file="${SKILLS_META_DIR}/${skill_name}"
+  [[ -f "$meta_file" ]] || return 0
+
+  local tags
+  tags="$(awk -F'|' '{print $3}' "$meta_file")"
+  local desc
+  desc="$(awk -F'|' '{print $2}' "$meta_file")"
+  local cat_keywords
+  cat_keywords="$(get_category_keywords "$category")"
+
+  # Tier 1 — metadata.tags
+  if [[ -n "$tags" && -n "$cat_keywords" ]]; then
+    local tag
+    while IFS= read -r tag; do
+      [[ -z "$tag" ]] && continue
+      if echo ":${cat_keywords}:" | grep -qi ":${tag}:"; then
+        echo "1"
+        return
+      fi
+    done < <(echo "$tags" | tr ':' '\n')
+  fi
+
+  # Tier 2 — keyword match against name + description
+  if [[ -n "$cat_keywords" ]]; then
+    local search_text="${skill_name} ${desc}"
+    local kw
+    while IFS= read -r kw; do
+      [[ -z "$kw" ]] && continue
+      if echo "$search_text" | grep -qi "$kw"; then
+        echo "2"
+        return
+      fi
+    done < <(echo "$cat_keywords" | tr ':' '\n')
+  fi
+}
+
+# Read current skill assignments for a category from the config file.
+read_config_category() {
+  local category="$1"
+  if [[ ! -f "$CATEGORIES_CONFIG" ]]; then
+    echo ""
+    return
+  fi
+  grep "^${category}=" "$CATEGORIES_CONFIG" 2>/dev/null | sed "s/^${category}=//" || true
+}
+
+# Write (create or update) a category line in the config file.
+write_config_category() {
+  local category="$1"
+  local skill_list="$2"
+  local tmp
+  tmp="$(mktemp)"
+
+  if [[ -f "$CATEGORIES_CONFIG" ]] && grep -q "^${category}=" "$CATEGORIES_CONFIG" 2>/dev/null; then
+    # Replace existing line
+    awk -v cat="$category" -v list="$skill_list" \
+      'substr($0,1,length(cat)+1)==cat"=" { print cat"="list; next } { print }' \
+      "$CATEGORIES_CONFIG" > "$tmp"
+  else
+    # Append new line
+    if [[ -f "$CATEGORIES_CONFIG" ]]; then
+      cp "$CATEGORIES_CONFIG" "$tmp"
+    else
+      printf '# skill-tags category config — edit with: skill-tags --categories\n' > "$tmp"
+    fi
+    echo "${category}=${skill_list}" >> "$tmp"
+  fi
+
+  mv "$tmp" "$CATEGORIES_CONFIG"
+}
+
+# Remove a category from the config and delete its generated command file.
+delete_config_category() {
+  local category="$1"
+  [[ -f "$CATEGORIES_CONFIG" ]] || return 0
+  local tmp
+  tmp="$(mktemp)"
+  grep -v "^${category}=" "$CATEGORIES_CONFIG" > "$tmp" || true
+  mv "$tmp" "$CATEGORIES_CONFIG"
+  rm -f "${GLOBAL_COMMANDS_DIR}/skills-${category}.md"
+}
+
+# Interactive skill-selection UI for a category.
+# All display output goes to stderr; echoes the final comma-delimited skill list to stdout.
+select_skills_for_category() {
+  local category="$1"
+  local current_assignments="$2"
+
+  local skill_names=()
+  local skill_selected=()
+  local skill_tiers=()
+
+  # Build the full list of skills from SKILLS_META_DIR
+  for meta_file in "${SKILLS_META_DIR}"/*; do
+    [[ -f "$meta_file" ]] || continue
+    local sname
+    sname="$(basename "$meta_file")"
+    skill_names+=("$sname")
+
+    local tier
+    tier="$(skill_match_tier "$sname" "$category")"
+    skill_tiers+=("$tier")
+
+    # Pre-select if already in current_assignments, or if there's a tier match and
+    # this is a fresh category (no prior assignments).
+    if echo ":${current_assignments}:" | grep -q ":${sname}:"; then
+      skill_selected+=("1")
+    elif [[ -n "$tier" && -z "$current_assignments" ]]; then
+      skill_selected+=("1")
+    else
+      skill_selected+=("")
+    fi
+  done
+
+  while true; do
+    printf "\n  Category: %s\n" "$category" >&2
+    printf "  Skills (toggle by number, Enter to confirm):\n\n" >&2
+
+    local i=0
+    while [[ $i -lt ${#skill_names[@]} ]]; do
+      local sname="${skill_names[$i]}"
+      local tier="${skill_tiers[$i]}"
+      local sel="${skill_selected[$i]}"
+      local num=$(( i + 1 ))
+
+      local marker="[ ]"
+      [[ "$sel" == "1" ]] && marker="[*]"
+
+      local hint=""
+      local tags
+      tags="$(awk -F'|' '{print $3}' "${SKILLS_META_DIR}/${sname}" 2>/dev/null || true)"
+      if [[ "$tier" == "1" && -n "$tags" ]]; then
+        local readable_tags
+        readable_tags="$(echo "$tags" | tr ':' ', ' | sed 's/, $//')"
+        hint="  (metadata.tags: ${readable_tags})"
+      elif [[ "$tier" == "2" ]]; then
+        hint="  (keyword match)"
+      fi
+
+      printf "  %s %3d  %-45s%s\n" "$marker" "$num" "$sname" "$hint" >&2
+      i=$(( i + 1 ))
+    done
+
+    printf "\n  Toggle by number (space-separated) or Enter to confirm: " >&2
+    local input
+    read -r input
+
+    if [[ -z "$input" ]]; then
+      break
+    fi
+
+    for num in $input; do
+      if echo "$num" | grep -q '^[0-9][0-9]*$'; then
+        local idx=$(( num - 1 ))
+        if [[ $idx -ge 0 && $idx -lt ${#skill_names[@]} ]]; then
+          if [[ "${skill_selected[$idx]}" == "1" ]]; then
+            skill_selected[$idx]=""
+          else
+            skill_selected[$idx]="1"
+          fi
+        fi
+      fi
+    done
+  done
+
+  # Return the final comma-delimited list via stdout
+  local result=""
+  local i=0
+  while [[ $i -lt ${#skill_names[@]} ]]; do
+    if [[ "${skill_selected[$i]}" == "1" ]]; then
+      [[ -n "$result" ]] && result="${result},"
+      result="${result}${skill_names[$i]}"
+    fi
+    i=$(( i + 1 ))
+  done
+
+  echo "$result"
+}
+
+# ─── Category command ───────────────────────────────────────────────────────────
+
+cmd_categories() {
+  printf "\n  skill-tags: category wizard\n\n"
+  printf "  Scanning all skills...\n"
+
+  for entry in "${GLOBAL_SKILL_SOURCES[@]}"; do
+    local dir="${entry%%:*}"
+    [[ -d "$dir" ]] && scan_tree "$dir"
+  done
+  if [[ "$GLOBAL_ONLY" == "false" && -d ".agents/skills" ]]; then
+    scan_tree "$(pwd)/.agents/skills"
+  fi
+
+  printf "  Found %d skill(s)\n" "$count_found"
+
+  mkdir -p "$GLOBAL_COMMANDS_DIR"
+  if [[ ! -f "$CATEGORIES_CONFIG" ]]; then
+    printf '# skill-tags category config — edit with: skill-tags --categories\n' > "$CATEGORIES_CONFIG"
+  fi
+
+  # Main CRUD loop
+  while true; do
+    printf "\n  Current categories:\n"
+
+    local cat_names=()
+    local has_cats=false
+
+    if [[ -f "$CATEGORIES_CONFIG" ]]; then
+      while IFS='=' read -r cat_name skill_list; do
+        [[ "$cat_name" == "#"* || -z "$cat_name" ]] && continue
+        cat_names+=("$cat_name")
+        local count
+        count="$(echo "$skill_list" | awk -F',' '{print NF}')"
+        [[ -z "$skill_list" ]] && count=0
+        printf "    %d) %s (%s skills)\n" "${#cat_names[@]}" "$cat_name" "$count"
+        has_cats=true
+      done < "$CATEGORIES_CONFIG"
+    fi
+
+    if [[ "$has_cats" == "false" ]]; then
+      printf "    (none yet)\n"
+    fi
+
+    printf "\n  [a] Add    [e] Edit    [d] Delete    [s] Save & generate    [q] Quit\n"
+    printf "  > "
+    local action
+    read -r action
+
+    case "$action" in
+      a|A)
+        # Show predefined category list
+        printf "\n  Predefined categories:\n"
+        local pcat_names=()
+        local pcat
+        for pcat in $PREDEFINED_CATEGORIES; do
+          pcat_names+=("$pcat")
+          printf "    %d) %s\n" "${#pcat_names[@]}" "$pcat"
+        done
+        printf "    c) custom\n"
+        printf "  > "
+        local choice
+        read -r choice
+
+        local new_cat=""
+        if [[ "$choice" == "c" || "$choice" == "C" ]]; then
+          printf "  Category name (lowercase, hyphens ok): "
+          read -r new_cat
+          new_cat="$(echo "$new_cat" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')"
+        elif echo "$choice" | grep -q '^[0-9][0-9]*$'; then
+          local pidx=$(( choice - 1 ))
+          if [[ $pidx -ge 0 && $pidx -lt ${#pcat_names[@]} ]]; then
+            new_cat="${pcat_names[$pidx]}"
+          fi
+        fi
+
+        if [[ -n "$new_cat" ]]; then
+          local current
+          current="$(read_config_category "$new_cat")"
+          local result
+          result="$(select_skills_for_category "$new_cat" "$current")"
+          write_config_category "$new_cat" "$result"
+          printf "\n  ✓ Saved: %s\n" "$new_cat"
+        fi
+        ;;
+
+      e|E)
+        if [[ ${#cat_names[@]} -eq 0 ]]; then
+          printf "  No categories yet. Use [a] to add one.\n"
+          continue
+        fi
+        printf "  Edit which category? (number): "
+        local edit_num
+        read -r edit_num
+        if echo "$edit_num" | grep -q '^[0-9][0-9]*$'; then
+          local eidx=$(( edit_num - 1 ))
+          if [[ $eidx -ge 0 && $eidx -lt ${#cat_names[@]} ]]; then
+            local edit_cat="${cat_names[$eidx]}"
+            local current
+            current="$(read_config_category "$edit_cat")"
+            local result
+            result="$(select_skills_for_category "$edit_cat" "$current")"
+            write_config_category "$edit_cat" "$result"
+            printf "\n  ✓ Updated: %s\n" "$edit_cat"
+          fi
+        fi
+        ;;
+
+      d|D)
+        if [[ ${#cat_names[@]} -eq 0 ]]; then
+          printf "  No categories yet.\n"
+          continue
+        fi
+        printf "  Delete which category? (number): "
+        local del_num
+        read -r del_num
+        if echo "$del_num" | grep -q '^[0-9][0-9]*$'; then
+          local didx=$(( del_num - 1 ))
+          if [[ $didx -ge 0 && $didx -lt ${#cat_names[@]} ]]; then
+            local del_cat="${cat_names[$didx]}"
+            printf "  Delete '%s' and its generated file? [y/N] " "$del_cat"
+            local confirm
+            read -r confirm
+            local confirm_lower
+            confirm_lower="$(echo "$confirm" | tr '[:upper:]' '[:lower:]')"
+            if [[ "$confirm_lower" == "y" ]]; then
+              delete_config_category "$del_cat"
+              printf "  ✓ Deleted: %s\n" "$del_cat"
+            fi
+          fi
+        fi
+        ;;
+
+      s|S)
+        printf "\n  Generating category files...\n"
+        generate_category_files
+        printf "\n  Done. Run 'skill-tags' to rebuild the full index.\n\n"
+        exit 0
+        ;;
+
+      q|Q|"")
+        printf "\n  Exiting without generating files.\n\n"
+        exit 0
+        ;;
+    esac
+  done
+}
+
+# ─── Generate category files ────────────────────────────────────────────────────
+
+# Reads ~/.cursor/skill-tags-categories.conf and writes a skills-<category>.md
+# command file for each category. Called automatically on every sync when config exists.
+generate_category_files() {
+  [[ -f "$CATEGORIES_CONFIG" ]] || return 0
+
+  local gen_count=0
+
+  while IFS='=' read -r cat_name skill_list; do
+    [[ "$cat_name" == "#"* || -z "$cat_name" ]] && continue
+    [[ -z "$skill_list" ]] && continue
+
+    local title
+    title="$(to_title_case "$cat_name")"
+    local out="${GLOBAL_COMMANDS_DIR}/skills-${cat_name}.md"
+
+    local skills_section=""
+    while IFS= read -r sname; do
+      [[ -z "$sname" ]] && continue
+      local meta_file="${SKILLS_META_DIR}/${sname}"
+      if [[ -f "$meta_file" ]]; then
+        local display_path desc stitle
+        display_path="$(awk -F'|' '{print $1}' "$meta_file")"
+        desc="$(awk -F'|' '{print $2}' "$meta_file")"
+        stitle="$(to_title_case "$sname")"
+        skills_section="${skills_section}
+### ${stitle}
+\`${display_path}\`
+
+${desc}
+"
+      fi
+    done < <(echo "$skill_list" | tr ',' '\n')
+
+    cat > "$out" <<EOF
+# Skills: ${title}
+
+<!-- Auto-generated by sync.sh (skill-tags) v${VERSION} — do not edit manually -->
+
+Assess the following ${title} skills and apply any that are relevant to completing the user's request.
+
+CRITICAL REQUIREMENT: Before applying any skill, you MUST use the Read tool to read the full contents of the skill file at the provided path. Do not assume the skill's behavior from its title or description alone.
+
+If operating in Plan Mode, explicitly reference specific skills and subagents within the plan contents and TODOs.
+
+## ${title} Skills
+${skills_section}
+EOF
+
+    gen_count=$(( gen_count + 1 ))
+    success "Generated: ${out/#$HOME/~}"
+  done < "$CATEGORIES_CONFIG"
+
+  if [[ $gen_count -gt 0 ]]; then
+    printf "  Category files: %d generated\n" "$gen_count"
+  fi
+}
+
+# ─── Main ──────────────────────────────────────────────────────────────────────
+
+if [[ "$RUN_CATEGORIES" == "true" ]]; then
+  cmd_categories
+  exit 0
+fi
+
+printf "\n🔄 Cursor Skill Command Sync v%s\n\n" "$VERSION"
+
+# 1. Scan all global/user-level skill sources
+for entry in "${GLOBAL_SKILL_SOURCES[@]}"; do
+  dir="${entry%%:*}"
+  label="${entry##*:}"
+  if [[ -d "$dir" ]]; then
+    log "Scanning ${label}: ${dir/#$HOME/~}"
+    scan_tree "$dir"
+  fi
+done
+
+# 2. Project-level skills (.agents/skills in CWD)
+if [[ "$GLOBAL_ONLY" == "false" && -d ".agents/skills" ]]; then
+  log "Scanning project skills: $(pwd)/.agents/skills"
+  scan_tree "$(pwd)/.agents/skills"
+fi
+
+# ─── Write skill-tags.md ───────────────────────────────────────────────────────
+
+mkdir -p "$GLOBAL_COMMANDS_DIR"
+
+OPENING="Assess the following skills available in this workspace and apply any that are relevant to completing the user's request at the highest level of efficiency, quality, and completeness. When skills overlap in scope, assess the overlapping skills in greater detail and autonomously determine which is the best match for the project or the specific request — do not prompt the user to resolve overlaps.
+
+CRITICAL REQUIREMENT: Before applying any skill, you MUST use the Read tool to read the full contents of the skill file at the provided path. Do not assume the skill's behavior from its title or description alone.
+
+If operating in Plan Mode, explicitly include references to specific skills to use and (if applicable) subagents to utilize for efficient programming within the contents of the plan and the plan's TODOs.
+
+Examples:
+- \"Use the \`responsive-design/SKILL.md\` to apply advanced clamp-based responsiveness to the new navigation bar.\"
+- \"Delegate to the \`frontend-designer\` subagent using \`ui-ux-pro-max/SKILL.md\` to build the polished component.\"
+- \"Utilize \`supabase-postgres-best-practices/SKILL.md\` when designing the database schema for the user profiles.\""
+
+is_update=false
+[[ -f "$OUTPUT_FILE" ]] && is_update=true
+
+cat > "$OUTPUT_FILE" <<EOF
+# Skill Tags Command
+
+<!-- Auto-generated by sync.sh (skill-tags) v${VERSION} — do not edit manually -->
+
+${OPENING}
+
+## Available Skills
+$(cat "$SKILLS_TEMP")
+EOF
+
+# ─── Generate category files (if config exists) ────────────────────────────────
+
+generate_category_files
+
+# ─── Summary ───────────────────────────────────────────────────────────────────
+
+printf "\n"
+if [[ "$is_update" == "true" ]]; then
+  printf "  ↺ Updated:  %s\n" "${OUTPUT_FILE/#$HOME/~}"
+else
+  printf "  ✓ Generated: %s\n" "${OUTPUT_FILE/#$HOME/~}"
+fi
+printf "  Skills:    %d indexed\n" "$count_found"
+if [[ $count_dupes -gt 0 ]]; then
+  printf "  Dupes:     %d skill(s) skipped (covered by higher-priority source)\n" "$count_dupes"
+fi
+printf "\n  Tip: type /skill-tags in Cursor chat to load the full skills reference.\n\n"

package/uninstall.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# uninstall.sh
+# Removes skill-tags: deletes the sync script, removes the shell wrapper,
+# and optionally deletes generated command files.
+
+set -euo pipefail
+
+SYNC_SCRIPT="${HOME}/.cursor/sync-skill-commands.sh"
+COMMANDS_DIR="${HOME}/.cursor/commands"
+MARKER="# ─── skill-tags / Cursor Skill Command Sync"
+
+# Detect shell rc file
+detect_rc() {
+  if [[ -n "${ZSH_VERSION:-}" ]] || [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then
+    echo "${HOME}/.zshrc"
+  else
+    echo "${HOME}/.bash_profile"
+  fi
+}
+
+RC_FILE="$(detect_rc)"
+
+printf "\n🗑  skill-tags — Uninstaller\n\n"
+
+# 1. Remove sync script
+if [[ -f "$SYNC_SCRIPT" ]]; then
+  rm "$SYNC_SCRIPT"
+  printf "  ✓ Removed %s\n" "${SYNC_SCRIPT/#$HOME/~}"
+else
+  printf "  ~ Sync script not found (already removed?)\n"
+fi
+
+# 2. Remove shell wrapper from rc file
+if grep -q "$MARKER" "$RC_FILE" 2>/dev/null; then
+  # Remove the block from the marker line through the closing marker line
+  local_tmp="$(mktemp)"
+  awk "
+    /${MARKER//\//\\/}/{found=1}
+    found && /^# ─────/{if(++count==2){found=0; next}}
+    !found
+  " "$RC_FILE" > "$local_tmp"
+  mv "$local_tmp" "$RC_FILE"
+  printf "  ✓ Removed skills wrapper from %s\n" "${RC_FILE/#$HOME/~}"
+else
+  printf "  ~ Shell wrapper not found in %s\n" "${RC_FILE/#$HOME/~}"
+fi
+
+# 3. Optionally remove generated command files
+printf "\n  Remove generated command files in %s? [y/N] " "${COMMANDS_DIR/#$HOME/~}"
+read -r answer
+if [[ "${answer,,}" == "y" ]]; then
+  # Only remove auto-generated files (those with our comment marker)
+  removed=0
+  for f in "$COMMANDS_DIR"/*.md; do
+    [[ -f "$f" ]] || continue
+    if grep -q "Auto-generated by sync" "$f" 2>/dev/null; then
+      rm "$f"
+      removed=$(( removed + 1 ))
+    fi
+  done
+  printf "  ✓ Removed %d generated command file(s)\n" "$removed"
+else
+  printf "  ~ Keeping generated command files.\n"
+fi
+
+printf "\n  Done. Restart your shell or run: source %s\n\n" "${RC_FILE/#$HOME/~}"