skills-atlas-cli 0.12.0 → 0.14.1

package/bin/skills.js

@@ -18,6 +18,7 @@ const gaps = require('../src/commands/gaps');
 const gapAnalyze = require('../src/commands/gap-analyze');
 const craft = require('../src/commands/craft');
 const prune = require('../src/commands/prune');
+const setup = require('../src/commands/setup');
 const feedback = require('../src/commands/feedback');
 const update = require('../src/commands/update');
 const mcp = require('../src/commands/mcp');
@@ -26,7 +27,7 @@ const { categories, list } = require('../src/commands/categories');
 const VERSION = require('../package.json').version;
 // `use` = install + activate inline (emit the SKILL.md so an agent follows it now).
 const use = argv => install([...argv, '--inline']);
-const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, 'gap-analyze': gapAnalyze, craft, prune, feedback, update, categories, list, registry, mcp };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, 'gap-analyze': gapAnalyze, craft, prune, feedback, setup, update, categories, list, registry, mcp };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -47,6 +48,9 @@ manage what you've installed:
   kit                set up the right skills for THIS project (detect + install)
   sync               reproduce a project's kit from skills-atlas.kit.json
 
+getting started:
+  setup              what you've got + how to use it (run after installing the plugin)
+
 autopilot (opt-in):
   hook on|off|status proactively suggest a skill in Claude when your prompt fits one
   gaps               kinds of work you keep doing without a skill (run: skills-atlas hook on)
@@ -80,7 +84,7 @@ async function main() {
   }
   // Opportunistic, non-blocking background catalog refresh so new skills appear over
   // time without a manual `update`. Skipped for `update` itself; fully fail-silent.
-  if (sub !== 'update' && sub !== 'gap-analyze' && !process.env.SKILLS_ATLAS_SUBCALL) {
+  if (sub !== 'update' && sub !== 'gap-analyze' && sub !== 'setup' && !process.env.SKILLS_ATLAS_SUBCALL) {
     try { require('../src/data').maybeBackgroundRefresh(); } catch { /* ignore */ }
   }
   await cmd(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.12.0",
+  "version": "0.14.1",
   "description": "Search, install and learn AI agent skills from the terminal — powered by the Skills Atlas catalog.",
   "bin": {
     "skills-atlas": "bin/skills.js",

package/src/args.js

@@ -24,6 +24,8 @@ const ALL = {
   verbose: { type: 'boolean' },
   show: { type: 'boolean' },
   once: { type: 'boolean' },
+  'session-start': { type: 'boolean' },
+  reset: { type: 'boolean' },
   archetype: { type: 'string' },
   update: { type: 'boolean' },
   name: { type: 'string' },

package/src/commands/setup.js

@@ -0,0 +1,98 @@
+// `skills-atlas setup` — post-install onboarding + status. Run manually anytime
+// (`skills-atlas setup`), or automatically once at session start via the plugin's
+// SessionStart hook (`setup --session-start`). The one-time welcome is gated by a
+// marker so it shows once, then stays silent. The session-start welcome is delivered
+// via `systemMessage`, which the user sees VERBATIM (the model never sees it / can't
+// paraphrase it). All local; nothing is sent.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parse } = require('../args');
+const registry = require('../registry');
+const { green, dim, bold } = require('../format');
+
+function cacheFile(name) {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'skills-atlas', name);
+}
+const exists = f => { try { return fs.existsSync(f); } catch { return false; } };
+function touch(f) {
+  try { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, new Date().toISOString() + '\n'); } catch { /* best-effort */ }
+}
+const onboardedFile = () => cacheFile('onboarded');
+// Set by the plugin's welcome.js when the "engine not installed" notice was shown — so
+// the eventual real welcome says "Nicely done" instead of the fresh-install greeting.
+const installPromptShown = () => exists(cacheFile('install-prompt-shown'));
+
+// The two settings worth surfacing up front (the rest live in the full `setup` view).
+function welcomeSettings(ap) {
+  return 'Settings:\n' +
+    `  language   /skills-atlas:skill-autopilot lang en|zh   (now: ${ap.replyLang})\n` +
+    `  autopilot  /skills-atlas:skill-autopilot on|off        (${ap.enabled !== false ? 'on' : 'off'})\n\n` +
+    'More: /skills-atlas:setup';
+}
+
+// The one-time welcome text, or null if the user was already onboarded. Gated by the global
+// `onboarded` marker so it shows exactly once; with { consume: true } it claims that one
+// shot (marks onboarded). Shared by the SessionStart hook (`setup --session-start`) and the
+// UserPromptSubmit fallback in `suggest` — which catches the case where the plugin was
+// installed mid-session and no fresh session-start has fired the welcome yet.
+function buildWelcome(ap, { consume = false } = {}) {
+  if (exists(onboardedFile())) return null;
+  if (consume) touch(onboardedFile());
+  const intro = installPromptShown()
+    ? '🎉 Nicely done — Skills Atlas is configured and on. It\'ll quietly flag a ready-made skill when one fits, and offer to turn repeated workflows into skills of your own.'
+    : '✨ Skills Atlas is on. While you work, it keeps an eye out and quietly flags a ready-made skill the moment one fits — and if you catch yourself doing the same dance over and over, it\'ll offer to turn it into a skill of your own.';
+  return intro + '\n\n' + welcomeSettings(ap);
+}
+
+module.exports = async function setup(argv) {
+  const { values } = parse(argv, ['session-start', 'json', 'reset']);
+  if (values.help) {
+    console.log('usage: skills-atlas setup [--reset]\n\n' +
+      'Show what Skills Atlas gives you and the autopilot status. Run it after installing\n' +
+      'the plugin. --reset makes the one-time welcome show again next session.');
+    return;
+  }
+  if (values.reset) {
+    try { fs.rmSync(onboardedFile(), { force: true }); fs.rmSync(cacheFile('install-prompt-shown'), { force: true }); } catch { /* ignore */ }
+    console.log(`${green('✓')} onboarding reset — the welcome will show once more next session.`);
+    return;
+  }
+
+  const ap = registry.getAutopilot();
+
+  // --- Auto path (SessionStart hook): emit a ONE-TIME welcome via systemMessage (shown
+  // to the user verbatim), then stay silent forever. "Nicely done" variant if the user
+  // came here after the engine-not-installed notice; otherwise the fresh-install greeting. ---
+  if (values['session-start']) {
+    const msg = buildWelcome(ap, { consume: true });
+    if (msg === null) return; // already welcomed → silent
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart' }, systemMessage: msg, suppressOutput: true }));
+    return;
+  }
+
+  // --- Manual path: human-readable status + what-you-can-do + full settings. ---
+  touch(onboardedFile()); // running setup yourself counts as onboarded
+  if (values.json) {
+    console.log(JSON.stringify({ installed: true, autopilot: ap.enabled !== false, suggest: ap.suggest, gapAlerts: ap.gapAlerts, prune: ap.prune, replyLang: ap.replyLang }));
+    return;
+  }
+  console.log(`${green('✓')} Skills Atlas is installed and ready.`);
+  console.log(`  autopilot: ${ap.enabled !== false ? green('on') : dim('off')}   ${dim('toggle: /skills-atlas:skill-autopilot on|off')}`);
+  console.log(`\n${bold('What you can do')} — right here in the conversation:`);
+  console.log(`  ${green('find & install')}    /skills-atlas:skill-search <query>  →  :skill-install <skill>`);
+  console.log(`  ${green('set up a project')}  /skills-atlas:skill-kit   (detects the project type, proposes a kit)`);
+  console.log(`  ${green('codify a workflow')} /skills-atlas:skill-craft   (turns something you keep doing into a skill)`);
+  console.log(`  ${green('review')}            /skills-atlas:skill-gaps  ·  :skill-prune  ·  :skill-installed`);
+  console.log(`\n${bold('Settings')} ${dim('(optional)')}`);
+  console.log(`  language    /skills-atlas:skill-autopilot lang en|zh     ${dim('(now: ' + ap.replyLang + ')')}`);
+  console.log(`  autopilot   /skills-atlas:skill-autopilot on|off          ${dim('(' + (ap.enabled !== false ? 'on' : 'off') + ')')}`);
+  console.log(`  fine-tune   /skills-atlas:skill-autopilot suggest|gaps|prune on|off  ${dim('· model')}`);
+  console.log(dim('\nThe autopilot also suggests skills proactively as you work — each judged for fit. Nothing leaves your machine.'));
+};
+
+// Reused by `suggest`'s first-run fallback (see src/commands/suggest.js).
+module.exports.buildWelcome = buildWelcome;

package/src/commands/suggest.js

@@ -56,7 +56,24 @@ module.exports = async function suggest() {
     let event = {};
     try { event = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { /* not JSON → bail */ }
     const prompt = event.prompt || '';
-    if (!prompt || prompt.length < 8) return;
+    if (!prompt) return;
+
+    // First-run welcome fallback: if the plugin was installed mid-session (so no fresh
+    // SessionStart has fired the welcome yet), surface the one-time welcome on the user's
+    // next prompt — verbatim, via systemMessage. This MUST run ahead of the suggestion's
+    // min-length gate below: onboarding shouldn't depend on how long the prompt is (a short
+    // "hi" should still get the welcome). Shares the global `onboarded` marker with the
+    // SessionStart hook, so the welcome shows exactly once across both paths.
+    try {
+      const welcome = require('./setup').buildWelcome(registry.getAutopilot(), { consume: true });
+      if (welcome) {
+        console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit' }, systemMessage: welcome, suppressOutput: true }));
+        return;
+      }
+    } catch { /* fail-open */ }
+
+    // The proactive suggestion (below) needs a meatier prompt to match against.
+    if (prompt.length < 8) return;
 
     const file = stateFile(event.session_id || event.sessionId);
     const state = readState(file);
@@ -150,17 +167,17 @@ module.exports = async function suggest() {
       return `- ${c.skill}${uc ? ` — ${uc}` : ''}  (details: \`skills-atlas info ${c.skill}\` · use now: \`skills-atlas use ${c.skill} --yes --project\`)`;
     }).join('\n');
     emit(
-      `[Skills Atlas autopilot] The user may be doing something one of these installable agent ` +
-      `skills is built for. Judge for yourself — do NOT mention any of this unless one of them ` +
-      `genuinely fits what they actually asked:\n${lines}\n` +
-      `If one genuinely fits, DON'T just name it: in one line tell the user what it does and why it ` +
-      `fits THIS task (it's a curated skill from the Skills Atlas catalog, not something you made up), ` +
-      `then let them choose — activate it now (\`skills-atlas use <skill> --yes --project\` installs + applies it ` +
-      `immediately), see what it covers first (\`skills-atlas info <skill>\`), or skip and you'll just ` +
-      `do the task yourself; if they ask to never suggest it again, run \`skills-atlas feedback dismiss <skill>\`. ` +
-      `If none fit but the task plainly needs a specialized skill, you may run ` +
-      `\`skills-atlas search "<short intent>"\` to look further. If nothing fits, say nothing about this ` +
-      `at all — don't mention this hook, these skills, or that a suggestion was made.` + langHint(ap.replyLang));
+      `[Skills Atlas autopilot] One of these catalog skills MIGHT fit what the user is doing. Judge for ` +
+      `yourself — most prompts match nothing, and staying silent is usually the right call:\n${lines}\n` +
+      `Mention one ONLY if it genuinely fits what they actually asked. If it does: in a sentence or two, ` +
+      `casually tell them what that skill ACTUALLY DOES and why it fits THIS task — enough that they ` +
+      `understand it (use the skill's EXACT name as listed above; it's a real curated skill from the Skills ` +
+      `Atlas catalog, not something you made up). Then offer the choice naturally, in prose — NOT a bulleted ` +
+      `sales menu: they can switch it on now (\`skills-atlas use <skill> --yes --project\`), or you can show ` +
+      `what it covers first (\`skills-atlas info <skill>\`) if they're unsure. Don't push. If nothing genuinely ` +
+      `fits, say NOTHING about any of this — don't mention this hook, the skills, or that a check ran. (To ` +
+      `look wider you may run \`skills-atlas search "<short intent>"\`; if they want a skill never suggested ` +
+      `again, \`skills-atlas feedback dismiss <skill>\`.)` + langHint(ap.replyLang));
     state.lastSuggestedCount = state.count;
     state.suggested = [...suggested, ...candidates.map(c => c.skill)];
     writeState(file, state);