skill-tags 1.2.0 → 1.2.1

package/README.md

@@ -30,8 +30,8 @@ If you're interested in contributing to Cursor Kits, please let me know!
 ## Quick Start
 
 ```bash
-# Install (global, recommended)
-npm install -g skill-tags
+# Install
+npm install skill-tags -g
 
 # Add the shell auto-trigger wrapper
 skill-tags --setup
@@ -90,14 +90,10 @@ Copy and paste this into your Cursor agent to autoconfigure skill-tags:
 ```text
 Install and configure the `skill-tags` package (npm: https://www.npmjs.com/package/skill-tags, github: https://github.com/steve-piece/skill-tags) 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).
+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`
+1. Install the package: `npm install skill-tags -g`
 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
@@ -108,6 +104,7 @@ When complete, output a summary that includes:
 - 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
+- (Optional) To create category-specific indexes for more focused context, run `skill-tags --categories`
 ```
 
 </details>
@@ -119,21 +116,15 @@ When complete, output a summary that includes:
 ### 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
+npm install skill-tags -g
+skill-tags --setup
+source ~/.zshrc
 ```
 
-After global install, set up the shell auto-trigger wrapper:
+### One-off run (no install)
 
 ```bash
-skill-tags --setup
-source ~/.zshrc
+npx skill-tags
 ```
 
 ### Install via curl
@@ -166,12 +157,13 @@ skills add vercel-labs/agent-skills/vercel-react-best-practices
 ## 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
+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 (.agents/skills in CWD)
+skill-tags --project-only # scan only .agents/skills in CWD; write to .cursor/commands/skill-tags.md
+skill-tags --version      # print version
+skill-tags --help         # show usage
 ```
 
 ## Manual Sync

package/bin/skill-tags.js

@@ -38,12 +38,13 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   Usage: skill-tags [options]
 
   Options:
-    (none)           Scan all skill sources and generate skill-tags.md
-    --categories     Interactive category wizard (arrow keys + space to toggle)
-    --global-only    Skip project-level skills (.agents/skills in CWD)
-    --setup          Install the skills() shell wrapper in your shell rc
-    --version, -v    Print version
-    --help, -h       Show this help
+    (none)            Scan all skill sources and generate skill-tags.md
+    --categories      Interactive category wizard (arrow keys + space to toggle)
+    --global-only     Skip project-level skills (.agents/skills in CWD)
+    --project-only    Scan only .agents/skills in CWD; write to .cursor/commands/skill-tags.md
+    --setup           Install the skills() shell wrapper in your shell rc
+    --version, -v     Print version
+    --help, -h        Show this help
 
   Skill sources (priority order):
     ~/.agents/skills/              skills installed via npx skills add
@@ -56,6 +57,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   Output:
     ~/.cursor/commands/skill-tags.md          full index of all skills
     ~/.cursor/commands/skills-<category>.md   generated by --categories
+    ./.cursor/commands/skill-tags.md          generated by --project-only
 
   Config:
     ~/.cursor/skill-tags-categories.conf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-tags",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Generates consolidated command files (@skill-tags.md and custom @skills-<category>.md indexes) for all installed Cursor skills.",
   "bin": {
     "skill-tags": "bin/skill-tags.js"

package/sync.sh

@@ -7,11 +7,13 @@
 
 set -euo pipefail
 
-VERSION="1.2.0"
+VERSION="1.2.1"
 
 GLOBAL_COMMANDS_DIR="${HOME}/.cursor/commands"
 OUTPUT_FILE="${GLOBAL_COMMANDS_DIR}/skill-tags.md"
 CATEGORIES_CONFIG="${HOME}/.cursor/skill-tags-categories.conf"
+PROJECT_COMMANDS_DIR="$(pwd)/.cursor/commands"
+PROJECT_OUTPUT_FILE="${PROJECT_COMMANDS_DIR}/skill-tags.md"
 
 # ─── Priority-ordered skill source directories ─────────────────────────────────
 # Earlier entries take priority when the same skill name exists in multiple locations.
@@ -33,10 +35,12 @@ trap 'rm -f "$SKILLS_TEMP"; rm -rf "$SKILLS_META_DIR"' EXIT
 # ─── Flags ─────────────────────────────────────────────────────────────────────
 
 GLOBAL_ONLY=false
+PROJECT_ONLY=false
 
 for arg in "$@"; do
   case "$arg" in
-    --global-only) GLOBAL_ONLY=true ;;
+    --global-only)  GLOBAL_ONLY=true ;;
+    --project-only) PROJECT_ONLY=true ;;
   esac
 done
 
@@ -254,27 +258,72 @@ EOF
 
 printf "\n  skill-tags v%s — syncing skills\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"
+if [[ "$PROJECT_ONLY" == "true" ]]; then
+  # ─── --project-only: scan only .agents/skills in CWD ────────────────────────
+  PROJECT_SKILLS_DIR="$(pwd)/.agents/skills"
+
+  if [[ ! -d "$PROJECT_SKILLS_DIR" ]]; then
+    printf "  No project skills found at %s/.agents/skills\n\n" "$(pwd)"
+    exit 0
   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
+  log "Scanning project skills: ${PROJECT_SKILLS_DIR}"
+  scan_tree "$PROJECT_SKILLS_DIR"
+
+  OPENING="Assess the following project-level skills 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.\""
+
+  mkdir -p "$PROJECT_COMMANDS_DIR"
+
+  is_update=false
+  [[ -f "$PROJECT_OUTPUT_FILE" ]] && is_update=true
+
+  cat > "$PROJECT_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
+
+  printf "\n"
+  if [[ "$is_update" == "true" ]]; then
+    printf "  ✓ Updated:   .cursor/commands/skill-tags.md\n"
+  else
+    printf "  ✓ Generated: .cursor/commands/skill-tags.md\n"
+  fi
+  printf "  Skills:      %d indexed\n" "$count_found"
+  printf "\n  Tip: type @skill-tags.md in Cursor chat to load the project skills reference.\n\n"
 
-# ─── Write skill-tags.md ───────────────────────────────────────────────────────
+else
+  # ─── Default: scan all 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
 
-mkdir -p "$GLOBAL_COMMANDS_DIR"
+  if [[ "$GLOBAL_ONLY" == "false" && -d ".agents/skills" ]]; then
+    log "Scanning project skills: $(pwd)/.agents/skills"
+    scan_tree "$(pwd)/.agents/skills"
+  fi
 
-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.
+  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.
 
@@ -285,10 +334,12 @@ Examples:
 - \"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
+  mkdir -p "$GLOBAL_COMMANDS_DIR"
 
-cat > "$OUTPUT_FILE" <<EOF
+  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 -->
@@ -299,20 +350,18 @@ ${OPENING}
 $(cat "$SKILLS_TEMP")
 EOF
 
-# ─── Generate category files (if config exists) ────────────────────────────────
-
-generate_category_files
+  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 "  Duplicates:  %d skipped (covered by higher-priority source)\n" "$count_dupes"
+  fi
+  printf "\n  Tip: type @skill-tags.md in Cursor chat to load the full skills reference.\n\n"
 
-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 "  Duplicates:  %d skipped (covered by higher-priority source)\n" "$count_dupes"
 fi
-printf "\n  Tip: type @skill-tags.md in Cursor chat to load the full skills reference.\n\n"