skill-tags 1.2.1 → 1.5.0

package/README.md

@@ -16,6 +16,7 @@ If you're interested in contributing to Cursor Kits, please let me know!
 - [Agent Setup Prompt](#agent-setup-prompt)
 - [Install Options](#install-options)
 - [How It Works](#how-it-works)
+- [Project-Level Install](#project-level-install)
 - [CLI Reference](#cli-reference)
 - [Manual Sync](#manual-sync)
 - [Skill Sources Scanned](#skill-sources-scanned)
@@ -23,29 +24,36 @@ If you're interested in contributing to Cursor Kits, please let me know!
 - [How Categorization Works](#how-categorization-works)
 - [Uninstall](#uninstall)
 - [Requirements](#requirements)
+- [Changelog](#changelog)
 - [License](#license)
 
 ---
 
 ## Quick Start
 
+1. **Install:** `npm install skill-tags -g` (or `--save-dev` for project-level)
+2. **Follow the prompts** — choose **Global** or **Project**, then **Auto** or **Manual** sync
+3. **Use:** Reference `@skill-tags.md` in any Cursor chat
+
 ```bash
-# Install
 npm install skill-tags -g
-
-# Add the shell auto-trigger wrapper
-skill-tags --setup
+# Setup wizard runs automatically — choose Global + Auto (recommended)
 source ~/.zshrc
+```
 
-# Initial sync (generate command file)
-skill-tags
+For project-level installs:
+
+```bash
+npm install skill-tags --save-dev
+# Setup wizard runs automatically — choose Project + Auto
+npm run skills add owner/repo/skill-name   # adds skill + auto-syncs
 ```
 
 ## Usage
 
 In any Cursor chat, attach the full index of your skills by referencing the generated command file:
 
-- `@skill-tags.md`
+- `@skill-tags.md` (global) or `@project-skill-tags.md` (local, from `skill-tags --local`)
 
 Example:
 
@@ -63,20 +71,25 @@ For more focused context windows, you can group your skills into category-specif
 skill-tags --categories
 ```
 
-This opens an interactive wizard where you can create, edit, and delete categories. Skill assignment is powered by keyword matching against the generated `skill-tags.md` index — all text is lowercased with strict full-word matching and automatic suffix expansion (plurals, gerunds, etc.) to avoid false positives.
-
-Suggested skills are pre-selected (`[*]`). Use arrow keys and space to toggle any skill before confirming.
+This opens an interactive wizard where you can add and remove categories. On save, skill assignment is powered by keyword matching against the generated `skill-tags.md` index — all text is lowercased with strict full-word matching and automatic suffix expansion (plurals, gerunds, etc.) to avoid false positives.
 
 Once configured, every `skill-tags` sync automatically regenerates the category files from the saved config at `~/.cursor/skill-tags-categories.conf`.
 
+For project-level categories (using only skills in `.agents/skills/`):
+
+```bash
+skill-tags --categories --local
+```
+
+Then reference focused category indexes instead of the full list:
+
 ```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`, `design`, `accessibility`, `performance`, `ai-agents`, `devops`, `marketing`, `mobile`, `documentation`. You can also create custom categories with any name.
+Predefined categories: `frontend`, `backend`, `database`, `testing`, `design`, `accessibility`, `performance`, `ai-agents`, `devops`, `marketing`, `mobile`, `documentation`.
 
 ---
 
@@ -93,10 +106,8 @@ Install and configure the `skill-tags` package (npm: https://www.npmjs.com/packa
 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: `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
+1. Install the package: `npm install skill-tags -g` — the setup wizard runs automatically during install; when prompted, choose Global and Auto (recommended)
+2. 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)
@@ -113,14 +124,21 @@ When complete, output a summary that includes:
 
 ## Install Options
 
-### Install via npm
+### Global install (npm)
 
 ```bash
-npm install skill-tags -g
-skill-tags --setup
+npm install skill-tags -g     # setup wizard runs automatically
 source ~/.zshrc
 ```
 
+### Project install (npm)
+
+```bash
+npm install skill-tags --save-dev    # setup wizard runs automatically
+```
+
+Adds `"skills": "st-skills"` to `package.json`. Use `npm run skills add <pkg>` to add project skills — auto-syncs `.cursor/commands/project-skill-tags.md` on every change.
+
 ### One-off run (no install)
 
 ```bash
@@ -128,7 +146,7 @@ npx skill-tags
 ```
 
 ### Install via curl
-
+ 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/steve-piece/skill-tags/main/install.sh | bash
 ```
@@ -141,31 +159,76 @@ 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`:
+After global 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:
+# The command file is updated:
 # ~/.cursor/commands/skill-tags.md
 
 # Use it in Cursor chat:
 # @skill-tags.md
 ```
 
+## Project-Level Install
+
+Install skill-tags as a dev dependency to manage project-specific skills without touching your global shell config. The setup wizard runs automatically during install and adds a `"skills"` npm script backed by the bundled `st-skills` binary.
+
+```bash
+npm install skill-tags --save-dev
+# choose: Project + Auto when prompted
+```
+
+After setup, `package.json` will include:
+
+```json
+"scripts": {
+  "skills": "st-skills"
+}
+```
+
+Use `npm run skills` to add, remove, or update project skills:
+
+```bash
+npm run skills add owner/repo/skill-name     # adds skill + auto-syncs
+npm run skills remove owner/repo/skill-name  # removes skill + auto-syncs
+npm run skills update owner/repo/skill-name  # updates skill + auto-syncs
+
+# Manual re-sync:
+skill-tags --local
+
+# Use in Cursor chat:
+# @project-skill-tags.md
+```
+
+The `st-skills` binary (from this package) wraps `npx skills`, then automatically runs `skill-tags --local` on every successful `add`, `remove`, or `update`, writing the index to `.cursor/commands/project-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 (.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
+skill-tags                       # sync all skills, generate/update the command file
+skill-tags --categories          # open interactive category wizard
+skill-tags --categories --local  # category wizard for project-level skills only
+skill-tags --setup               # re-run setup wizard (runs automatically on first install)
+skill-tags --global              # skip local skills (.agents/skills in CWD); scan global sources only
+skill-tags --local               # scan only .agents/skills in CWD; write to .cursor/commands/project-skill-tags.md
+skill-tags --latest              # update skill-tags to the latest version
+skill-tags --version             # print version
+skill-tags --help                # show usage
+```
+
+### `st-skills` (project binary)
+
+```bash
+npm run skills add <pkg>     # install a project skill + auto-sync
+npm run skills remove <pkg>  # remove a project skill + auto-sync
+npm run skills update <pkg>  # update a project skill + auto-sync
 ```
 
+`st-skills` is registered in `package.json` by `skill-tags --setup` (local mode). It wraps `npx skills` and calls `skill-tags --local` after every mutating command.
+
 ## Manual Sync
 
 Run at any time to regenerate the command file:
@@ -192,7 +255,7 @@ Skills are discovered from all of these locations automatically. When the same s
 
 ## Generated File Format
 
-The `~/.cursor/commands/skill-tags.md` contains:
+The `~/.cursor/commands/skill-tags.md` (global) and `./.cursor/commands/project-skill-tags.md` (local) contain:
 
 - 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.
@@ -227,6 +290,47 @@ bash uninstall.sh
 - bash or zsh
 - [Cursor IDE](https://cursor.com)
 
+## Changelog
+
+### v1.5.0
+
+- **`--latest` flag** — run `skill-tags --latest` to check npm for updates and self-update in place
+- **Project-level categories** — `skill-tags --categories --local` runs the category wizard using only project skills (`.agents/skills/`), stores config in `.cursor/skill-tags-categories.conf`, and generates category files in `.cursor/commands/`
+- **Simplified category wizard** — streamlined to three actions: Add categories (multi-select from predefined list), Edit categories (multi-select to remove), and Save changes (runs keyword matching on save)
+- **Quieter sync from wizard** — `sync.sh` accepts `--quiet` to suppress verbose scan output; the category wizard uses it for cleaner post-save output with an aligned summary table
+- **Removed custom category input** — categories are now limited to the predefined list for consistency
+
+### v1.4.0
+
+- Interactive `--categories` wizard with keyword-based auto-assignment
+- Category config persistence at `~/.cursor/skill-tags-categories.conf`
+- Auto-regeneration of category files on every sync
+- Predefined categories: frontend, backend, database, testing, design, accessibility, performance, ai-agents, devops, marketing, mobile, documentation
+
+### v1.3.0
+
+- `--local` flag for project-level skill scanning
+- `st-skills` binary for project-level add/remove/update with auto-sync
+- Project setup mode in `--setup` wizard
+
+### v1.2.0
+
+- `--global` flag to skip local skills
+- `--setup` wizard with Global and Project modes
+- Shell wrapper auto-sync on `skills add/remove`
+
+### v1.1.0
+
+- Deduplication across skill sources (first-found wins by priority)
+- Support for nested plugin cache directories
+- Description extraction from YAML frontmatter and first content line
+
+### v1.0.0
+
+- Initial release
+- Scans all known skill locations and generates `~/.cursor/commands/skill-tags.md`
+- Priority-ordered skill sources with deduplication
+
 ## License
 
 MIT

package/bin/categories.js

@@ -5,18 +5,26 @@
 
 'use strict';
 
-const { checkbox, select, input, confirm } = require('@inquirer/prompts');
+const { checkbox, select } = require('@inquirer/prompts');
 const { spawnSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
 const HOME = os.homedir();
-const CATEGORIES_CONFIG = path.join(HOME, '.cursor', 'skill-tags-categories.conf');
-const COMMANDS_DIR = path.join(HOME, '.cursor', 'commands');
-const SKILL_TAGS_FILE = path.join(COMMANDS_DIR, 'skill-tags.md');
+const IS_LOCAL = process.argv.includes('--local');
 const SYNC_SCRIPT = path.join(__dirname, '..', 'sync.sh');
 
+const CATEGORIES_CONFIG = IS_LOCAL
+  ? path.join(process.cwd(), '.cursor', 'skill-tags-categories.conf')
+  : path.join(HOME, '.cursor', 'skill-tags-categories.conf');
+const COMMANDS_DIR = IS_LOCAL
+  ? path.join(process.cwd(), '.cursor', 'commands')
+  : path.join(HOME, '.cursor', 'commands');
+const SKILL_TAGS_FILE = IS_LOCAL
+  ? path.join(process.cwd(), '.cursor', 'commands', 'project-skill-tags.md')
+  : path.join(HOME, '.cursor', 'commands', 'skill-tags.md');
+
 const PREDEFINED_CATEGORIES = [
   'frontend',
   'backend',
@@ -119,8 +127,10 @@ const CATEGORY_KEYWORDS = {
 
 function ensureSkillTagsFile() {
   if (fs.existsSync(SKILL_TAGS_FILE)) return;
-  console.log('  skill-tags.md not found — running initial sync...\n');
-  spawnSync('bash', [SYNC_SCRIPT], { stdio: 'inherit' });
+  const label = IS_LOCAL ? 'project-skill-tags.md' : 'skill-tags.md';
+  console.log(`  ${label} not found — running initial sync...\n`);
+  const args = IS_LOCAL ? [SYNC_SCRIPT, '--local'] : [SYNC_SCRIPT];
+  spawnSync('bash', args, { stdio: 'inherit' });
 }
 
 function loadSkillsFromIndex() {
@@ -212,135 +222,66 @@ function toTitleCase(str) {
   return str.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
-function truncate(str, len) {
-  if (!str || str.length <= len) return str || '';
-  return str.slice(0, len - 1) + '…';
-}
-
 // ─── Wizard actions ──────────────────────────────────────────────────────────
 
-async function addCategories(skills, config) {
+async function addCategories(config) {
   const existing = new Set(Object.keys(config));
   const available = PREDEFINED_CATEGORIES.filter(c => !existing.has(c));
 
-  let selected = [];
-  if (available.length > 0) {
-    selected = await checkbox({
-      message: 'Select categories to add (space to toggle)',
-      choices: available.map(c => ({ name: toTitleCase(c), value: c })),
-      pageSize: 14,
-    });
-  } else {
-    console.log('\n  All predefined categories already exist.');
+  if (available.length === 0) {
+    console.log('\n  All categories already added.\n');
+    return;
   }
 
-  const custom = await input({
-    message: 'Custom category name (blank to skip):',
+  const selected = await checkbox({
+    message: 'Select categories to add (space to toggle)',
+    choices: available.map(c => ({ name: toTitleCase(c), value: c })),
+    pageSize: 14,
   });
 
-  if (custom.trim()) {
-    const normalized = custom.trim().toLowerCase()
-      .replace(/[^a-z0-9-]/g, '-')
-      .replace(/-+/g, '-')
-      .replace(/^-|-$/g, '');
-    if (normalized && !existing.has(normalized)) {
-      selected.push(normalized);
-    } else if (existing.has(normalized)) {
-      console.log(`  "${normalized}" already exists — use Edit instead.`);
-    }
-  }
-
   if (selected.length === 0) {
     console.log('  No categories selected.\n');
     return;
   }
 
   for (const cat of selected) {
-    const skillChoices = skills.map(s => {
-      const match = matchKeywords(s, cat);
-      const hint = match ? ` — ${match.reason}` : '';
-      return {
-        name: `${s.name}${hint}`,
-        value: s.name,
-        checked: !!match,
-        description: truncate(s.description, 60),
-      };
-    });
-
-    const selectedSkills = await checkbox({
-      message: `Select skills for "${cat}" (space to toggle)`,
-      choices: skillChoices,
-      pageSize: 15,
-    });
-
-    config[cat] = selectedSkills;
-    console.log(`  ✓ ${toTitleCase(cat)}: ${selectedSkills.length} skill(s)\n`);
+    config[cat] = [];
+    console.log(`  + ${toTitleCase(cat)}`);
   }
+  console.log();
 }
 
-async function editCategory(skills, config) {
-  const cats = Object.keys(config);
-  if (cats.length === 0) {
-    console.log('  No categories yet. Add one first.\n');
-    return;
-  }
-
-  const cat = await select({
-    message: 'Which category to edit?',
-    choices: cats.map(c => ({
-      name: `${toTitleCase(c)} (${config[c].length} skills)`,
-      value: c,
-    })),
-  });
-
-  const currentSet = new Set(config[cat] || []);
-  const skillChoices = skills.map(s => {
-    const match = matchKeywords(s, cat);
-    const hint = match ? ` — ${match.reason}` : '';
-    return {
-      name: `${s.name}${hint}`,
-      value: s.name,
-      checked: currentSet.has(s.name),
-      description: truncate(s.description, 60),
-    };
-  });
-
-  const selectedSkills = await checkbox({
-    message: `Select skills for "${cat}" (space to toggle)`,
-    choices: skillChoices,
-    pageSize: 15,
-  });
-
-  config[cat] = selectedSkills;
-  console.log(`  ✓ Updated ${toTitleCase(cat)}: ${selectedSkills.length} skill(s)\n`);
-}
-
-async function deleteCategory(config) {
+async function editCategories(config) {
   const cats = Object.keys(config);
   if (cats.length === 0) {
-    console.log('  No categories yet.\n');
+    console.log('  No categories yet. Add some first.\n');
     return;
   }
 
-  const cat = await select({
-    message: 'Which category to delete?',
+  const kept = await checkbox({
+    message: 'Uncheck categories to remove (space to toggle)',
     choices: cats.map(c => ({
       name: `${toTitleCase(c)} (${config[c].length} skills)`,
       value: c,
+      checked: true,
     })),
+    pageSize: 14,
   });
 
-  const yes = await confirm({
-    message: `Delete "${cat}" and its generated command file?`,
-    default: false,
-  });
+  const keptSet = new Set(kept);
+  const removed = cats.filter(c => !keptSet.has(c));
 
-  if (yes) {
+  for (const cat of removed) {
     delete config[cat];
     const genFile = path.join(COMMANDS_DIR, `skills-${cat}.md`);
     try { fs.unlinkSync(genFile); } catch {}
-    console.log(`  ✓ Deleted: ${cat}\n`);
+    console.log(`  - Removed: ${toTitleCase(cat)}`);
+  }
+
+  if (removed.length === 0) {
+    console.log('  No changes.');
   }
+  console.log();
 }
 
 function printCurrentCategories(config) {
@@ -359,11 +300,13 @@ function printCurrentCategories(config) {
 // ─── Main loop ───────────────────────────────────────────────────────────────
 
 async function main() {
-  console.log('\n  skill-tags: category wizard\n');
+  const mode = IS_LOCAL ? 'project' : 'global';
+  const indexFile = IS_LOCAL ? 'project-skill-tags.md' : 'skill-tags.md';
+  console.log(`\n  skill-tags: category wizard (${mode})\n`);
 
   ensureSkillTagsFile();
 
-  console.log('  Loading skills from skill-tags.md...');
+  console.log(`  Loading skills from ${indexFile}...`);
   const skills = loadSkillsFromIndex();
   console.log(`  Found ${skills.length} skill(s)\n`);
 
@@ -376,30 +319,60 @@ async function main() {
       message: 'What would you like to do?',
       choices: [
         { name: 'Add categories', value: 'add' },
-        { name: 'Edit a category', value: 'edit' },
-        { name: 'Delete a category', value: 'delete' },
-        { name: 'Save & generate files', value: 'save' },
+        { name: 'Edit categories', value: 'edit' },
+        { name: 'Save changes', value: 'save' },
         { name: 'Quit without saving', value: 'quit' },
       ],
     });
 
     switch (action) {
       case 'add':
-        await addCategories(skills, config);
+        await addCategories(config);
         break;
       case 'edit':
-        await editCategory(skills, config);
-        break;
-      case 'delete':
-        await deleteCategory(config);
+        await editCategories(config);
         break;
       case 'save': {
+        const cats = Object.keys(config);
+        if (cats.length === 0) {
+          console.log('  No categories to save.\n');
+          break;
+        }
+
+        const pad = Math.max(...cats.map(c => toTitleCase(c).length));
+
+        console.log();
+        console.log('  ┌─ Matching skills to categories ─────────────────');
+        for (const cat of cats) {
+          const matched = skills.filter(s => matchKeywords(s, cat));
+          config[cat] = matched.map(s => s.name);
+          const label = toTitleCase(cat).padEnd(pad);
+          const count = String(matched.length).padStart(2);
+          console.log(`  │  ✓ ${label}  ${count} skill${matched.length === 1 ? '' : 's'}`);
+        }
+        console.log('  └─────────────────────────────────────────────────');
+
         writeConfig(config);
-        console.log('\n  Config saved. Running sync...\n');
-        const result = spawnSync('bash', [SYNC_SCRIPT], { stdio: 'inherit' });
+
+        const syncArgs = IS_LOCAL
+          ? [SYNC_SCRIPT, '--local', '--quiet']
+          : [SYNC_SCRIPT, '--quiet'];
+        console.log(`\n  Syncing ${skills.length} skills...\n`);
+        const result = spawnSync('bash', syncArgs, { stdio: 'inherit' });
         if (result.error) {
-          console.error(`  Error running sync: ${result.error.message}`);
+          console.error(`  Error: ${result.error.message}`);
+          process.exit(1);
+        }
+
+        const configPath = IS_LOCAL
+          ? '.cursor/skill-tags-categories.conf'
+          : '~/.cursor/skill-tags-categories.conf';
+        console.log(`  ✓ Config saved → ${configPath}`);
+        console.log(`  ✓ ${cats.length} category file${cats.length === 1 ? '' : 's'} generated`);
+        for (const cat of cats) {
+          console.log(`    @skills-${cat}.md`);
         }
+        console.log(`\n  Tip: type @skills-<category>.md in Cursor chat to use a category.\n`);
         process.exit(result.status ?? 0);
       }
       case 'quit':

package/bin/postinstall.js

@@ -1,42 +1,82 @@
 #!/usr/bin/env node
 // bin/postinstall.js
-// Runs automatically after `npm install -g skill-tags`.
-// Performs an initial sync of any already-installed skills.
+// Runs automatically after `npm install skill-tags`.
+// Launches interactive setup wizard on first install; re-syncs on reinstall.
+// Falls back gracefully for non-interactive environments (CI, piped input).
 // 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');
+const os = require('os');
 
-// 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 HOME = os.homedir();
+const isGlobal = process.env.npm_config_global === 'true';
+const SYNC_SCRIPT = path.join(__dirname, '..', 'sync.sh');
+const WRAPPER_MARKER = '# ─── skill-tags / Cursor Skill Command Sync';
 
-const syncScript = path.join(__dirname, '..', 'sync.sh');
+function isAlreadyConfigured() {
+  if (isGlobal) {
+    const shellName = path.basename(process.env.SHELL || 'bash');
+    let rcFile;
+    if (shellName === 'zsh') rcFile = path.join(HOME, '.zshrc');
+    else if (process.platform === 'darwin') rcFile = path.join(HOME, '.bash_profile');
+    else rcFile = path.join(HOME, '.bashrc');
 
-if (!fs.existsSync(syncScript)) {
-  process.exit(0);
-}
+    try {
+      return fs.readFileSync(rcFile, 'utf-8').includes(WRAPPER_MARKER);
+    } catch {
+      return false;
+    }
+  }
 
-console.log('\n  skill-tags: running initial sync...\n');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+    return pkg.scripts?.skills === 'st-skills';
+  } catch {
+    return false;
+  }
+}
 
-try {
-  const result = spawnSync('bash', [syncScript], { stdio: 'inherit' });
-  if (result.error) throw result.error;
-} catch (_) {
-  // Never fail the install
+function runSync() {
+  if (!fs.existsSync(SYNC_SCRIPT)) return;
+  const { spawnSync } = require('child_process');
+  spawnSync('bash', [SYNC_SCRIPT], { stdio: 'inherit' });
 }
 
-console.log('  To auto-sync after every `skills add`, run:');
-console.log('    skill-tags --setup\n');
+async function main() {
+  if (isAlreadyConfigured()) {
+    if (isGlobal) {
+      console.log('\n  skill-tags: re-syncing...\n');
+      runSync();
+    } else {
+      console.log('\n  skill-tags: already configured.\n');
+    }
+    return;
+  }
+
+  try {
+    const runSetup = require('./setup');
+    await runSetup();
+  } catch (err) {
+    if (err.name === 'ExitPromptError') {
+      console.log();
+      return;
+    }
+    if (isGlobal) {
+      console.log('\n  skill-tags: running initial sync...\n');
+      runSync();
+      console.log('  To configure auto-sync, run: skill-tags --setup\n');
+    } else {
+      console.log('\n  skill-tags installed as a project dependency.');
+      console.log('  Run setup to configure: npx skill-tags --setup\n');
+    }
+  }
+}
 
-process.exit(0);
+main();

package/bin/setup.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// bin/setup.js
+// Interactive setup wizard: global/project install mode + auto/manual sync preference.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const HOME = os.homedir();
+const SYNC_SCRIPT = path.join(__dirname, '..', 'sync.sh');
+const WRAPPER_MARKER = '# ─── skill-tags / Cursor Skill Command Sync';
+
+module.exports = async function runSetup() {
+  const { select, confirm } = require('@inquirer/prompts');
+
+  console.log('\n  skill-tags: setup\n');
+
+  const isGlobal = process.env.npm_config_global === 'true';
+
+  const mode = await select({
+    message: 'How are you using skill-tags?',
+    choices: [
+      {
+        name: 'Global  — add skills() wrapper to shell profile (recommended for most users)',
+        value: 'global',
+      },
+      {
+        name: 'Project — add "skills" npm script to this project\'s package.json',
+        value: 'project',
+      },
+    ],
+    default: isGlobal ? 'global' : 'project',
+  });
+
+  const syncMode = await select({
+    message: 'How should skill-tags sync?',
+    choices: [
+      {
+        name: 'Auto (recommended) — sync automatically whenever you add or remove a skill',
+        value: 'auto',
+      },
+      {
+        name: 'Manual — run skill-tags yourself to sync when needed',
+        value: 'manual',
+      },
+    ],
+    default: 'auto',
+  });
+
+  if (mode === 'global') {
+    await setupGlobal(confirm, syncMode);
+  } else {
+    await setupProject(confirm, syncMode);
+  }
+};
+
+// ─── Global setup ─────────────────────────────────────────────────────────────
+
+async function setupGlobal(confirm, syncMode) {
+  const shellName = path.basename(process.env.SHELL || 'bash');
+  let rcFile;
+  if (shellName === 'zsh') rcFile = path.join(HOME, '.zshrc');
+  else if (process.platform === 'darwin') rcFile = path.join(HOME, '.bash_profile');
+  else rcFile = path.join(HOME, '.bashrc');
+
+  const displayRc = rcFile.replace(HOME, '~');
+
+  if (syncMode === 'manual') {
+    console.log('\n  Manual sync selected.');
+    console.log('  Run skill-tags at any time to regenerate ~/.cursor/commands/skill-tags.md\n');
+    console.log('  Running initial sync...\n');
+    spawnSync('bash', [SYNC_SCRIPT], { stdio: 'inherit' });
+    console.log(`\n  Done! Run skill-tags manually to re-sync.\n`);
+    return;
+  }
+
+  // Auto sync: add shell wrapper
+  let alreadyInstalled = false;
+  try {
+    const content = fs.readFileSync(rcFile, 'utf-8');
+    if (content.includes(WRAPPER_MARKER)) alreadyInstalled = true;
+  } catch {}
+
+  if (alreadyInstalled) {
+    console.log(`\n  ✓ Shell wrapper already installed in ${displayRc}\n`);
+    process.exit(0);
+  }
+
+  console.log(`\n  This will add a skills() shell wrapper to ${displayRc}`);
+  console.log(`  It auto-syncs skill-tags.md after every skills add/remove.\n`);
+
+  const yes = await confirm({
+    message: `Add the wrapper to ${displayRc}?`,
+    default: true,
+  });
+
+  if (!yes) {
+    console.log('\n  Skipped.\n');
+    process.exit(0);
+  }
+
+  const syncPath = fs.existsSync(path.join(HOME, '.cursor', 'sync-skill-commands.sh'))
+    ? path.join(HOME, '.cursor', 'sync-skill-commands.sh')
+    : SYNC_SCRIPT;
+
+  const wrapper = `
+${WRAPPER_MARKER} ────────────────────────────────────────────────
+# Wraps \`npx skills\` to auto-generate skill-tags.md after install/removal.
+# Run manually: skill-tags   (or: bash ${syncPath})
+function skills() {
+  npx skills "$@"
+  local exit_code=$?
+  if [[ "$1" == "add" || "$1" == "remove" ]] && [[ $exit_code -eq 0 ]]; then
+    bash "${syncPath}"
+  fi
+  return $exit_code
+}
+# ─────────────────────────────────────────────────────────────────────────────
+`;
+
+  try {
+    fs.appendFileSync(rcFile, wrapper);
+  } catch (err) {
+    console.error(`\n  Failed to write to ${displayRc}: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n  ✓ Added skills() wrapper to ${displayRc}`);
+  console.log(`  Reload with: source ${displayRc}\n`);
+}
+
+// ─── Project setup ────────────────────────────────────────────────────────────
+
+async function setupProject(confirm, syncMode) {
+  const pkgPath = path.join(process.cwd(), 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    console.error('\n  No package.json found in current directory.');
+    console.error('  Run skill-tags --setup from your project root.\n');
+    process.exit(1);
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch (err) {
+    console.error(`\n  Failed to read package.json: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const scripts = pkg.scripts || {};
+
+  if (syncMode === 'manual') {
+    console.log('\n  Manual sync selected.');
+    console.log('  Run skill-tags --local at any time to regenerate .cursor/commands/project-skill-tags.md\n');
+    console.log('  Running initial project sync...\n');
+    spawnSync(
+      'node',
+    [path.join(__dirname, 'skill-tags.js'), '--local'],
+    { stdio: 'inherit', cwd: process.cwd() }
+  );
+  console.log(`\n  Done! Run skill-tags --local manually to re-sync.\n`);
+    return;
+  }
+
+  // Auto sync: add "skills" npm script
+  if (scripts.skills === 'st-skills') {
+    console.log('\n  ✓ Already configured — "skills": "st-skills" is in package.json\n');
+    console.log('  Add a skill:  npm run skills add <owner/repo/skill-name>');
+    console.log('  Remove:       npm run skills remove <owner/repo/skill-name>\n');
+    process.exit(0);
+  }
+
+  console.log('\n  This will add a "skills" script to your package.json:');
+  console.log('    "scripts": { "skills": "st-skills" }');
+  console.log('\n  Then use:  npm run skills add <owner/repo/skill-name>');
+  console.log('  Auto-syncs .cursor/commands/project-skill-tags.md after every add/remove.\n');
+
+  const yes = await confirm({
+    message: 'Add the "skills" script to package.json?',
+    default: true,
+  });
+
+  if (!yes) {
+    console.log('\n  Skipped.\n');
+    process.exit(0);
+  }
+
+  pkg.scripts = { ...scripts, skills: 'st-skills' };
+
+  try {
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+  } catch (err) {
+    console.error(`\n  Failed to write package.json: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  console.log('\n  ✓ Added "skills": "st-skills" to package.json');
+  console.log('\n  Running initial project sync...\n');
+
+  const result = spawnSync(
+    'node',
+    [path.join(__dirname, 'skill-tags.js'), '--local'],
+    { stdio: 'inherit', cwd: process.cwd() }
+  );
+
+  if (result.error) {
+    console.error(`\n  Warning: initial sync failed — ${result.error.message}`);
+  }
+
+  console.log('\n  Setup complete!\n');
+  console.log('  Add a skill:   npm run skills add <owner/repo/skill-name>');
+  console.log('  Remove:        npm run skills remove <owner/repo/skill-name>');
+  console.log('  Manual sync:   skill-tags --local\n');
+}

package/bin/skill-tags.js

@@ -7,12 +7,9 @@
 const { spawnSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
-const os = require('os');
 
 const VERSION = require('../package.json').version;
-const HOME = os.homedir();
 const SYNC_SCRIPT = path.join(__dirname, '..', 'sync.sh');
-const WRAPPER_MARKER = '# ─── skill-tags / Cursor Skill Command Sync';
 
 // ─── --version ───────────────────────────────────────────────────────────────
 
@@ -40,9 +37,11 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   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)
-    --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
+    --categories --local  Category wizard for project-level skills only
+    --global          Skip local skills (.agents/skills in CWD); scan global sources only
+    --local           Scan only .agents/skills in CWD; write to .cursor/commands/project-skill-tags.md
+    --setup           Interactive setup: choose Global (shell profile) or Project (package.json)
+    --latest          Update skill-tags to the latest version
     --version, -v     Print version
     --help, -h        Show this help
 
@@ -55,12 +54,23 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
     ./.agents/skills/              project-level skills (current directory)
 
   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
+    ~/.cursor/commands/skill-tags.md           full index of all skills (global)
+    ~/.cursor/commands/skills-<category>.md    generated by --categories
+    ./.cursor/commands/project-skill-tags.md   generated by --local
+    ./.cursor/commands/skills-<category>.md    generated by --categories --local
 
   Config:
-    ~/.cursor/skill-tags-categories.conf
+    ~/.cursor/skill-tags-categories.conf       global category config
+    ./.cursor/skill-tags-categories.conf       project category config (--categories --local)
+
+  Setup modes:
+    Global   Adds skills() wrapper to ~/.zshrc — use: skills add <pkg>
+    Project  Adds "skills": "st-skills" to package.json — use: npm run skills add <pkg>
+
+  Project binary (st-skills):
+    st-skills add <pkg>      Install a project skill and auto-sync
+    st-skills remove <pkg>   Remove a project skill and auto-sync
+    st-skills update <pkg>   Update a project skill and auto-sync
 `);
   process.exit(0);
 }
@@ -71,9 +81,68 @@ if (process.argv.includes('--categories')) {
   require('./categories');
 }
 
+// ─── --latest ────────────────────────────────────────────────────────────────
+
+else if (process.argv.includes('--latest')) {
+  const https = require('https');
+
+  function getLatestVersion() {
+    return new Promise((resolve, reject) => {
+      https.get('https://registry.npmjs.org/skill-tags/latest', { headers: { Accept: 'application/json' } }, res => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end', () => {
+          try { resolve(JSON.parse(data).version); }
+          catch { reject(new Error('Failed to parse registry response')); }
+        });
+      }).on('error', reject);
+    });
+  }
+
+  (async () => {
+    console.log(`\n  skill-tags v${VERSION}\n`);
+
+    let latest;
+    try {
+      process.stdout.write('  Checking for updates...');
+      latest = await getLatestVersion();
+      process.stdout.write(` v${latest}\n`);
+    } catch (err) {
+      console.error(`\n  Could not reach npm registry: ${err.message}\n`);
+      process.exit(1);
+    }
+
+    if (latest === VERSION) {
+      console.log('  Already on the latest version.\n');
+      process.exit(0);
+    }
+
+    console.log(`  Updating: v${VERSION} → v${latest}\n`);
+    const result = spawnSync('npm', ['install', '-g', 'skill-tags@latest'], {
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    if (result.error) {
+      console.error(`\n  Update failed: ${result.error.message}`);
+      console.error('  Try manually: npm install -g skill-tags@latest\n');
+      process.exit(1);
+    }
+
+    if (result.status !== 0) {
+      console.error('\n  Update failed. You may need to run with sudo:');
+      console.error('  sudo npm install -g skill-tags@latest\n');
+      process.exit(result.status);
+    }
+
+    console.log(`\n  ✓ Updated to v${latest}\n`);
+  })();
+}
+
 // ─── --setup ─────────────────────────────────────────────────────────────────
 
 else if (process.argv.includes('--setup')) {
+  const runSetup = require('./setup');
   runSetup().catch(err => {
     if (err.name === 'ExitPromptError') { console.log(); process.exit(0); }
     console.error('  Error:', err.message);
@@ -100,72 +169,3 @@ else {
 
   process.exit(result.status ?? 0);
 }
-
-// ─── Setup implementation ────────────────────────────────────────────────────
-
-async function runSetup() {
-  const { confirm } = require('@inquirer/prompts');
-
-  const shellName = path.basename(process.env.SHELL || 'bash');
-  let rcFile;
-  if (shellName === 'zsh') rcFile = path.join(HOME, '.zshrc');
-  else if (process.platform === 'darwin') rcFile = path.join(HOME, '.bash_profile');
-  else rcFile = path.join(HOME, '.bashrc');
-
-  const displayRc = rcFile.replace(HOME, '~');
-
-  console.log(`\n  skill-tags: shell setup\n`);
-
-  let alreadyInstalled = false;
-  try {
-    const content = fs.readFileSync(rcFile, 'utf-8');
-    if (content.includes(WRAPPER_MARKER)) alreadyInstalled = true;
-  } catch {}
-
-  if (alreadyInstalled) {
-    console.log(`  ✓ Shell wrapper already installed in ${displayRc}\n`);
-    process.exit(0);
-  }
-
-  console.log(`  This will add a skills() shell wrapper to ${displayRc}`);
-  console.log(`  It auto-syncs skill-tags.md after every skills add/remove.\n`);
-
-  const yes = await confirm({
-    message: `Add the wrapper to ${displayRc}?`,
-    default: true,
-  });
-
-  if (!yes) {
-    console.log('\n  Skipped.\n');
-    process.exit(0);
-  }
-
-  const syncPath = fs.existsSync(path.join(HOME, '.cursor', 'sync-skill-commands.sh'))
-    ? path.join(HOME, '.cursor', 'sync-skill-commands.sh')
-    : SYNC_SCRIPT;
-
-  const wrapper = `
-${WRAPPER_MARKER} ────────────────────────────────────────────────
-# Wraps \`npx skills\` to auto-generate skill-tags.md after install/removal.
-# Run manually: skill-tags   (or: bash ${syncPath})
-function skills() {
-  npx skills "$@"
-  local exit_code=$?
-  if [[ "$1" == "add" || "$1" == "remove" ]] && [[ $exit_code -eq 0 ]]; then
-    bash "${syncPath}"
-  fi
-  return $exit_code
-}
-# ─────────────────────────────────────────────────────────────────────────────
-`;
-
-  try {
-    fs.appendFileSync(rcFile, wrapper);
-  } catch (err) {
-    console.error(`\n  Failed to write to ${displayRc}: ${err.message}\n`);
-    process.exit(1);
-  }
-
-  console.log(`\n  ✓ Added skills() wrapper to ${displayRc}`);
-  console.log(`  Reload with: source ${displayRc}\n`);
-}

package/bin/st-skills.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// bin/st-skills.js
+// Project-level skills wrapper: runs npx skills and auto-syncs project-skill-tags.md on add/remove/update.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+
+// Run npx skills with all forwarded arguments
+const result = spawnSync('npx', ['skills', ...args], { stdio: 'inherit', shell: false });
+
+if (result.error) {
+  console.error(`\n  st-skills: failed to run npx skills — ${result.error.message}\n`);
+  process.exit(1);
+}
+
+const exitCode = result.status ?? 1;
+
+// Auto-sync project-skill-tags.md on successful mutating subcommands
+if (['add', 'remove', 'update'].includes(subcommand) && exitCode === 0) {
+  const syncResult = spawnSync(
+    'node',
+    [path.join(__dirname, 'skill-tags.js'), '--local'],
+    { stdio: 'inherit', cwd: process.cwd() }
+  );
+
+  if (syncResult.error) {
+    console.error(`\n  st-skills: sync failed — ${syncResult.error.message}\n`);
+  }
+}
+
+process.exit(exitCode);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "skill-tags",
-  "version": "1.2.1",
+  "version": "1.5.0",
   "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"
+    "skill-tags": "bin/skill-tags.js",
+    "st-skills": "bin/st-skills.js"
   },
   "scripts": {
     "postinstall": "node ./bin/postinstall.js"

package/sync.sh

@@ -7,13 +7,13 @@
 
 set -euo pipefail
 
-VERSION="1.2.1"
+VERSION="1.5.0"
 
 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"
+PROJECT_OUTPUT_FILE="${PROJECT_COMMANDS_DIR}/project-skill-tags.md"
 
 # ─── Priority-ordered skill source directories ─────────────────────────────────
 # Earlier entries take priority when the same skill name exists in multiple locations.
@@ -36,11 +36,13 @@ trap 'rm -f "$SKILLS_TEMP"; rm -rf "$SKILLS_META_DIR"' EXIT
 
 GLOBAL_ONLY=false
 PROJECT_ONLY=false
+QUIET=false
 
 for arg in "$@"; do
   case "$arg" in
-    --global-only)  GLOBAL_ONLY=true ;;
-    --project-only) PROJECT_ONLY=true ;;
+    --global) GLOBAL_ONLY=true ;;
+    --local)  PROJECT_ONLY=true ;;
+    --quiet)  QUIET=true ;;
   esac
 done
 
@@ -49,8 +51,8 @@ done
 count_found=0
 count_dupes=0
 
-log()     { printf "  %s\n" "$*"; }
-success() { printf "  ✓ %s\n" "$*"; }
+log()     { [[ "$QUIET" == "true" ]] || printf "  %s\n" "$*"; }
+success() { [[ "$QUIET" == "true" ]] || printf "  ✓ %s\n" "$*"; }
 
 # Tracks which skill names have already been processed (deduplication).
 # Uses a delimited string for bash 3.2 compatibility (no associative arrays).
@@ -192,10 +194,14 @@ scan_tree() {
 
 # ─── 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.
+# Reads a categories config and writes a skills-<category>.md command file for each.
+# Usage: generate_category_files [config_file] [commands_dir]
+# Defaults to global paths when called without arguments.
 generate_category_files() {
-  [[ -f "$CATEGORIES_CONFIG" ]] || return 0
+  local config_file="${1:-$CATEGORIES_CONFIG}"
+  local commands_dir="${2:-$GLOBAL_COMMANDS_DIR}"
+
+  [[ -f "$config_file" ]] || return 0
 
   local gen_count=0
 
@@ -205,7 +211,7 @@ generate_category_files() {
 
     local title
     title="$(to_title_case "$cat_name")"
-    local out="${GLOBAL_COMMANDS_DIR}/skills-${cat_name}.md"
+    local out="${commands_dir}/skills-${cat_name}.md"
 
     local skills_section=""
     while IFS= read -r sname; do
@@ -247,19 +253,21 @@ EOF
 
     gen_count=$(( gen_count + 1 ))
     success "Generated: ${out/#$HOME/~}"
-  done < "$CATEGORIES_CONFIG"
+  done < "$config_file"
 
-  if [[ $gen_count -gt 0 ]]; then
+  if [[ $gen_count -gt 0 && "$QUIET" != "true" ]]; then
     printf "  Category files: %d generated\n" "$gen_count"
   fi
 }
 
 # ─── Main ──────────────────────────────────────────────────────────────────────
 
-printf "\n  skill-tags v%s — syncing skills\n\n" "$VERSION"
+if [[ "$QUIET" != "true" ]]; then
+  printf "\n  skill-tags v%s — syncing skills\n\n" "$VERSION"
+fi
 
 if [[ "$PROJECT_ONLY" == "true" ]]; then
-  # ─── --project-only: scan only .agents/skills in CWD ────────────────────────
+  # ─── --local: scan only .agents/skills in CWD ───────────────────────────────
   PROJECT_SKILLS_DIR="$(pwd)/.agents/skills"
 
   if [[ ! -d "$PROJECT_SKILLS_DIR" ]]; then
@@ -297,14 +305,19 @@ ${OPENING}
 $(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"
+  PROJECT_CATEGORIES_CONFIG="$(pwd)/.cursor/skill-tags-categories.conf"
+  generate_category_files "$PROJECT_CATEGORIES_CONFIG" "$PROJECT_COMMANDS_DIR"
+
+  if [[ "$QUIET" != "true" ]]; then
+    printf "\n"
+    if [[ "$is_update" == "true" ]]; then
+      printf "  ✓ Updated:   .cursor/commands/project-skill-tags.md\n"
+    else
+      printf "  ✓ Generated: .cursor/commands/project-skill-tags.md\n"
+    fi
+    printf "  Skills:      %d indexed\n" "$count_found"
+    printf "\n  Tip: type @project-skill-tags.md in Cursor chat to load the project skills reference.\n\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"
 
 else
   # ─── Default: scan all sources ───────────────────────────────────────────────
@@ -352,16 +365,18 @@ EOF
 
   generate_category_files
 
-  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"
+  if [[ "$QUIET" != "true" ]]; then
+    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"
   fi
-  printf "\n  Tip: type @skill-tags.md in Cursor chat to load the full skills reference.\n\n"
 
 fi