skill-tags 1.3.0 → 1.5.0

package/README.md

@@ -24,36 +24,28 @@ 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
 
-### Global (recommended for most users)
-
-1. **Install:** `npm install skill-tags -g`
-2. **Setup:** `skill-tags --setup` → choose **Global** → `source ~/.zshrc`
-3. **Sync:** `skill-tags` (generates the command file)
-4. **Use:** Reference `@skill-tags.md` in any Cursor chat
+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
 npm install skill-tags -g
-skill-tags --setup   # choose: Global
+# Setup wizard runs automatically — choose Global + Auto (recommended)
 source ~/.zshrc
-skill-tags
 ```
 
-### Project-level
-
-1. **Install:** `npm install skill-tags --save-dev`
-2. **Setup:** `npx skill-tags --setup` → choose **Project**
-3. **Use:** Reference `@project-skill-tags.md` in Cursor chat
+For project-level installs:
 
 ```bash
 npm install skill-tags --save-dev
-npx skill-tags --setup   # choose: Project — adds "skills" script to package.json
-
+# Setup wizard runs automatically — choose Project + Auto
 npm run skills add owner/repo/skill-name   # adds skill + auto-syncs
 ```
 
@@ -79,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`.
 
 ---
 
@@ -109,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` — when prompted, choose Global and Auto (recommended)
-3. Source my shell rc file or instruct me to do so manually
-4. Run `skill-tags` to perform an initial sync of all installed skills
+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)
@@ -132,16 +127,14 @@ When complete, output a summary that includes:
 ### Global install (npm)
 
 ```bash
-npm install skill-tags -g
-skill-tags --setup   # choose: Global
+npm install skill-tags -g     # setup wizard runs automatically
 source ~/.zshrc
 ```
 
 ### Project install (npm)
 
 ```bash
-npm install skill-tags --save-dev
-npx skill-tags --setup   # choose: Project
+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.
@@ -153,7 +146,7 @@ npx skill-tags
 ```
 
 ### Install via curl
-
+ 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/steve-piece/skill-tags/main/install.sh | bash
 ```
@@ -181,11 +174,11 @@ skills add vercel-labs/agent-skills/vercel-react-best-practices
 
 ## Project-Level Install
 
-Install skill-tags as a dev dependency to manage project-specific skills without touching your global shell config. The `--setup` wizard adds a `"skills"` npm script backed by the bundled `st-skills` binary.
+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
-npx skill-tags --setup   # choose: Project
+# choose: Project + Auto when prompted
 ```
 
 After setup, `package.json` will include:
@@ -215,13 +208,15 @@ The `st-skills` binary (from this package) wraps `npx skills`, then automaticall
 ## CLI Reference
 
 ```bash
-skill-tags                # sync all skills, generate/update the command file
-skill-tags --categories   # open interactive category wizard (CRUD)
-skill-tags --setup        # interactive setup: choose Global (shell profile) or Project (package.json)
-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 --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)
@@ -295,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() {
@@ -214,95 +224,64 @@ function toTitleCase(str) {
 
 // ─── 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 matched = skills.filter(s => matchKeywords(s, cat));
-    config[cat] = matched.map(s => s.name);
-    console.log(`  ✓ ${toTitleCase(cat)}: ${matched.length} skill(s) auto-assigned\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 matched = skills.filter(s => matchKeywords(s, cat));
-  config[cat] = matched.map(s => s.name);
-  console.log(`  ✓ Re-generated ${toTitleCase(cat)}: ${matched.length} skill(s) auto-assigned\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) {
@@ -321,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`);
 
@@ -338,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,48 +1,82 @@
 #!/usr/bin/env node
 // bin/postinstall.js
 // Runs automatically after `npm install skill-tags`.
-// Global installs: perform initial sync. Local installs: print setup guidance.
+// 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);
 }
 
+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';
 
-if (!isGlobal) {
-  // Project (local) install — print setup guidance and exit cleanly
-  console.log('\n  skill-tags installed as a project dependency.');
-  console.log('  Run setup to add the "skills" npm script to your package.json:\n');
-  console.log('    npx skill-tags --setup\n');
-  process.exit(0);
-}
+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');
 
-// ─── Global install: run initial sync ────────────────────────────────────────
+    try {
+      return fs.readFileSync(rcFile, 'utf-8').includes(WRAPPER_MARKER);
+    } catch {
+      return false;
+    }
+  }
 
-const syncScript = path.join(__dirname, '..', 'sync.sh');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+    return pkg.scripts?.skills === 'st-skills';
+  } catch {
+    return false;
+  }
+}
 
-if (!fs.existsSync(syncScript)) {
-  process.exit(0);
+function runSync() {
+  if (!fs.existsSync(SYNC_SCRIPT)) return;
+  const { spawnSync } = require('child_process');
+  spawnSync('bash', [SYNC_SCRIPT], { stdio: 'inherit' });
 }
 
-console.log('\n  skill-tags: running initial sync...\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 result = spawnSync('bash', [syncScript], { stdio: 'inherit' });
-  if (result.error) throw result.error;
-} catch (_) {
-  // Never fail the install
+  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');
+    }
+  }
 }
 
-console.log('  To auto-sync after every `skills add`, run:');
-console.log('    skill-tags --setup\n');
-
-process.exit(0);
+main();

package/bin/skill-tags.js

@@ -37,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)
+    --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,9 +57,11 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
     ~/.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>
@@ -77,6 +81,64 @@ 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')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-tags",
-  "version": "1.3.0",
+  "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",

package/sync.sh

@@ -7,7 +7,7 @@
 
 set -euo pipefail
 
-VERSION="1.3.0"
+VERSION="1.5.0"
 
 GLOBAL_COMMANDS_DIR="${HOME}/.cursor/commands"
 OUTPUT_FILE="${GLOBAL_COMMANDS_DIR}/skill-tags.md"
@@ -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) 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,16 +253,18 @@ 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
   # ─── --local: scan only .agents/skills in CWD ───────────────────────────────
@@ -297,14 +305,19 @@ ${OPENING}
 $(cat "$SKILLS_TEMP")
 EOF
 
-  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"
+  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 @project-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