claude-agent-skills 1.5.2 → 1.5.4

package/README.md

@@ -1,8 +1,8 @@
 # claude-agent-skills
 
-Install and manage Pavi's Claude Code agent skills via an interactive CLI.
+Interactive CLI to install and manage Claude Code agent skills — the prompt files that teach Claude how to perform specialised tasks in your projects.
 
-## Usage
+## Quick start
 
 ```bash
 npx claude-agent-skills
@@ -17,48 +17,109 @@ claude-agent-skills
 
 ## What it does
 
-Launches an animated interactive menu to install, update, remove, and inspect Claude Code skills — the prompt files that teach Claude how to perform specialised tasks in your projects.
+Launches a full-screen interactive TUI (alternate screen buffer — your terminal is restored on exit) with an animated banner, grid-based skill picker, and in-place navigation. Works like `vim` or `less` — nothing leaks into your scrollback.
 
 Skills are installed into:
 
-| Scope   | Path                               |
-|---------|------------------------------------|
+| Scope   | Paths |
+|---------|-------|
 | Global  | `~/.claude/skills/` + `~/.agents/skills/` |
-| Project | `.claude/skills/` in current dir   |
+| Project | `.claude/skills/` in the current directory |
 
-A lockfile (`~/.claude/claude-agent-skills-lock.json` or `.claude/claude-agent-skills-lock.json`) tracks every installed skill with a SHA-256 hash so updates and drift can be detected.
+A lockfile (`claude-skills-lock.json`) tracks every installed skill with a SHA-256 hash so updates, drift, and broken symlinks can be detected.
+
+## Navigation
+
+Every screen shows a `►► key action` hint bar at the bottom.
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` | Move up / down in menus |
+| `←` `→` | Move left / right in skill grid |
+| `space` | Toggle skill selection |
+| `a` | Select / deselect all skills |
+| `enter` | Confirm |
+| `esc` | Go back to previous menu |
+| `ctrl+c` | Quit |
+
+After any command finishes, a **5-second countdown** is shown (`◂ returning to menu in 5s · press any key`) so you can read the output before the screen resets. Press any key to skip the wait.
 
 ## Menu options
 
-| Option | Description |
-|--------|-------------|
-| **Add Skill(s)** | Pick from 54 bundled skills. Dependencies are resolved and installed automatically. |
-| **Update Existing Skill(s)** | Detect and apply updates for skills that have a newer bundled version. |
-| **Remove Existing Skill(s)** | Uninstall skills from disk and remove them from the lockfile. |
-| **List Installed Skill(s)** | Show all installed skills with status, link type, and hash. |
-| **Sync/Restore Skills from Lockfile** | Re-materialize any missing or broken skills from the lockfile. |
-| **Check Skill(s)** | Health check — ok / update available / locally modified / missing / broken symlink. |
-| **Quit** | Exit. |
+| Option | What it does |
+|--------|--------------|
+| **Add Skill(s)** | Grid picker of all 54 bundled skills. Select scope → pick skills → pick link type → confirm. Dependencies resolved automatically. |
+| **Update Existing Skill(s)** | Finds skills where the bundled version has a newer hash and re-installs them. |
+| **Remove Existing Skill(s)** | Uninstalls selected skills from disk and removes them from the lockfile. |
+| **List Installed Skill(s)** | Table of all installed skills with their status, link type, and hash. |
+| **Sync/Restore from Lockfile** | Re-materializes any missing or broken skills using the lockfile. Run this after cloning a new machine or if symlinks break. |
+| **Check Skill(s)** | Health check — reports each skill as `ok`, `update available`, `locally modified`, `missing`, or `broken symlink`. |
+| **Quit** | Restore the terminal and exit. |
+
+## CLI subcommands
+
+All menu actions are also available as direct subcommands (no TUI):
+
+```bash
+claude-agent-skills add --global --all              # install all skills globally
+claude-agent-skills add --skill grilling tdd        # install specific skills
+claude-agent-skills add --project --copy            # copy into project scope
+claude-agent-skills update --global                 # update all globally
+claude-agent-skills remove --project                # interactive remove, project scope
+claude-agent-skills list --global                   # show installed skills
+claude-agent-skills sync --global                   # restore from lockfile
+claude-agent-skills check --project                 # health check, project scope
+claude-agent-skills export --out skills.lock.json   # export lockfile for team sharing
+claude-agent-skills import --in skills.lock.json    # import and apply a shared lockfile
+```
+
+### Flags
 
-Press **Escape** at any sub-prompt to go back to the main menu.
+| Flag | Description |
+|------|-------------|
+| `--global` | Target `~/.claude/skills/` (default) |
+| `--project` | Target `.claude/skills/` in cwd |
+| `--all` | Select all available skills |
+| `--skill <name...>` | Specify skill names directly |
+| `--copy` | Materialize as file copies (safe for npx) |
+| `--symlink` | Materialize as symlinks (requires persistent install) |
+| `--yes` | Skip confirmation prompts |
+| `--out <path>` | Export lockfile destination |
+| `--in <path>` | Import lockfile source |
 
-## CLI commands
+## Lockfile
 
-All menu options are also available as direct subcommands:
+The lockfile (`claude-skills-lock.json`) records each installed skill's SHA-256 hash and link type. Commit it to your repo to let teammates restore the exact same skill set with:
 
 ```bash
-claude-agent-skills add --global --all          # install everything globally
-claude-agent-skills add --skill grilling tdd    # install specific skills
-claude-agent-skills update --global             # update all with new versions
-claude-agent-skills remove --project            # interactive remove (project scope)
-claude-agent-skills list --global               # show installed skills
-claude-agent-skills sync --global               # restore from lockfile
-claude-agent-skills check --project             # health check
+claude-agent-skills import --in claude-skills-lock.json --global
+```
+
+Export your current setup:
+
+```bash
+claude-agent-skills export --out claude-skills-lock.json
 ```
 
 ## Included skills
 
-54 skills spanning engineering, productivity, and personal workflows — including the full [mattpocock/skills](https://github.com/mattpocock/skills) set, [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) skills, [obra/superpowers](https://github.com/obra/superpowers) skills, and Pavi's personal additions (ponytail suite, council, etc.).
+54 skills across four upstream sources:
+
+| Source | Skills |
+|--------|--------|
+| [mattpocock/skills](https://github.com/mattpocock/skills) | `brainstorming`, `codebase-design`, `diagnosing-bugs`, `dispatching-parallel-agents`, `domain-modeling`, `executing-plans`, `finishing-a-development-branch`, `implement`, `improve-codebase-architecture`, `prototype`, `receiving-code-review`, `requesting-code-review`, `subagent-driven-development`, `systematic-debugging`, `tdd`, `teach`, `test-driven-development`, `to-issues`, `to-prd`, `triage`, `using-git-worktrees`, `using-superpowers`, `verification-before-completion`, `writing-plans`, `writing-skills` |
+| [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) | `caveman`, `cavecrew`, `caveman-commit`, `caveman-compress`, `caveman-help`, `caveman-review`, `caveman-stats` |
+| [obra/superpowers](https://github.com/obra/superpowers) | `git-guardrails-claude-code`, `migrate-to-shoehorn`, `resolving-merge-conflicts`, `scaffold-exercises`, `setup-matt-pocock-skills`, `setup-pre-commit` |
+| Personal (Pavi) | `ask-matt`, `council`, `edit-article`, `grill-me`, `grill-with-docs`, `grilling`, `handoff`, `i-am-dumb`, `obsidian-vault`, `ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`, `writing-great-skills` |
+
+## How bundling works
+
+Skills live in a private monorepo (`Pavithran-Francis/skills`). At publish time, `scripts/bundle.js` copies all skill folders into `bundled-skills/` and generates `skills.json` (manifest with skill list, dependency graph, and descriptions). This means `npx` users get all skills without needing access to the private repo.
+
+## Requirements
+
+- Node.js 18+
+- Claude Code (to use the installed skills)
 
 ## Author
 

package/commands/hub.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { showIntro, showIntroStatic } from '../lib/banner.js';
 import { CliCancel } from '../lib/prompts.js';
+import { brand, muted } from '../lib/theme.js';
 import { inlineSelect } from '../lib/inlineSelect.js';
 
 const req = createRequire(import.meta.url);
@@ -33,6 +34,45 @@ function restoreScreen() {
   process.stdout.write('\x1b[?1049l');
 }
 
+/** Show a live countdown then return — lets the user read command output before menu clears. */
+async function pauseBeforeReturn(seconds = 5) {
+  let remaining = seconds;
+  const render = () => process.stdout.write(
+    `\r\x1b[2K  ${brand('◂')} ${muted(`returning to menu in ${remaining}s  ·  press any key`)}`
+  );
+
+  process.stdout.write('\n');
+  render();
+
+  return new Promise(resolve => {
+    let done = false;
+    function cleanup() {
+      if (done) return;
+      done = true;
+      clearInterval(tick);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeAllListeners('data');
+      process.stdout.write('\n');
+    }
+
+    const tick = setInterval(() => {
+      remaining--;
+      if (remaining <= 0) { cleanup(); resolve(); }
+      else render();
+    }, 1000);
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', key => {
+      if (key === '\x03') { cleanup(); process.exit(0); }
+      cleanup();
+      resolve();
+    });
+  });
+}
+
 export async function runHub() {
   // Alternate screen buffer — isolated viewport, no scrollback. Restored on exit like vim/less.
   process.stdout.write('\x1b[?1049h\x1b[2J\x1b[H');
@@ -43,9 +83,8 @@ export async function runHub() {
   let first = true;
   for (;;) {
     if (!first) {
-      // Clear alt screen and re-render the static banner so it's always visible
       process.stdout.write('\x1b[2J\x1b[H');
-      await showIntroStatic();
+      await showIntroStatic(); // static banner — always visible on return to menu
     }
     first = false;
 
@@ -64,9 +103,12 @@ export async function runHub() {
       if (choice === 'list')   await runList(SKIP);
       if (choice === 'sync')   await runSync(SKIP);
       if (choice === 'check')  await runCheck(SKIP);
+
+      // Pause so user can read command output before the screen clears
+      await pauseBeforeReturn();
     } catch (e) {
-      if (e instanceof CliCancel) continue; // sub-command ESC → back to menu
-      if (e?.isCancel) { restoreScreen(); return; } // hub menu ESC → quit
+      if (e instanceof CliCancel) continue; // ESC from sub-step → back to menu immediately
+      if (e?.isCancel) { restoreScreen(); return; }
       restoreScreen();
       throw e;
     }

package/lib/inlineSelect.js

@@ -13,24 +13,38 @@ const KEY = {
   ESC:    '\x1b',
 };
 
+function formatHints(str) {
+  return '  ' + brand('►► ') + str.split(' · ').map(part => {
+    const [key, ...rest] = part.trim().split(' ');
+    return ansis.bold(ansis.white(key)) + (rest.length ? muted(' ' + rest.join(' ')) : '');
+  }).join(muted('  ·  '));
+}
+
 export async function inlineSelect({ message, hint = '↑↓ navigate · enter select · esc back', options }) {
   let cursor = 0;
   let lastLines = 0;
 
+  // Pre-compute max label width so all descriptions align to the same column
+  const maxLen = Math.max(...options.map(o => o.label.length));
+
   function renderLines() {
     const out = [];
-    out.push(brand('◆') + '  ' + ansis.bold(white(message)) + '  ' + muted(hint));
+    // Title line — no hints here (moved to footer bar)
+    out.push(brand('◆') + '  ' + ansis.bold(white(message)));
     out.push(muted('│'));
     for (let i = 0; i < options.length; i++) {
-      const focused = i === cursor;
-      const arrow   = focused ? ansis.bold(ansis.white('▶')) : ' ';
-      const label   = focused
-        ? ansis.bold(ansis.white(options[i].label))
-        : muted(options[i].label);
-      const desc    = options[i].hint ? '  ' + muted(options[i].hint) : '';
+      const focused  = i === cursor;
+      const arrow    = focused ? ansis.bold(ansis.white('▶')) : ' ';
+      const pad      = ' '.repeat(maxLen - options[i].label.length);
+      const label    = focused
+        ? ansis.bold(ansis.white(options[i].label)) + pad
+        : muted(options[i].label) + pad;
+      const desc     = options[i].hint ? '  ' + muted(options[i].hint) : '';
       out.push(muted('│') + '  ' + arrow + ' ' + label + desc);
     }
     out.push(muted('│'));
+    // Dedicated hint footer bar
+    out.push(formatHints(hint));
     return out;
   }
 

package/lib/picker.js

@@ -3,7 +3,14 @@
  * Navigation: ↑↓←→  space=toggle  a=all  enter=confirm  esc=back
  */
 import ansis from 'ansis';
-import { skillColor, white, muted, success, brand, warn } from './theme.js';
+import { skillColor, white, muted, success, brand } from './theme.js';
+
+function formatHints(str) {
+  return '  ' + brand('►► ') + str.split(' · ').map(part => {
+    const [key, ...rest] = part.trim().split(' ');
+    return ansis.bold(ansis.white(key)) + (rest.length ? muted(' ' + rest.join(' ')) : '');
+  }).join(muted('  ·  '));
+}
 
 const KEY = {
   UP:     '\x1b[A',
@@ -52,12 +59,13 @@ export async function skillPicker({ message, options }) {
     return Math.max(0, Math.min(options.length - 1, c));
   }
 
+  const HINT = '↑↓←→ navigate · space toggle · a=all · enter confirm · esc back';
+
   function renderGrid() {
     const lines = [];
 
-    // Header
-    lines.push(brand('◆') + '  ' + ansis.bold(white(message)) +
-      muted('  ↑↓←→ navigate · space toggle · a=all · enter confirm · esc back'));
+    // Header — title only, hints moved to footer bar
+    lines.push(brand('◆') + '  ' + ansis.bold(white(message)));
     lines.push(muted('│'));
 
     // Grid rows
@@ -94,12 +102,13 @@ export async function skillPicker({ message, options }) {
       lines.push(muted('│ ') + white(line));
     }
 
-    // Footer
+    // Footer — count + hint bar
     const selCount = sel.size;
     lines.push(
       '  ' + (selCount > 0 ? success(`${selCount} selected`) : muted('0 selected')) +
       muted(`  ·  ${cursor + 1} of ${options.length}`)
     );
+    lines.push(formatHints(HINT));
 
     return lines;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-agent-skills",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Install and manage Pavi's Claude Code agent skills",
   "license": "MIT",
   "type": "module",

package/skills.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "name": "claude-agent-skills",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "skills": [
     "ask-matt",
     "brainstorming",