skillfish 1.0.17 → 1.0.18

package/README.md

@@ -169,10 +169,52 @@ skillfish update --yes               # Update all without prompting
 skillfish update --json              # Check for updates (JSON output)
 ```
 
-<details>
-<summary>Exit Codes</summary>
+---
+
+## Non-Interactive Mode
+
+All commands work without prompts for use in scripts, CI pipelines, and automation. Non-interactive mode activates when:
+
+- The `--json` flag is passed, or
+- stdin is not a TTY (piped input, CI runners, cron jobs)
+
+In non-interactive mode, commands use default values where possible and error with guidance when required flags are missing.
+
+### Required flags
+
+| Command | Required | Defaults |
+|---------|----------|----------|
+| `add` | `<owner/repo>` + skill name, `--path`, or `--all` if repo has multiple skills | Location: global (`~/`), Agents: all detected |
+| `init` | `--name`, `--description` | Location: project (`./`), Agents: all detected |
+| `list` | (none) | Both locations, all agents |
+| `remove` | Skill name or `--all` | Both locations, all agents |
+| `update` | `--yes` to apply updates | All tracked skills |
+
+All commands accept `--project` or `--global` to override the default location.
+
+### Confirmation behavior
+
+Confirmation prompts are skipped in non-interactive mode. Commands that modify skills (`add`, `init`, `remove`) proceed automatically. The `update` command is the exception: `--json` without `--yes` runs in **check-only mode**, reporting outdated skills without applying changes.
+
+Use `--yes` to explicitly skip confirmations in interactive mode.
 
-Exit codes help agents and scripts understand command results without parsing error messages.
+### JSON output
+
+Pass `--json` to get structured output on stdout. All commands return a common shape:
+
+```json
+{
+  "success": true,
+  "exit_code": 0,
+  "errors": []
+}
+```
+
+Each command adds its own fields: `installed` and `skipped` (add), `created` and `skipped` (init), `removed` (remove), `outdated` and `updated` (update), `installed` and `agents_detected` (list).
+
+### Exit codes
+
+Exit codes are consistent across all commands:
 
 | Code | Name | Meaning |
 |------|------|---------|
@@ -182,14 +224,21 @@ Exit codes help agents and scripts understand command results without parsing er
 | 3 | Network Error | Network failure (timeout, rate limit) |
 | 4 | Not Found | Requested resource not found (skill, agent, repo) |
 
-JSON output includes `exit_code` for programmatic access:
+### CI example
 
 ```bash
-skillfish add owner/repo --json
-# Output includes: "exit_code": 0 (or error code)
-```
+# Install skills in CI (non-interactive, JSON output)
+skillfish add owner/repo --yes --json
 
-</details>
+# Create a skill template in CI
+skillfish init --name my-skill --description "My skill" --project --json
+
+# Check for outdated skills without applying
+skillfish update --json
+
+# Apply updates
+skillfish update --yes --json
+```
 
 ---
 

package/dist/commands/add.js

@@ -6,6 +6,7 @@ import { homedir } from 'os';
 import { dirname, basename } from 'path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import { printBanner } from '../lib/banner.js';
 import { trackInstall } from '../telemetry.js';
 import { isValidPath, parseFrontmatter, deriveSkillName, toTitleCase, truncate, batchMap, createJsonOutput, isInputTTY, isTTY, } from '../utils.js';
 import { getDetectedAgents, AGENT_CONFIGS } from '../lib/agents.js';
@@ -67,11 +68,7 @@ Examples:
     }
     // Show banner and intro (TTY only, not in JSON mode)
     if (isTTY() && !jsonMode) {
-        console.log();
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log(`       ${pc.cyan('><>')}  ${pc.bold('SKILL FISH')}  ${pc.cyan('><>')}`);
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log();
+        printBanner();
         p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`v${version}`)}`);
     }
     const force = options.force ?? false;

package/dist/commands/init.js

@@ -7,6 +7,7 @@ import { join } from 'path';
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import { printBanner } from '../lib/banner.js';
 import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
 import { SKILL_FILENAME } from '../lib/github.js';
 import { EXIT_CODES } from '../lib/constants.js';
@@ -155,11 +156,7 @@ Examples:
     }
     // Show banner and intro (TTY only, not in JSON mode)
     if (isTTY() && !jsonMode) {
-        console.log();
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log(`       ${pc.cyan('><>')}  ${pc.bold('SKILL FISH')}  ${pc.cyan('><>')}`);
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log();
+        printBanner();
         p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`v${version}`)} ${pc.dim('· Create a skill')}`);
     }
     const skipPrompts = options.yes ?? false;

package/dist/commands/list.js

@@ -6,10 +6,11 @@ import { homedir } from 'os';
 import { join } from 'path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import { printBanner } from '../lib/banner.js';
 import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
 import { listInstalledSkillsInDir } from '../lib/installer.js';
 import { EXIT_CODES } from '../lib/constants.js';
-import { isInputTTY } from '../utils.js';
+import { isTTY, isInputTTY } from '../utils.js';
 export const listCommand = new Command('list')
     .description('List installed skills across all detected agents')
     .option('--project', 'List project-level skills only (./.claude)')
@@ -134,8 +135,10 @@ Examples:
                 agents_detected: detected.map((a) => a.name),
             });
         }
-        // Display intro
-        console.log();
+        // Display intro (TTY only, not in JSON mode)
+        if (isTTY() && !jsonMode) {
+            printBanner();
+        }
         p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`Skills for ${found[0].name}`)}`);
         if (globalSkills.length === 0 && projectSkills.length === 0) {
             p.outro(pc.dim('No skills installed'));
@@ -184,7 +187,9 @@ Examples:
     }
     // Interactive mode: show agent selector
     if (isInputTTY()) {
-        console.log();
+        if (isTTY() && !jsonMode) {
+            printBanner();
+        }
         p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim('Installed skills')}`);
         // Step 1: Build options with skill counts in label (always visible)
         const agentOptions = detected.map((agent) => {
@@ -254,7 +259,9 @@ Examples:
     }
     // Non-interactive mode: display all agents with skills
     const { installed, globalSkills, projectSkills } = collectSkills(detected);
-    console.log();
+    if (isTTY() && !jsonMode) {
+        printBanner();
+    }
     p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim('Installed skills')}`);
     console.log();
     console.log(pc.bold('Detected Agents'));

package/dist/commands/remove.js

@@ -7,6 +7,7 @@ import { join } from 'path';
 import { existsSync, rmSync } from 'fs';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import { printBanner } from '../lib/banner.js';
 import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
 import { listInstalledSkillsInDir } from '../lib/installer.js';
 import { isTTY, isInputTTY } from '../utils.js';
@@ -63,11 +64,7 @@ Examples:
     }
     // Show banner (TTY only, not in JSON mode)
     if (isTTY() && !jsonMode) {
-        console.log();
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log(`       ${pc.cyan('><>')}  ${pc.bold('SKILL FISH')}  ${pc.cyan('><>')}`);
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log();
+        printBanner();
         p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`v${version}`)}`);
     }
     const skipConfirm = options.yes ?? false;

package/dist/commands/update.js

@@ -6,6 +6,7 @@ import { homedir } from 'os';
 import { join } from 'path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import { printBanner } from '../lib/banner.js';
 import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
 import { listInstalledSkillsInDir, installSkill } from '../lib/installer.js';
 import { readManifest } from '../lib/manifest.js';
@@ -54,11 +55,7 @@ Examples:
     }
     // Show banner (TTY only, not in JSON mode)
     if (isTTY() && !jsonMode) {
-        console.log();
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log(`       ${pc.cyan('><>')}  ${pc.bold('SKILL FISH')}  ${pc.cyan('><>')}`);
-        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
-        console.log();
+        printBanner();
         p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`v${version}`)}`);
     }
     // Detect agents

package/dist/index.js

@@ -8,7 +8,9 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import pc from 'picocolors';
 import updateNotifier from 'update-notifier';
+import { getBannerText } from './lib/banner.js';
 import { addCommand } from './commands/add.js';
 import { initCommand } from './commands/init.js';
 import { listCommand } from './commands/list.js';
@@ -19,6 +21,16 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 // Check for updates (runs in background, non-blocking)
 const notifier = updateNotifier({ pkg });
+// Shared help styling for all commands
+const helpStyles = {
+    sortSubcommands: true,
+    styleTitle: (str) => pc.bold(pc.underline(str)),
+    styleCommandText: (str) => pc.bold(pc.cyan(str)),
+    styleSubcommandText: (str) => pc.cyan(str),
+    styleOptionText: (str) => pc.yellow(str),
+    styleArgumentText: (str) => pc.dim(str),
+    styleDescriptionText: (str) => pc.dim(str),
+};
 const program = new Command()
     .name('skillfish')
     .description('Install and manage AI agent skills from GitHub repositories')
@@ -31,18 +43,30 @@ const program = new Command()
     writeOut: (str) => process.stdout.write(str),
     writeErr: (str) => process.stderr.write(str),
 })
-    .configureHelp({
-    sortSubcommands: true,
-})
-    .addHelpText('after', `
-Examples:
-  $ skillfish add owner/repo                 Install skills from a repository
-  $ skillfish add owner/repo/plugin/skill    Install a specific skill
-  $ skillfish init                           Create a new skill template
-  $ skillfish list                           Show installed skills
-  $ skillfish remove my-skill                Remove a skill
-
-Documentation: https://skill.fish`);
+    .configureHelp(helpStyles)
+    .addHelpText('beforeAll', () => (process.stdout.isTTY ? getBannerText() : ''))
+    .addHelpText('after', () => {
+    const isTTY = process.stdout.isTTY;
+    const examples = [
+        ['skillfish add owner/repo', 'Install skills from a repository'],
+        ['skillfish add owner/repo/plugin/skill', 'Install a specific skill'],
+        ['skillfish init', 'Create a new skill template'],
+        ['skillfish list', 'Show installed skills'],
+        ['skillfish remove my-skill', 'Remove a skill'],
+    ];
+    const title = isTTY ? pc.bold(pc.underline('Examples:')) : 'Examples:';
+    const lines = examples.map(([cmd, desc]) => {
+        const prefix = isTTY ? pc.dim('  $ ') : '  $ ';
+        const command = isTTY ? pc.cyan(cmd) : cmd;
+        // Pad to align descriptions
+        const padding = ' '.repeat(Math.max(1, 42 - cmd.length));
+        const description = isTTY ? pc.dim(desc) : desc;
+        return `${prefix}${command}${padding}${description}`;
+    });
+    const docUrl = isTTY ? pc.bold(pc.cyan('https://skill.fish')) : 'https://skill.fish';
+    const docLabel = isTTY ? pc.dim('Documentation:') : 'Documentation:';
+    return `\n${title}\n${lines.join('\n')}\n\n${docLabel} ${docUrl}`;
+});
 // Store version in options for commands to access
 program.hook('preAction', (thisCommand) => {
     thisCommand.setOptionValue('version', pkg.version);
@@ -53,6 +77,10 @@ program.addCommand(initCommand);
 program.addCommand(listCommand);
 program.addCommand(removeCommand);
 program.addCommand(updateCommand);
+// Propagate help styling to all subcommands (must run after all addCommand() calls)
+for (const cmd of program.commands) {
+    cmd.configureHelp(helpStyles);
+}
 // Handle --json flag for help output
 program.on('option:json', () => {
     // JSON mode is handled by commands

package/dist/lib/banner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared ASCII art logo and banner display for skillfish CLI.
+ */
+export declare const LOGO_LINES: readonly ["   ███████╗██╗  ██╗██╗██╗     ██╗        ███████╗██╗███████╗██╗  ██╗", "   ██╔════╝██║ ██╔╝██║██║     ██║        ██╔════╝██║██╔════╝██║  ██║", "   ███████╗█████╔╝ ██║██║     ██║        █████╗  ██║███████╗███████║", "   ╚════██║██╔═██╗ ██║██║     ██║        ██╔══╝  ██║╚════██║██╔══██║", "   ███████║██║  ██╗██║███████╗███████╗██╗██║     ██║███████║██║  ██║", "   ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝"];
+/**
+ * Get the colored banner as a string.
+ * Returns the colored logo + tagline, or plain text when colors are disabled.
+ */
+export declare function getBannerText(): string;
+/**
+ * Print the colored ASCII art banner with tagline.
+ * Only outputs when stdout is a TTY.
+ */
+export declare function printBanner(): void;

package/dist/lib/banner.js

@@ -0,0 +1,68 @@
+/**
+ * Shared ASCII art logo and banner display for skillfish CLI.
+ */
+import pc from 'picocolors';
+import { isTTY } from '../utils.js';
+export const LOGO_LINES = [
+    '   ███████╗██╗  ██╗██╗██╗     ██╗        ███████╗██╗███████╗██╗  ██╗',
+    '   ██╔════╝██║ ██╔╝██║██║     ██║        ██╔════╝██║██╔════╝██║  ██║',
+    '   ███████╗█████╔╝ ██║██║     ██║        █████╗  ██║███████╗███████║',
+    '   ╚════██║██╔═██╗ ██║██║     ██║        ██╔══╝  ██║╚════██║██╔══██║',
+    '   ███████║██║  ██╗██║███████╗███████╗██╗██║     ██║███████║██║  ██║',
+    '   ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝',
+];
+// Ocean gradient colors (top to bottom): light cyan → deeper blue
+// All colors kept bright enough to be readable on dark backgrounds
+// Length must match LOGO_LINES (one color per line).
+const GRADIENT_COLORS = [
+    [0, 230, 255],
+    [0, 210, 250],
+    [0, 190, 240],
+    [0, 170, 230],
+    [0, 155, 220],
+    [0, 140, 210],
+];
+/** Check if colors are disabled via NO_COLOR convention (https://no-color.org). */
+function isColorDisabled() {
+    return 'NO_COLOR' in process.env;
+}
+/**
+ * Check if the terminal supports truecolor (24-bit) via COLORTERM env var.
+ */
+function supportsTruecolor() {
+    if (isColorDisabled())
+        return false;
+    const ct = process.env.COLORTERM;
+    return ct === 'truecolor' || ct === '24bit';
+}
+/** Apply truecolor gradient, fall back to picocolors cyan. */
+function colorLine(line, index) {
+    if (supportsTruecolor()) {
+        const color = GRADIENT_COLORS[index % GRADIENT_COLORS.length];
+        const [r, g, b] = color;
+        return `\x1b[38;2;${r};${g};${b}m${line}\x1b[0m`;
+    }
+    return pc.cyan(line);
+}
+/**
+ * Get the colored banner as a string.
+ * Returns the colored logo + tagline, or plain text when colors are disabled.
+ */
+export function getBannerText() {
+    const lines = [''];
+    for (let i = 0; i < LOGO_LINES.length; i++) {
+        lines.push(colorLine(LOGO_LINES[i], i));
+    }
+    lines.push(`   ${pc.dim('The Skill Manager for AI Coding Agents')} — ${pc.bold(pc.cyan('https://skill.fish'))}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Print the colored ASCII art banner with tagline.
+ * Only outputs when stdout is a TTY.
+ */
+export function printBanner() {
+    if (!isTTY())
+        return;
+    console.log(getBannerText());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillfish",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "All in one Skill manager for AI coding agents. Install, update, and sync Skills across Claude Code, Cursor, Copilot + more.",
   "type": "module",
   "bin": {