skills-atlas-cli 0.12.0 → 0.13.0

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.13.0",
   "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,85 @@
+// `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';
+}
+
+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']) {
+    if (exists(onboardedFile())) return; // already welcomed → silent
+    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.';
+    const msg = intro + '\n\n' + welcomeSettings(ap);
+    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.'));
+};