@inkobytes/nexus 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.7 - 2026-06-06
+
+- Added `nexus install-skill` to install the bundled Nexus skill into `~/.agents/skills/nexus`.
+- Added `--target` and `--force` options for custom or refreshed skill installs, with a guard against broad overwrite targets.
+- Updated help, zsh completion, README docs, and regression coverage for the new skill installer command.
+
 ## 1.0.6 - 2026-06-03
 
 - Extended Nexus protocol drift checks so `nexus doctor` now covers the bundled `skills/nexus/SKILL.md`.

package/README.md

@@ -71,6 +71,7 @@ Requires Node.js 18 or newer.
 
 - Colorized `nexus help` output for easier scanning in the terminal
 - Built-in `nexus completion zsh` support for shell completions
+- Bundled `nexus install-skill` support for installing the Nexus agent skill into `~/.agents/skills`
 
 See [CHANGELOG.md](./CHANGELOG.md) for the release summary.
 
@@ -240,6 +241,18 @@ source <(nexus completion zsh)
 
 This gives `zsh` tab-completion for commands like `claim`, `release`, `doctor`, `drill`, and common agent handles such as `@codex` and `@claude`.
 
+### `nexus install-skill [--target <path>] [--force]`
+
+Install the bundled Nexus agent skill into the shared agent skill directory.
+
+```bash
+nexus install-skill
+nexus install-skill --force
+nexus install-skill --target ~/.agents/skills/nexus
+```
+
+By default, Nexus copies `skills/nexus` from the published package into `~/.agents/skills/nexus`. Restart or refresh your agent session after installing so its skill registry can discover the new `nexus` skill.
+
 ### `nexus ledger [--json]`
 
 Show completed task entries from `_NEXUS_LEDGER.md`.

package/bin/nexus.js

@@ -20,12 +20,13 @@ const COMMANDS = {
   ledger: () => import('../src/commands/ledger.js'),
   drill: () => import('../src/commands/drill.js'),
   soul: () => import('../src/commands/soul.js'),
+  'install-skill': () => import('../src/commands/install-skill.js'),
   chmod: () => import('../src/commands/chmod.js'),
   db: () => import('../src/commands/db.js'),
   help: () => import('../src/commands/help.js'),
 };
 
-const VERSION = '1.0.1';
+const VERSION = '1.0.7';
 const COLORS = createColors();
 
 const args = argv.slice(2);
@@ -76,6 +77,7 @@ function printHelp() {
     ['db <backup|list|restore|schedule>', 'Database backup and recovery'],
     ['drill <list|show|run|report>', 'Inspect or run protocol drills'],
     ['soul [--file <path>] [--status | --remove]', 'Manage local soul overlay in agent files'],
+    ['install-skill [--target <path>] [--force]', 'Install bundled Nexus skill into ~/.agents/skills'],
     ['help', 'Show this help'],
   ];
 
@@ -89,6 +91,7 @@ function printHelp() {
     'nexus metrics --json',
     'nexus ledger backfill',
     'nexus drill show wrong-repo-push',
+    'nexus install-skill',
     'nexus claim src/lib/components/login/ @claude "Building login UI"',
     'nexus release src/lib/components/login/ "feat: login form component"',
     'nexus standup "2026-06-01 08:38 AM @codex [DONE]: Updated tests"',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkobytes/nexus",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
   "type": "module",
   "bin": {

package/src/commands/completion.js

@@ -54,6 +54,7 @@ commands=(
   'db:Database backup and recovery'
   'drill:Inspect or run protocol drills'
   'soul:Manage local soul overlay in agent files'
+  'install-skill:Install bundled Nexus skill into ~/.agents/skills'
   'help:Show command help'
 )
 
@@ -116,6 +117,9 @@ case $words[2] in
   soul)
     _arguments '--file[Overlay file path]:path:_files' '--status[Show status]' '--remove[Remove overlay]'
     ;;
+  install-skill)
+    _arguments '--target[Install target]:path:_files' '--force[Refresh existing installation]'
+    ;;
   start)
     _arguments '--agent[Agent handle]:agent:(@agy @claude @codex @gemini)'
     ;;

package/src/commands/install-skill.js

@@ -0,0 +1,83 @@
+/**
+ * nexus install-skill - install the bundled Nexus agent skill
+ */
+
+import { cpSync, existsSync, mkdirSync, rmSync } from 'fs';
+import { basename, dirname, parse, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+
+const COMMAND_USAGE = 'Usage: nexus install-skill [--target <path>] [--force]';
+const DEFAULT_TARGET = '~/.agents/skills/nexus';
+
+function parseArgs(args) {
+  let target = DEFAULT_TARGET;
+  let force = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--force') {
+      force = true;
+      continue;
+    }
+
+    if (arg === '--target') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(COMMAND_USAGE);
+      target = value;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(COMMAND_USAGE);
+  }
+
+  return { target, force };
+}
+
+function expandHome(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return resolve(homedir(), path.slice(2));
+  return resolve(path);
+}
+
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function assertSafeSkillTarget(destination) {
+  if (basename(destination) !== 'nexus') {
+    throw new Error('Install target must be the Nexus skill directory, for example ~/.agents/skills/nexus.');
+  }
+
+  if (destination === parse(destination).root || destination === homedir()) {
+    throw new Error('Install target is too broad.');
+  }
+}
+
+export default function installSkill(args) {
+  const { target, force } = parseArgs(args);
+  const source = resolve(packageRoot(), 'skills', 'nexus');
+  const destination = expandHome(target);
+
+  if (!existsSync(source)) {
+    throw new Error(`Bundled Nexus skill not found: ${source}`);
+  }
+
+  assertSafeSkillTarget(destination);
+
+  if (existsSync(destination)) {
+    if (!force) {
+      console.log(`Nexus skill already installed at ${destination}`);
+      console.log('Run `nexus install-skill --force` to refresh it.');
+      return;
+    }
+    rmSync(destination, { recursive: true, force: true });
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { recursive: true });
+
+  console.log(`Installed Nexus skill to ${destination}`);
+  console.log('Restart or refresh your agent session so the skill registry can pick it up.');
+}