skill-tags 1.2.1 → 1.3.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)
@@ -29,23 +30,38 @@ If you're interested in contributing to Cursor Kits, please let me know!
 
 ## 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
+
 ```bash
-# Install
 npm install skill-tags -g
-
-# Add the shell auto-trigger wrapper
-skill-tags --setup
+skill-tags --setup   # choose: Global
 source ~/.zshrc
-
-# Initial sync (generate command file)
 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
+
+```bash
+npm install skill-tags --save-dev
+npx skill-tags --setup   # choose: Project — adds "skills" script to package.json
+
+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:
 
@@ -94,9 +110,9 @@ Use a terminal that runs outside the sandbox with full permissions to avoid perm
 
 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
+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
 
 When complete, output a summary that includes:
 - Where the command file was generated (~/.cursor/commands/skill-tags.md)
@@ -113,14 +129,23 @@ When complete, output a summary that includes:
 
 ## Install Options
 
-### Install via npm
+### Global install (npm)
 
 ```bash
 npm install skill-tags -g
-skill-tags --setup
+skill-tags --setup   # choose: Global
 source ~/.zshrc
 ```
 
+### Project install (npm)
+
+```bash
+npm install skill-tags --save-dev
+npx skill-tags --setup   # choose: Project
+```
+
+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
@@ -141,31 +166,74 @@ 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 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
+```
+
+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 --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
 ```
 
+### `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 +260,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.

package/bin/categories.js

@@ -212,11 +212,6 @@ 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) {
@@ -256,25 +251,9 @@ async function addCategories(skills, config) {
   }
 
   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`);
+    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`);
   }
 }
 
@@ -293,26 +272,9 @@ async function editCategory(skills, config) {
     })),
   });
 
-  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`);
+  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) {

package/bin/postinstall.js

@@ -1,7 +1,7 @@
 #!/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`.
+// Global installs: perform initial sync. Local installs: print setup guidance.
 // Never throws — a failed postinstall should never break npm install.
 
 'use strict';
@@ -15,12 +15,18 @@ 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') {
+const isGlobal = process.env.npm_config_global === 'true';
+
+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);
 }
 
+// ─── Global install: run initial sync ────────────────────────────────────────
+
 const syncScript = path.join(__dirname, '..', 'sync.sh');
 
 if (!fs.existsSync(syncScript)) {

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,9 @@ 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
+    --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)
     --version, -v     Print version
     --help, -h        Show this help
 
@@ -55,12 +52,21 @@ 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
 
   Config:
     ~/.cursor/skill-tags-categories.conf
+
+  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);
 }
@@ -74,6 +80,7 @@ if (process.argv.includes('--categories')) {
 // ─── --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 +107,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.3.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.3.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.
@@ -39,8 +39,8 @@ PROJECT_ONLY=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 ;;
   esac
 done
 
@@ -259,7 +259,7 @@ EOF
 printf "\n  skill-tags v%s — syncing skills\n\n" "$VERSION"
 
 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
@@ -299,12 +299,12 @@ EOF
 
   printf "\n"
   if [[ "$is_update" == "true" ]]; then
-    printf "  ✓ Updated:   .cursor/commands/skill-tags.md\n"
+    printf "  ✓ Updated:   .cursor/commands/project-skill-tags.md\n"
   else
-    printf "  ✓ Generated: .cursor/commands/skill-tags.md\n"
+    printf "  ✓ Generated: .cursor/commands/project-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"
+  printf "\n  Tip: type @project-skill-tags.md in Cursor chat to load the project skills reference.\n\n"
 
 else
   # ─── Default: scan all sources ───────────────────────────────────────────────