ginskill-init 1.0.0 → 1.0.1

package/DEVELOPMENT.md

@@ -0,0 +1,510 @@
+# GinStudio Skills — Development Guide
+
+Everything you need to contribute skills, release new versions, and manage the CLI.
+
+---
+
+## Table of Contents
+
+1. [Project Structure](#project-structure)
+2. [How to Add a New Skill](#how-to-add-a-new-skill)
+3. [How to Add a New Agent](#how-to-add-a-new-agent)
+4. [How to Release (Publish to npm)](#how-to-release-publish-to-npm)
+5. [CLI Reference](#cli-reference)
+6. [How Users Install Skills](#how-users-install-skills)
+7. [How to Upgrade Installed Skills](#how-to-upgrade-installed-skills)
+8. [How to Uninstall](#how-to-uninstall)
+9. [Local Development & Testing](#local-development--testing)
+10. [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Structure
+
+```
+ginstudio-skills/
+├── bin/
+│   └── cli.js              # npm CLI entrypoint (ginskill-init)
+├── skills/
+│   └── my-skill/           # One directory per skill
+│       ├── SKILL.md        # Main skill file (required)
+│       ├── docs/           # Supporting docs loaded at runtime
+│       └── scripts/        # Shell scripts used by the skill
+├── agents/
+│   ├── my-agent.md         # Single-file agent (simple)
+│   └── my-agent/           # Directory agent (with supporting files)
+│       └── agent.md
+├── package.json            # npm package config
+├── .npmignore              # Files excluded from npm publish
+├── .gitignore
+├── README.md
+└── DEVELOPMENT.md          # This file
+```
+
+---
+
+## How to Add a New Skill
+
+### 1. Create the skill directory
+
+```bash
+mkdir -p skills/my-skill/docs
+mkdir -p skills/my-skill/scripts
+```
+
+### 2. Write `SKILL.md` (required)
+
+Every skill needs a `SKILL.md` at `skills/my-skill/SKILL.md`.
+
+**Minimal template:**
+
+```markdown
+---
+name: my-skill
+description: |
+  Short description visible to Claude when deciding to load this skill.
+  - MANDATORY TRIGGERS: keyword1, keyword2, keyword3
+  - Use this skill when the user wants to: do X, Y, Z
+argument-hint: "[optional | args | here]"
+disable-model-invocation: false
+---
+
+# My Skill Title
+
+You are an expert in [domain]. Help the user [goal].
+
+## Step 1 — Do Something
+
+...instructions...
+
+## Step 2 — Do Something Else
+
+...
+```
+
+**SKILL.md frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Identifier, must match the directory name |
+| `description` | yes | Shown to Claude; include `MANDATORY TRIGGERS` keywords |
+| `argument-hint` | no | Shown in `/skill-name [hint]` |
+| `disable-model-invocation` | no | Set `true` to block Claude from calling models inside the skill |
+| `user-invocable` | no | Set `false` for domain-knowledge skills that auto-load but aren't called directly |
+
+**Rules:**
+- Keep `SKILL.md` under **500 lines**. Move excess content to `docs/`.
+- Put reusable deep-dives in `docs/*.md` and load them via a script or inline reference.
+- Scripts go in `scripts/` and are invoked with `` !`bash skills/my-skill/scripts/my-script.sh $ARGUMENTS` ``.
+
+### 3. Load docs dynamically (optional)
+
+Create `scripts/load-tutorial.sh` if your skill routes to different docs based on arguments:
+
+```bash
+#!/bin/bash
+TOPIC="${1:-overview}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DOCS_DIR="$SCRIPT_DIR/../docs"
+
+case "$TOPIC" in
+  intro)   cat "$DOCS_DIR/intro.md" ;;
+  advanced) cat "$DOCS_DIR/advanced.md" ;;
+  *)       cat "$DOCS_DIR/overview.md" ;;
+esac
+```
+
+Then in `SKILL.md`:
+
+```markdown
+!`bash skills/my-skill/scripts/load-tutorial.sh $ARGUMENTS`
+```
+
+### 4. Register the skill's auto-triggers
+
+The `description` field in the frontmatter is used by Claude to decide when to auto-load the skill. Include:
+
+```yaml
+description: |
+  Brief one-liner.
+  - MANDATORY TRIGGERS: the exact words or phrases that should trigger it
+  - Use this skill when the user wants to: create X, build Y, fix Z
+```
+
+### 5. Test the skill locally
+
+```bash
+# Install from local repo to a test .claude directory
+node bin/cli.js --skills my-skill -t /tmp/test-project
+
+# Verify it's there
+ls /tmp/test-project/.claude/skills/my-skill/
+
+# In Claude Code, invoke directly
+/my-skill
+# Or let it auto-trigger by describing your goal
+```
+
+---
+
+## How to Add a New Agent
+
+Agents live in `agents/` and are copied to `.claude/agents/` during install.
+
+### Simple agent (single `.md` file)
+
+Create `agents/my-agent.md`:
+
+```markdown
+---
+name: my-agent
+description: Use this agent to do X. TRIGGER when user asks about Y.
+tools: Read, Grep, Glob, Bash
+model: claude-haiku-4-5-20251001
+---
+
+You are a specialized agent for [domain].
+
+## Capabilities
+...
+
+## Instructions
+...
+```
+
+### Directory agent (with supporting files)
+
+Create `agents/my-agent/` directory with an `agent.md` (or any `.md`) and supporting scripts/configs.
+
+### Agent frontmatter fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Agent identifier |
+| `description` | When to invoke; visible in `/agents` list |
+| `tools` | Comma-separated tool allowlist (restricts what the agent can call) |
+| `model` | Override the model (e.g., `claude-haiku-4-5-20251001` for speed) |
+
+### Test the agent
+
+```bash
+node bin/cli.js --agents my-agent -t /tmp/test-project
+# In Claude Code: "Use the my-agent agent to [task]"
+# Or: /agents  to verify it appears
+```
+
+---
+
+## How to Release (Publish to npm)
+
+### Prerequisites
+
+- npm account with access to the `ginskill-init` package
+- `npm login` completed
+
+### Step 1 — Bump the version
+
+```bash
+# patch: 1.0.0 → 1.0.1  (bug fixes, content updates)
+npm version patch
+
+# minor: 1.0.0 → 1.1.0  (new skills/agents added)
+npm version minor
+
+# major: 1.0.0 → 2.0.0  (breaking changes to CLI or skill format)
+npm version major
+```
+
+This updates `package.json` and creates a git tag automatically.
+
+### Step 2 — Preview what will be published
+
+```bash
+npm pack --dry-run
+```
+
+Check that:
+- No `node_modules/` is included
+- No `screenshots/`, `evals/`, or large media files
+- All `skills/` and `agents/` directories are present
+- Total size is reasonable (< 2MB target)
+
+### Step 3 — Publish
+
+```bash
+npm publish
+```
+
+For a pre-release (beta):
+
+```bash
+npm version prerelease --preid=beta   # 1.1.0-beta.0
+npm publish --tag beta
+# Users install with: npx ginskill-init@beta
+```
+
+### Step 4 — Push the tag
+
+```bash
+git push && git push --tags
+```
+
+### What `.npmignore` excludes
+
+The `.npmignore` file keeps the package small by excluding:
+
+```
+**/screenshots/    # demo images
+**/evals/          # evaluation files
+**/*.mov, *.mp4    # video files
+node_modules/
+install.py, install.js   # legacy installers
+*.local.json
+**/.env*
+```
+
+To add more exclusions, edit `.npmignore`. **Do not add a `files` field to `package.json`** — it overrides `.npmignore` and can accidentally include everything.
+
+---
+
+## CLI Reference
+
+```
+ginskill-init [command] [options]
+```
+
+### Default: `install`
+
+```bash
+ginskill-init                           # Interactive TUI — select skills/agents
+ginskill-init --all                     # Install everything, no prompts
+ginskill-init --skills react-query,mongodb
+ginskill-init --agents developer,tester
+ginskill-init -g                        # Install to ~/.claude (global)
+ginskill-init -t /path/to/project       # Install to specific project
+```
+
+### `upgrade`
+
+Re-copies installed skills/agents from the bundled version.
+
+```bash
+ginskill-init upgrade                   # Interactive — choose what to upgrade
+ginskill-init upgrade --all             # Upgrade everything
+ginskill-init upgrade -t /path/to/project
+ginskill-init upgrade -g
+```
+
+### `uninstall` (alias: `remove`)
+
+Removes installed skills/agents from the target `.claude/` directory.
+
+```bash
+ginskill-init uninstall                 # Interactive — choose what to remove
+ginskill-init uninstall -t /path/to/project
+ginskill-init uninstall -g
+```
+
+### `status` (alias: `info`)
+
+Shows which skills/agents are installed vs available.
+
+```bash
+ginskill-init status
+ginskill-init status -t /path/to/project
+ginskill-init status -g
+```
+
+### `list` (alias: `ls`)
+
+Lists all skills and agents bundled in this package (not what's installed).
+
+```bash
+ginskill-init list
+```
+
+### `versions` (alias: `ver`)
+
+Fetches all published versions from the npm registry.
+
+```bash
+ginskill-init versions
+```
+
+### Global flags (work on all commands)
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--global` | `-g` | Target `~/.claude/` (available in all projects) |
+| `--target <path>` | `-t` | Target a specific project directory |
+| `--version` | `-V` | Print CLI version |
+| `--help` | `-h` | Print help |
+
+---
+
+## How Users Install Skills
+
+### One-time install (recommended)
+
+```bash
+npx ginskill-init
+```
+
+Runs the interactive TUI to select skills and agents.
+
+### Install to a specific project
+
+```bash
+cd /path/to/my-project
+npx ginskill-init
+# or
+npx ginskill-init -t /path/to/my-project
+```
+
+### Install globally (all projects)
+
+```bash
+npx ginskill-init -g
+# or
+npx ginskill-init --global
+```
+
+### Non-interactive (CI/scripts)
+
+```bash
+npx ginskill-init --all                         # all skills + agents
+npx ginskill-init --skills react-query,mongodb  # specific skills only
+npx ginskill-init --agents developer            # specific agent only
+npx ginskill-init --all -g                      # everything, globally
+```
+
+---
+
+## How to Upgrade Installed Skills
+
+When a new version of `ginskill-init` is published, users upgrade their installed skills by running:
+
+```bash
+# Interactive — choose which skills/agents to upgrade
+npx ginskill-init@latest upgrade
+
+# Upgrade everything silently
+npx ginskill-init@latest upgrade --all
+
+# Upgrade in a specific project
+npx ginskill-init@latest upgrade -t /path/to/project
+```
+
+The `upgrade` command re-copies skills/agents from the npm package, overwriting the existing files. Only skills/agents already installed are shown.
+
+---
+
+## How to Uninstall
+
+### Remove specific skills/agents interactively
+
+```bash
+ginskill-init uninstall
+# or from any version:
+npx ginskill-init uninstall
+```
+
+### Remove from a specific project
+
+```bash
+ginskill-init uninstall -t /path/to/project
+```
+
+### Remove globally installed skills
+
+```bash
+ginskill-init uninstall -g
+```
+
+### Manual removal
+
+Skills are plain directories — you can also delete them manually:
+
+```bash
+# Remove a specific skill
+rm -rf .claude/skills/my-skill
+
+# Remove a specific agent
+rm .claude/agents/my-agent.md
+# or
+rm -rf .claude/agents/my-agent/
+```
+
+---
+
+## Local Development & Testing
+
+### Setup
+
+```bash
+cd ginstudio-skills
+npm install
+```
+
+### Run CLI locally
+
+```bash
+node bin/cli.js --help
+node bin/cli.js list
+node bin/cli.js status -t /tmp/test
+node bin/cli.js --all -t /tmp/test
+node bin/cli.js upgrade --all -t /tmp/test
+node bin/cli.js uninstall -t /tmp/test
+```
+
+### Link globally for testing
+
+```bash
+npm link
+# Now you can run: ginskill-init --help
+npm unlink ginskill-init   # when done
+```
+
+### Test pack before publishing
+
+```bash
+npm pack --dry-run         # preview what's included
+npm pack                   # creates ginskill-init-x.x.x.tgz
+# Test install from the tgz:
+npx ./ginskill-init-x.x.x.tgz
+```
+
+---
+
+## Troubleshooting
+
+### Skills not appearing in Claude Code
+
+Run `/agents` or restart Claude Code after installing. Skills are picked up on session start.
+
+### `npx ginskill-init` installs an old version
+
+Force the latest:
+
+```bash
+npx ginskill-init@latest
+# or clear npx cache:
+npx --yes ginskill-init@latest
+```
+
+### Target not recognized
+
+If `-t /path/to/project` seems to be ignored, make sure you're passing it **after** the command:
+
+```bash
+ginskill-init upgrade -t /path/to/project   ✓
+ginskill-init -t /path/to/project upgrade   ✗  (flag consumed by parent)
+```
+
+### Package is too large
+
+Check `.npmignore` is present and `package.json` has no `files` field. Run `npm pack --dry-run` to inspect.
+
+### Skill doesn't auto-trigger
+
+Verify the `description` frontmatter in `SKILL.md` includes `MANDATORY TRIGGERS` with the exact words the user would say.

package/bin/cli.js

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
 
-import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'fs';
+import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync, rmSync, readFileSync } from 'fs';
 import { homedir } from 'os';
+import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
 import prompts from 'prompts';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const PACKAGE_DIR  = join(__dirname, '..');
-const SRC_SKILLS   = join(PACKAGE_DIR, 'skills');
-const SRC_AGENTS   = join(PACKAGE_DIR, 'agents');
+const __dirname  = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = join(__dirname, '..');
+const SRC_SKILLS  = join(PACKAGE_DIR, 'skills');
+const SRC_AGENTS  = join(PACKAGE_DIR, 'agents');
+const PKG         = JSON.parse(readFileSync(join(PACKAGE_DIR, 'package.json'), 'utf-8'));
 
-// ─── Utils ────────────────────────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 
 function getDirs(dir) {
   if (!existsSync(dir)) return [];
@@ -29,6 +30,10 @@ function getMdFiles(dir) {
     .map(f => f.replace('.md', ''));
 }
 
+function unique(arr) {
+  return [...new Set(arr)];
+}
+
 function copyDir(src, dest) {
   mkdirSync(dest, { recursive: true });
   for (const entry of readdirSync(src)) {
@@ -38,37 +43,64 @@ function copyDir(src, dest) {
 }
 
 function resolveTarget(targetArg, isGlobal) {
-  if (isGlobal) return join(homedir(), '.claude');
-  if (targetArg)  return join(targetArg, '.claude');
+  if (isGlobal)  return join(homedir(), '.claude');
+  if (targetArg) return join(targetArg, '.claude');
   return join(process.cwd(), '.claude');
 }
 
-// ─── Logger ──────────────────────────────────────────────────────────────────
+function getAvailable() {
+  const skills = getDirs(SRC_SKILLS);
+  const agents = unique([...getDirs(SRC_AGENTS), ...getMdFiles(SRC_AGENTS)]);
+  return { skills, agents };
+}
+
+function getInstalled(claudeDir) {
+  const skills = getDirs(join(claudeDir, 'skills'))
+    .filter(s => getDirs(SRC_SKILLS).includes(s));           // only ours
+  const agentDir = join(claudeDir, 'agents');
+  const available = getAvailable().agents;
+  const agents = unique([
+    ...getDirs(agentDir),
+    ...getMdFiles(agentDir),
+  ]).filter(a => available.includes(a));
+  return { skills, agents };
+}
+
+// ─── Logger ───────────────────────────────────────────────────────────────────
 
 const log = {
   title:   msg => console.log('\n' + chalk.bold.cyan(msg) + '\n'),
-  info:    msg => console.log(chalk.blue('  info ') + msg),
-  success: msg => console.log(chalk.green('  ✓ ') + msg),
-  warn:    msg => console.log(chalk.yellow('  warn ') + msg),
+  info:    msg => console.log(chalk.blue('  info  ') + msg),
+  success: msg => console.log(chalk.green('  ✓  ') + msg),
+  warn:    msg => console.log(chalk.yellow('  warn  ') + msg),
+  error:   msg => console.log(chalk.red('  error ') + msg),
   dim:     msg => console.log(chalk.dim('  ' + msg)),
 };
 
-// ─── Install Logic ────────────────────────────────────────────────────────────
+const onCancel = () => { log.warn('Cancelled.'); process.exit(0); };
 
-async function runInstall({ target, skills, agents }) {
+// ─── Core Install ─────────────────────────────────────────────────────────────
+
+async function runInstall({ target, skills, agents, verb = 'Installed' }) {
   const destSkills = join(target, 'skills');
   const destAgents = join(target, 'agents');
-  const spinner = ora({ text: 'Installing...', color: 'cyan' }).start();
+
+  if (skills.length === 0 && agents.length === 0) {
+    log.warn('Nothing selected.');
+    return;
+  }
+
+  const spinner = ora({ text: 'Working...', color: 'cyan' }).start();
   let count = 0;
 
   for (const skill of skills) {
-    spinner.text = `Installing skill ${chalk.cyan(skill)}...`;
+    spinner.text = `${verb.replace('d','ing')} skill ${chalk.cyan(skill)}...`;
     copyDir(join(SRC_SKILLS, skill), join(destSkills, skill));
     count++;
   }
 
   for (const agent of agents) {
-    spinner.text = `Installing agent ${chalk.cyan(agent)}...`;
+    spinner.text = `${verb.replace('d','ing')} agent ${chalk.cyan(agent)}...`;
     const srcDir  = join(SRC_AGENTS, agent);
     const srcFile = join(SRC_AGENTS, `${agent}.md`);
     mkdirSync(destAgents, { recursive: true });
@@ -80,39 +112,48 @@ async function runInstall({ target, skills, agents }) {
     count++;
   }
 
-  if (count === 0) {
-    spinner.warn('Nothing selected to install.');
-    return;
-  }
-
-  spinner.succeed(chalk.bold.green(`Done! ${count} item(s) installed`));
+  spinner.succeed(chalk.bold.green(`${verb}! ${count} item(s)`));
   console.log();
   log.info(`Target: ${chalk.cyan(target)}`);
-  log.dim('Restart Claude Code (or run /agents) to pick up the changes.');
+  log.dim('Restart Claude Code (or run /agents) to pick up changes.');
   console.log();
 }
 
-// ─── Interactive TUI ──────────────────────────────────────────────────────────
+// ─── Multiselect helper ───────────────────────────────────────────────────────
 
-async function interactiveInstall(options) {
-  const { global: isGlobal, all: isAll, skills: skillsFlag, agents: agentsFlag, target: targetArg } = options;
+async function multiSelect(message, choices) {
+  const { selected } = await prompts({
+    type: 'multiselect',
+    name: 'selected',
+    message,
+    choices,
+    hint: 'Space to toggle · A to toggle all · Enter to confirm',
+    instructions: false,
+    min: 0,
+  }, { onCancel });
+  return selected ?? [];
+}
 
-  log.title('GinStudio Skills Installer');
+async function confirmPrompt(message) {
+  const { ok } = await prompts({ type: 'confirm', name: 'ok', message, initial: true }, { onCancel });
+  return ok;
+}
 
-  const allSkills = getDirs(SRC_SKILLS);
-  const allAgents = [...getDirs(SRC_AGENTS), ...getMdFiles(SRC_AGENTS)]
-    .filter((v, i, a) => a.indexOf(v) === i);
+// ─── COMMAND: install ─────────────────────────────────────────────────────────
 
-  const target = resolveTarget(targetArg, isGlobal);
+async function cmdInstall(options, targetArg) {
+  log.title('GinStudio — Install Skills & Agents');
 
-  // ── Shortcut flags ─────────────────────────────────────────────────────────
+  const target  = resolveTarget(options.target || targetArg, options.global);
+  const { skills: allSkills, agents: allAgents } = getAvailable();
 
-  if (isAll || skillsFlag || agentsFlag) {
-    let skills = isAll ? allSkills
-      : skillsFlag ? skillsFlag.split(',').map(s => s.trim()).filter(s => allSkills.includes(s))
+  // Non-interactive shortcut flags
+  if (options.all || options.skills || options.agents) {
+    const skills = options.all ? allSkills
+      : options.skills ? options.skills.split(',').map(s => s.trim()).filter(s => allSkills.includes(s))
       : allSkills;
-    let agents = isAll ? allAgents
-      : agentsFlag ? agentsFlag.split(',').map(s => s.trim()).filter(s => allAgents.includes(s))
+    const agents = options.all ? allAgents
+      : options.agents ? options.agents.split(',').map(s => s.trim()).filter(s => allAgents.includes(s))
       : allAgents;
 
     log.info(`Target: ${chalk.cyan(target)}`);
@@ -122,105 +163,299 @@ async function interactiveInstall(options) {
     return runInstall({ target, skills, agents });
   }
 
-  // ── Full TUI ───────────────────────────────────────────────────────────────
+  // Full TUI
+  log.info(`Target: ${chalk.cyan(target)}\n`);
+
+  const installed = getInstalled(target);
+
+  const skills = await multiSelect('Select skills to install:', allSkills.map(s => ({
+    title: s,
+    value: s,
+    selected: installed.skills.includes(s) || !existsSync(target),
+  })));
+
+  console.log();
+
+  const agents = await multiSelect('Select agents to install:', allAgents.map(a => ({
+    title: a,
+    value: a,
+    selected: installed.agents.includes(a) || !existsSync(target),
+  })));
+
+  console.log();
+  console.log(chalk.bold('  Summary'));
+  console.log(`    ${chalk.green('Skills')} (${skills.length}): ${skills.join(', ') || chalk.dim('none')}`);
+  console.log(`    ${chalk.cyan('Agents')} (${agents.length}): ${agents.join(', ') || chalk.dim('none')}`);
+  console.log(`    Target: ${target}`);
+  console.log();
+
+  if (!await confirmPrompt('Install?')) { log.warn('Cancelled.'); return; }
+  console.log();
+
+  return runInstall({ target, skills, agents });
+}
+
+// ─── COMMAND: upgrade ─────────────────────────────────────────────────────────
+
+async function cmdUpgrade(options, targetArg) {
+  log.title('GinStudio — Upgrade Skills & Agents');
+
+  const target = resolveTarget(options.target || targetArg, options.global);
+  const installed = getInstalled(target);
+  const total = installed.skills.length + installed.agents.length;
+
+  if (total === 0) {
+    log.warn(`Nothing from GinStudio is installed in ${chalk.cyan(target)}.`);
+    log.dim(`Run ${chalk.white('ginskill-init')} to install first.`);
+    console.log();
+    return;
+  }
+
+  log.info(`Target: ${chalk.cyan(target)}`);
+  log.info(`Current package: ${chalk.cyan(`v${PKG.version}`)}\n`);
+
+  // Non-interactive
+  if (options.all) {
+    return runInstall({ target, skills: installed.skills, agents: installed.agents, verb: 'Upgraded' });
+  }
+
+  const skills = await multiSelect('Select skills to upgrade:', installed.skills.map(s => ({
+    title: s, value: s, selected: true,
+  })));
+
+  console.log();
+
+  const agents = await multiSelect('Select agents to upgrade:', installed.agents.map(a => ({
+    title: a, value: a, selected: true,
+  })));
+
+  console.log();
+
+  if (!await confirmPrompt(`Re-install ${skills.length + agents.length} item(s) from v${PKG.version}?`)) {
+    log.warn('Cancelled.');
+    return;
+  }
+  console.log();
+
+  return runInstall({ target, skills, agents, verb: 'Upgraded' });
+}
+
+// ─── COMMAND: uninstall ───────────────────────────────────────────────────────
+
+async function cmdUninstall(options, targetArg) {
+  log.title('GinStudio — Uninstall Skills & Agents');
+
+  const target = resolveTarget(options.target || targetArg, options.global);
+  const installed = getInstalled(target);
+  const total = installed.skills.length + installed.agents.length;
+
+  if (total === 0) {
+    log.warn(`Nothing from GinStudio is installed in ${chalk.cyan(target)}.`);
+    console.log();
+    return;
+  }
 
   log.info(`Target: ${chalk.cyan(target)}\n`);
 
-  // Cancel gracefully with Ctrl+C
-  prompts.override({});
+  const skills = await multiSelect('Select skills to uninstall:', installed.skills.map(s => ({
+    title: s, value: s, selected: false,
+  })));
 
-  const { skills } = await prompts({
-    type: 'multiselect',
-    name: 'skills',
-    message: 'Select skills to install:',
-    choices: allSkills.map(s => ({ title: s, value: s, selected: true })),
-    hint: 'Space to toggle, A to toggle all, Enter to confirm',
-    instructions: false,
-    min: 0,
-  }, {
-    onCancel: () => { log.warn('Cancelled.'); process.exit(0); }
-  });
+  console.log();
+
+  const agents = await multiSelect('Select agents to uninstall:', installed.agents.map(a => ({
+    title: a, value: a, selected: false,
+  })));
 
   console.log();
 
-  const { agents } = await prompts({
-    type: 'multiselect',
-    name: 'agents',
-    message: 'Select agents to install:',
-    choices: allAgents.map(a => ({ title: a, value: a, selected: true })),
-    hint: 'Space to toggle, A to toggle all, Enter to confirm',
-    instructions: false,
-    min: 0,
-  }, {
-    onCancel: () => { log.warn('Cancelled.'); process.exit(0); }
-  });
+  const count = skills.length + agents.length;
+  if (count === 0) { log.warn('Nothing selected.'); return; }
 
+  console.log(chalk.bold('  Will remove:'));
+  skills.forEach(s => console.log(`    ${chalk.red('✕')} skill  ${s}`));
+  agents.forEach(a => console.log(`    ${chalk.red('✕')} agent  ${a}`));
   console.log();
 
-  // Summary + confirm
-  console.log(chalk.bold('  Summary'));
-  console.log(`    ${chalk.green('Skills')}  (${skills.length}): ${skills.join(', ') || chalk.dim('none')}`);
-  console.log(`    ${chalk.cyan('Agents')}  (${agents.length}): ${agents.join(', ') || chalk.dim('none')}`);
-  console.log(`    ${chalk.bold('Target:')} ${target}`);
+  if (!await confirmPrompt(chalk.red(`Permanently remove ${count} item(s)?`))) {
+    log.warn('Cancelled.');
+    return;
+  }
+
+  const spinner = ora({ text: 'Removing...', color: 'red' }).start();
+
+  for (const skill of skills) {
+    const dir = join(target, 'skills', skill);
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  }
+  for (const agent of agents) {
+    const dir  = join(target, 'agents', agent);
+    const file = join(target, 'agents', `${agent}.md`);
+    if (existsSync(dir))  rmSync(dir,  { recursive: true, force: true });
+    if (existsSync(file)) rmSync(file, { force: true });
+  }
+
+  spinner.succeed(chalk.bold.red(`Removed ${count} item(s)`));
   console.log();
+  log.dim('Restart Claude Code to pick up changes.');
+  console.log();
+}
 
-  const { ok } = await prompts({
-    type: 'confirm',
-    name: 'ok',
-    message: 'Install?',
-    initial: true,
-  }, {
-    onCancel: () => { log.warn('Cancelled.'); process.exit(0); }
-  });
+// ─── COMMAND: status ──────────────────────────────────────────────────────────
 
-  if (!ok) { log.warn('Cancelled.'); return; }
+function cmdStatus(options, targetArg) {
+  log.title('GinStudio — Status');
 
+  const target = resolveTarget(options.target || targetArg, options.global);
+  const { skills: allSkills, agents: allAgents } = getAvailable();
+  const installed = getInstalled(target);
+
+  log.info(`Package:  ${chalk.cyan(`ginskill-init v${PKG.version}`)}`);
+  log.info(`Target:   ${chalk.cyan(target)}`);
+  console.log();
+
+  console.log(chalk.bold('  Skills:'));
+  for (const s of allSkills) {
+    const isInstalled = installed.skills.includes(s);
+    const icon  = isInstalled ? chalk.green('✓') : chalk.dim('○');
+    const label = isInstalled ? chalk.white(s)   : chalk.dim(s);
+    const badge = isInstalled ? chalk.green('installed') : chalk.dim('not installed');
+    console.log(`    ${icon}  ${label.padEnd(28)} ${badge}`);
+  }
+
+  console.log();
+  console.log(chalk.bold('  Agents:'));
+  for (const a of allAgents) {
+    const isInstalled = installed.agents.includes(a);
+    const icon  = isInstalled ? chalk.green('✓') : chalk.dim('○');
+    const label = isInstalled ? chalk.cyan(a)    : chalk.dim(a);
+    const badge = isInstalled ? chalk.green('installed') : chalk.dim('not installed');
+    console.log(`    ${icon}  ${label.padEnd(28)} ${badge}`);
+  }
+
+  console.log();
+  const si = installed.skills.length, ai = installed.agents.length;
+  log.info(`${si} skill(s) · ${ai} agent(s) installed out of ${allSkills.length} skills · ${allAgents.length} agents available`);
   console.log();
-  return runInstall({ target, skills, agents });
 }
 
-// ─── List Command ─────────────────────────────────────────────────────────────
+// ─── COMMAND: versions ────────────────────────────────────────────────────────
+
+async function cmdVersions() {
+  log.title('GinStudio — Available Versions');
+
+  const spinner = ora({ text: 'Fetching from npm registry...', color: 'cyan' }).start();
+
+  try {
+    const res  = await fetch(`https://registry.npmjs.org/${PKG.name}`);
+    if (!res.ok) throw new Error(`Registry returned ${res.status}`);
+    const data = await res.json();
+
+    const versions = Object.keys(data.versions || {}).reverse();
+    const latest   = data['dist-tags']?.latest;
+    const times    = data.time || {};
+
+    spinner.succeed(`Found ${versions.length} version(s)\n`);
+
+    console.log(chalk.bold('  Available versions:\n'));
+    for (const v of versions.slice(0, 20)) {
+      const isLatest = v === latest;
+      const date     = times[v] ? new Date(times[v]).toLocaleDateString() : '';
+      const isCurrent = v === PKG.version;
+      const tag      = isLatest ? chalk.green('[latest]') : '';
+      const cur      = isCurrent ? chalk.blue('[current]') : '';
+      const vStr     = isLatest ? chalk.bold.green(`v${v}`) : chalk.white(`v${v}`);
+      console.log(`    ${vStr}  ${chalk.dim(date)}  ${tag} ${cur}`);
+    }
+    if (versions.length > 20) log.dim(`... and ${versions.length - 20} more`);
+
+    console.log();
+    log.dim(`Run ${chalk.white('npx ginskill-init@latest')} to get the newest version.`);
+    console.log();
+
+  } catch (err) {
+    spinner.fail('Could not fetch versions from npm registry.');
+    log.error(err.message);
+    log.dim(`Current installed version: ${chalk.cyan(`v${PKG.version}`)}`);
+    console.log();
+  }
+}
+
+// ─── COMMAND: list ────────────────────────────────────────────────────────────
+
+function cmdList() {
+  log.title('GinStudio — Available Skills & Agents');
+  const { skills, agents } = getAvailable();
 
-function listCommand() {
-  log.title('GinStudio Skills & Agents');
   console.log(chalk.bold('  Skills:'));
-  getDirs(SRC_SKILLS).forEach(s => console.log(`    ${chalk.green('✦')} ${s}`));
+  skills.forEach(s => console.log(`    ${chalk.green('✦')} ${s}`));
   console.log();
   console.log(chalk.bold('  Agents:'));
-  const agents = [...getDirs(SRC_AGENTS), ...getMdFiles(SRC_AGENTS)]
-    .filter((v, i, a) => a.indexOf(v) === i);
   agents.forEach(a => console.log(`    ${chalk.cyan('✦')} ${a}`));
   console.log();
 }
 
-// ─── CLI Setup ────────────────────────────────────────────────────────────────
+// ─── CLI wiring ───────────────────────────────────────────────────────────────
 
 const program = new Command();
 
 program
   .name('ginskill-init')
-  .description('Install GinStudio skills and agents for Claude Code')
-  .version('1.0.0')
-  .option('-g, --global',           'Install to ~/.claude/ (all projects)')
-  .option('-a, --all',              'Install all without prompts')
-  .option('--skills <list>',        'Install specific skills (comma-separated)')
-  .option('--agents <list>',        'Install specific agents (comma-separated)')
-  .option('-t, --target <path>',    'Custom target project path')
-  .argument('[target]',             'Target project path (positional)')
-  .action(async (targetArg, opts) => {
-    await interactiveInstall({
-      global: opts.global,
-      all: opts.all,
-      skills: opts.skills,
-      agents: opts.agents,
-      target: opts.target || targetArg || null,
-    });
-  });
+  .description('Install GinStudio skills & agents for Claude Code')
+  .version(PKG.version);
+
+// Shared options factory
+function addTargetOptions(cmd) {
+  return cmd
+    .option('-g, --global',        'Target ~/.claude/ (available in all projects)')
+    .option('-t, --target <path>', 'Custom target project path')
+    .argument('[target]',          'Target project path (positional)');
+}
 
-program
-  .command('list')
-  .alias('ls')
-  .description('List available skills and agents')
-  .action(listCommand);
+// Default: install
+addTargetOptions(
+  program
+    .option('-a, --all',           'Install all without prompts')
+    .option('--skills <list>',     'Install specific skills (comma-separated names)')
+    .option('--agents <list>',     'Install specific agents (comma-separated names)')
+)
+.action((targetArg, opts) => cmdInstall(opts, targetArg));
+
+// Merge parent opts (handles case where Commander consumes -t/-g at parent level)
+function mergeOpts(opts) {
+  return { ...program.opts(), ...opts };
+}
+
+// upgrade
+addTargetOptions(
+  program.command('upgrade')
+    .description('Upgrade installed skills & agents to the bundled version')
+    .option('-a, --all', 'Upgrade all without prompts')
+)
+.action((targetArg, opts) => cmdUpgrade(mergeOpts(opts), targetArg));
+
+// uninstall
+addTargetOptions(
+  program.command('uninstall').alias('remove')
+    .description('Remove installed skills & agents')
+)
+.action((targetArg, opts) => cmdUninstall(mergeOpts(opts), targetArg));
+
+// status
+addTargetOptions(
+  program.command('status').alias('info')
+    .description('Show installed vs available skills & agents')
+)
+.action((targetArg, opts) => cmdStatus(mergeOpts(opts), targetArg));
+
+// versions
+program.command('versions').alias('ver')
+  .description('List all published npm versions')
+  .action(() => cmdVersions());
+
+// list
+program.command('list').alias('ls')
+  .description('List all available skills & agents in this package')
+  .action(() => cmdList());
 
 program.parse();

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "ginskill-init",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Install GinStudio skills and agents for Claude Code",
-  "keywords": ["claude-code", "claude", "skills", "agents", "ai"],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skills",
+    "agents",
+    "ai"
+  ],
   "license": "MIT",
   "type": "module",
   "bin": {