@smitdev/ai-skills 0.2.0 → 0.3.1

package/README.md

@@ -14,7 +14,8 @@ No global install needed — run it with `npx`:
 # See what's available
 npx @smitdev/ai-skills list
 
-# Interactive: pick assistant(s) and skill(s)
+# Interactive: pick assistant(s) and skill(s) with the keyboard
+#   ↑/↓ move · space or tab toggle · a select all · enter confirm
 npx @smitdev/ai-skills install
 
 # Non-interactive examples

package/bin/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 
-const readline = require('readline');
 const path = require('path');
 const { listSkills } = require('../lib/skills');
 const { adapters } = require('../lib/adapters');
 const { install } = require('../lib/install');
+const { multiselect, select } = require('../lib/prompt');
 
 const ASSISTANT_IDS = Object.keys(adapters);
 
@@ -31,10 +31,6 @@ function parseArgs(argv) {
   return args;
 }
 
-function ask(rl, question) {
-  return new Promise((resolve) => rl.question(question, (a) => resolve(a.trim())));
-}
-
 function parseList(val, valid) {
   if (val === true || !val) return [];
   const items = String(val)
@@ -55,6 +51,8 @@ Usage:
 Commands:
   list                 List the skills bundled in this package
   install              Install skills for one or more assistants
+                       (run with no flags for an interactive picker:
+                        ↑/↓ move · space/tab toggle · a all · enter confirm)
 
 Options for "install":
   --assistant <ids>    Comma-separated: ${ASSISTANT_IDS.join(', ')} (or "all")
@@ -73,20 +71,6 @@ Examples:
 `);
 }
 
-async function pickFromList(rl, label, options) {
-  console.log(`\n${label}`);
-  options.forEach((o, i) => console.log(`  ${i + 1}. ${o.label}`));
-  console.log(`  (comma-separated numbers, or "a" for all)`);
-  const ans = await ask(rl, '> ');
-  if (ans.toLowerCase() === 'a' || ans === '') return options.map((o) => o.id);
-  const picked = ans
-    .split(',')
-    .map((s) => parseInt(s.trim(), 10))
-    .filter((n) => n >= 1 && n <= options.length)
-    .map((n) => options[n - 1].id);
-  return [...new Set(picked)];
-}
-
 async function runInstall(args) {
   const skills = listSkills();
   if (skills.length === 0) {
@@ -98,31 +82,43 @@ async function runInstall(args) {
     typeof args.flags.dir === 'string' ? args.flags.dir : process.cwd()
   );
   const dryRun = !!args.flags['dry-run'];
-  const scope = args.flags.global ? 'global' : 'project';
+  const scopeFlagged = !!args.flags.global || !!args.flags.project;
+  let scope = args.flags.global ? 'global' : 'project';
 
   let assistants = parseList(args.flags.assistant, ASSISTANT_IDS);
   let skillNames = parseList(args.flags.skill, skills.map((s) => s.name));
 
-  const nonInteractive =
-    args.flags.yes || (assistants.length > 0);
+  const nonInteractive = args.flags.yes || assistants.length > 0;
 
   if (!nonInteractive && process.stdin.isTTY) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     if (assistants.length === 0) {
-      assistants = await pickFromList(
-        rl,
-        'Which assistant(s)?',
-        ASSISTANT_IDS.map((id) => ({ id, label: adapters[id].label }))
-      );
+      assistants = await multiselect({
+        title: 'Which assistant(s)? (Claude Code, Copilot, Cursor, Windsurf)',
+        options: ASSISTANT_IDS.map((id) => ({ id, label: adapters[id].label })),
+        initial: ['claude'],
+      });
     }
     if (skillNames.length === 0) {
-      skillNames = await pickFromList(
-        rl,
-        'Which skill(s)?',
-        skills.map((s) => ({ id: s.name, label: `${s.name} — ${truncate(s.description, 60)}` }))
-      );
+      skillNames = await multiselect({
+        title: 'Which skill(s)?',
+        options: skills.map((s) => ({
+          id: s.name,
+          label: `${s.name} — ${truncate(s.description, 60)}`,
+        })),
+        initial: skills.map((s) => s.name),
+      });
+    }
+    // Only Claude Code supports a global scope; ask when relevant.
+    if (!scopeFlagged && assistants.includes('claude')) {
+      scope = await select({
+        title: 'Install scope for Claude Code?',
+        options: [
+          { id: 'project', label: 'This project  (./.claude/skills)' },
+          { id: 'global', label: 'Global         (~/.claude/skills, available everywhere)' },
+        ],
+        initial: 'project',
+      });
     }
-    rl.close();
   }
 
   if (assistants.length === 0) assistants = ASSISTANT_IDS.slice();

package/lib/prompt.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const readline = require('readline');
+
+// Tiny zero-dependency interactive prompts (checkbox + radio) built on
+// readline keypress events. Falls back to nothing in non-TTY environments —
+// callers should guard with process.stdin.isTTY.
+
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const dim = paint('2');
+const bold = paint('1');
+const cyan = paint('36');
+const green = paint('32');
+
+function setupKeys() {
+  const input = process.stdin;
+  readline.emitKeypressEvents(input);
+  if (input.isTTY) input.setRawMode(true);
+  input.resume();
+  return input;
+}
+
+function teardownKeys(input, onKey) {
+  input.removeListener('keypress', onKey);
+  if (input.isTTY) input.setRawMode(false);
+  input.pause();
+}
+
+function hideCursor() {
+  if (useColor) process.stdout.write('\x1b[?25l');
+}
+function showCursor() {
+  if (useColor) process.stdout.write('\x1b[?25h');
+}
+
+/**
+ * Multi-select checkbox prompt.
+ *   options: [{ id, label }]
+ *   initial: array of pre-selected ids
+ * Resolves to an array of selected ids (in option order). Always returns at
+ * least one (the highlighted item) so callers never get an empty selection.
+ */
+function multiselect({ title, options, initial }) {
+  return new Promise((resolve) => {
+    const selected = new Set(initial || []);
+    let cursor = 0;
+    let rendered = 0;
+    const output = process.stdout;
+
+    const hint = dim(
+      '↑/↓ move · space/tab toggle · a all · enter confirm'
+    );
+
+    function render(first) {
+      if (!first) output.write(`\x1b[${rendered}A`);
+      const lines = [bold(title), hint];
+      options.forEach((o, i) => {
+        const active = i === cursor;
+        const pointer = active ? cyan('›') : ' ';
+        const box = selected.has(o.id) ? green('◉') : dim('◯');
+        const label = active ? cyan(o.label) : o.label;
+        lines.push(`${pointer} ${box} ${label}`);
+      });
+      output.write(lines.map((l) => '\x1b[2K' + l).join('\n') + '\n');
+      rendered = lines.length;
+    }
+
+    const input = setupKeys();
+    hideCursor();
+
+    function finish() {
+      if (selected.size === 0) selected.add(options[cursor].id);
+      teardownKeys(input, onKey);
+      showCursor();
+      resolve(options.filter((o) => selected.has(o.id)).map((o) => o.id));
+    }
+
+    function onKey(_str, key) {
+      if (!key) return;
+      if (key.ctrl && key.name === 'c') {
+        teardownKeys(input, onKey);
+        showCursor();
+        output.write('\n');
+        process.exit(130);
+      }
+      switch (key.name) {
+        case 'up':
+        case 'k':
+          cursor = (cursor - 1 + options.length) % options.length;
+          break;
+        case 'down':
+        case 'j':
+          cursor = (cursor + 1) % options.length;
+          break;
+        case 'space':
+        case 'tab':
+          if (selected.has(options[cursor].id)) selected.delete(options[cursor].id);
+          else selected.add(options[cursor].id);
+          break;
+        case 'a': {
+          if (selected.size === options.length) selected.clear();
+          else options.forEach((o) => selected.add(o.id));
+          break;
+        }
+        case 'return':
+        case 'enter':
+          finish();
+          return;
+        default:
+          return;
+      }
+      render(false);
+    }
+
+    input.on('keypress', onKey);
+    render(true);
+  });
+}
+
+/**
+ * Single-select radio prompt.
+ *   options: [{ id, label }]
+ * Resolves to one id.
+ */
+function select({ title, options, initial }) {
+  return new Promise((resolve) => {
+    let cursor = Math.max(0, options.findIndex((o) => o.id === initial));
+    if (cursor < 0) cursor = 0;
+    let rendered = 0;
+    const output = process.stdout;
+    const hint = dim('↑/↓ move · enter select');
+
+    function render(first) {
+      if (!first) output.write(`\x1b[${rendered}A`);
+      const lines = [bold(title), hint];
+      options.forEach((o, i) => {
+        const active = i === cursor;
+        const pointer = active ? cyan('›') : ' ';
+        const dot = active ? green('◉') : dim('◯');
+        const label = active ? cyan(o.label) : o.label;
+        lines.push(`${pointer} ${dot} ${label}`);
+      });
+      output.write(lines.map((l) => '\x1b[2K' + l).join('\n') + '\n');
+      rendered = lines.length;
+    }
+
+    const input = setupKeys();
+    hideCursor();
+
+    function onKey(_str, key) {
+      if (!key) return;
+      if (key.ctrl && key.name === 'c') {
+        teardownKeys(input, onKey);
+        showCursor();
+        output.write('\n');
+        process.exit(130);
+      }
+      switch (key.name) {
+        case 'up':
+        case 'k':
+          cursor = (cursor - 1 + options.length) % options.length;
+          break;
+        case 'down':
+        case 'j':
+          cursor = (cursor + 1) % options.length;
+          break;
+        case 'return':
+        case 'enter':
+          teardownKeys(input, onKey);
+          showCursor();
+          resolve(options[cursor].id);
+          return;
+        default:
+          return;
+      }
+      render(false);
+    }
+
+    input.on('keypress', onKey);
+    render(true);
+  });
+}
+
+module.exports = { multiselect, select };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smitdev/ai-skills",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Install reusable AI assistant skills (Claude Code, GitHub Copilot, Cursor, Windsurf) with one command.",
   "bin": {
     "ai-skills": "bin/cli.js"

package/skills/understand/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: understand
-description: Read a whole codebase and write a set of plain-language docs that explain it - one overview/map doc plus one doc per aspect (UI, styles, API, models, data, testing, features, services, and so on). Use this when someone wants to understand a project as a whole or get onboarded to a repo - things like "help me understand this codebase", "document this repo", "explain how this project is structured", "map out the code", "onboard me to this project", or "I just joined and need to learn this code". This is for the WHOLE codebase. To explain one single feature in depth, use the feature-explainer skill instead.
+description: Read a whole codebase and write a set of plain-language docs that explain it - one overview/map doc plus one doc per aspect (UI, styles, API, models, data, testing, features, services, and so on). Use this when someone wants to understand a project as a whole or get onboarded to a repo - things like "help me understand this codebase", "document this repo", "explain how this project is structured", "map out the code", "onboard me to this project", or "I just joined and need to learn this code". This is for the WHOLE codebase. It can also explain one single feature in depth on request - things like "explain how login works", "walk me through the checkout flow", "how does feature X work" - but only after confirming with the user first (see "Explaining a single feature on request").
 ---
 
 # Understanding
@@ -124,6 +124,51 @@ Put all the docs in one folder so they're a set. Reuse the project's docs folder
 
 Name the files simply: the map is `overview.md`, and each aspect is its lowercase name (`api.md`, `ui.md`, `data.md`, ...). Tell the user the folder path and the list of files when you're done.
 
+## Explaining a single feature on request
+
+Sometimes the user doesn't want the whole codebase mapped - they want one feature explained in depth (e.g. "explain how login works", "walk me through the checkout flow", "how does search work"). This skill can do that too, but it's a different job from the full map, so **always confirm before starting**.
+
+When a request looks like a single-feature explanation:
+
+1. **Confirm first.** Don't dive in. Ask the user something like: "Do you want me to explain just the `<feature>` feature in depth, or map the whole codebase? And should I write it to a doc file or just explain it here in the chat?" Wait for their answer before doing the work. Only proceed once they've confirmed the scope (one feature vs. whole repo) and the output (a file vs. inline).
+
+2. **Trace the feature, not the repo.** Once confirmed, follow the one feature end to end instead of surveying everything. Find its entry point (the button, route, command, or event that kicks it off) and follow it through the layers - UI -> API -> services -> data and back. Read only the files on that path.
+
+3. **Write the explanation** using this shape:
+
+```markdown
+# Feature: <feature name>
+
+## What it does
+
+One short paragraph in plain words - what this feature is, from the user's point of view.
+
+## How it's triggered
+
+Where it starts - the button, route, command, or event that kicks it off, with the real file path.
+
+## How it flows end to end
+
+Follow the feature step by step through the layers (UI -> API -> service -> data
+-> back). This is the core of the doc. A numbered list or a small diagram works well.
+Point to the real file (and function) at each step.
+
+## The main pieces
+
+The key files/functions involved and what each one contributes. Just the ones on this
+feature's path, not the whole repo.
+
+## Edge cases and gotchas
+
+Error handling, validation, special states, and the non-obvious bits someone would miss.
+
+## Where to start reading
+
+The first file or two to open to follow this feature.
+```
+
+4. **Output where they asked.** If they wanted a file, save it in the same docs folder the full maps use (see "Where to save the docs") as `feature-<name>.md`. If they wanted it inline, just explain it in the chat. Either way, follow the same rules below - real file paths, no invention.
+
 ## Rules to keep in mind
 
 - Write for a newcomer. Plain words, real examples, no walls of jargon.