@almyty/skills 1.2.0 → 1.3.0

package/README.md

@@ -1,12 +1,17 @@
 # @almyty/skills
 
-Install and manage almyty skills in 30+ AI coding agents (Claude Code, Cursor, Windsurf, Copilot, Codex, and more).
+Turn any API in your almyty gateways into a `SKILL.md` your coding agent
+reads on its next session. 30 agents are recognised — Claude Code,
+Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Amp, Cline,
+Continue, Goose, Junie, Roo Code, Trae, OpenHands, OpenCode, Augment and
+more — plus the universal `.agents/skills/` convention.
 
 ## Quick start
 
 ```bash
 $ npx @almyty/auth login
 $ npx @almyty/skills gateways
+$ npx @almyty/skills install org/gateway --dry-run   # see the exact files
 $ npx @almyty/skills install org/gateway
 ```
 
@@ -14,21 +19,28 @@ $ npx @almyty/skills install org/gateway
 
 | Command | Description |
 |---------|-------------|
-| `gateways` | List your gateways |
-| `list` | List all available skills |
-| `list org/gateway` | List skills from one gateway |
-| `search <query>` | Search skills by keyword |
-| `install org/gateway` | Install all skills from a gateway |
-| `install org/gateway/skill` | Install a single skill |
-| `installed` | Show locally installed skills |
-| `remove` | Remove all installed skills |
-| `run org/gateway/skill [--key value]` | Execute a skill |
-| `daemon [--interval 60]` | Sync all skills on a schedule |
-| `watch org/gateway [--interval 60]` | Watch a specific gateway for changes |
+| `gateways` | Your gateways, and the ref to install each |
+| `list` | Every skill available to you |
+| `list org/gateway` | Skills from one gateway |
+| `search <query>` | Search your gateways' skills by keyword |
+| `install org/gateway` | Install every skill from a gateway |
+| `install org/gateway/skill` | Install one skill |
+| `installed` | Skills this CLI has installed in this directory |
+| `remove` | Remove every skill this CLI installed here |
+| `run org/gateway/skill [--key value]` | Execute one skill and print its result |
+| `daemon [--interval 60]` | Re-sync every skill on a timer |
+| `watch org/gateway [--interval 60]` | Re-sync one gateway on a timer |
+
+`login`, `logout` and `whoami` moved to `@almyty/auth`; typing them here
+prints where they went and exits `2`.
 
 ## References
 
-Skills are referenced as `org/gateway` or `org/gateway/skill`:
+A skill is `org/gateway/skill`, a whole gateway is `org/gateway`, and a
+gateway UUID also works. A leading `@` is optional — `@acme/petstore`
+and `acme/petstore` are the same. A bare name is treated as a search,
+and installs only when it matches exactly one skill; an ambiguous name
+lists the matches and exits `2` rather than guessing.
 
 ```bash
 $ npx @almyty/skills install acme/petstore
@@ -37,84 +49,152 @@ $ npx @almyty/skills run acme/petstore/get-pet --id 123
 
 ## Where skills get installed
 
-`install` writes a `SKILL.md` file per skill into one or more agent
-directories. The CLI detects agents at two scopes:
+`install` writes one `SKILL.md` per skill into one or more agent
+directories, at `<skillsDir>/<skill-name>/SKILL.md`. The CLI detects
+agents at two scopes:
 
 - **Project scope** — a config dir exists in the current project
-  (e.g. `./.codex/`). Skills install to `./.codex/skills/`, only
+  (e.g. `./.codex/`). Skills install to `./.codex/skills/`, so only
   this checkout sees them.
 - **Home scope** — a config dir exists in your home directory
-  (e.g. `~/.codex/`). Skills install to `~/.codex/skills/`, every
-  project the agent opens picks them up.
+  (e.g. `~/.codex/`). Skills install to `~/.codex/skills/`, so every
+  project that agent opens picks them up.
 
-Default behavior:
+**Installing overwrites a `SKILL.md` of the same name** in the target
+directory. Nothing else in those directories is touched, and `remove`
+only deletes directories whose `SKILL.md` carries almyty's own
+`metadata.author: almyty` marker. `install` prints the directories it is
+about to write to before it writes anything, reports how many files it
+replaced, and `--dry-run` lists every path and writes nothing:
 
-- **Interactive (TTY, no flags):** the picker lists every detected
-  agent at both scopes (each labeled `(project)` or `(home)`),
-  every other supported agent as opt-in, the universal
-  `.agents/skills/` convention, and a custom-path option. Pick any
-  combination.
-- **`--yes` or non-TTY:** project-detected agents + `.agents/skills/`.
+```bash
+$ npx @almyty/skills install acme/petstore --dry-run
+
+acme/petstore (12 skill(s)) — dry run, nothing will be written:
+  Codex: /work/proj/.codex/skills
+  Universal (.agents/skills): /work/proj/.agents/skills
+
+  Codex: 12 skill file(s) would go to /work/proj/.codex/skills
+      /work/proj/.codex/skills/get-pet/SKILL.md
+      …
+
+Dry run: 24 skill file(s) across 2 target(s), 3 of them replacing an existing file.
+Re-run without --dry-run to write them.
+```
+
+### Choosing targets
+
+- **Interactive terminal, no target flag:** a multi-select picker lists
+  every detected agent at both scopes (labelled `(project)` or
+  `(home)`), every other supported agent as opt-in, the universal
+  `.agents/skills/` convention, and a custom-path option.
+- **`--yes`, `--json`, CI, or a pipe:** the picker is skipped and
+  install writes to the project-detected agents plus `.agents/skills/`.
   Home-detected agents are NOT installed automatically — pass
-  `--global` to opt in.
+  `--global`.
 - **`--global` alone:** every home-detected agent. No project install.
-- **`--all`:** every project-detected agent + universal. Combine
-  with `--global` to also include home-detected.
-- **`--agent <name>`:** install to a specific agent. Picks the
-  detected scope (project preferred). With `--global`, prefers
-  home. If neither is detected, creates the project-scope dir
-  (the agent will pick it up on next scan).
+- **`--all`:** every project-detected agent plus universal. Combine with
+  `--global` to include home-detected too.
+- **`--agent <name>`:** the named agent at whichever scope it is
+  detected in (project preferred). With `--global`, prefers home. If it
+  is detected nowhere, creates the project-scope directory so the agent
+  picks it up on its next scan.
 
 | Flag | Meaning |
 |------|---------|
-| `--agent <name>`, `-a` | Install to the named agent. Repeatable. Partial-match. |
+| `--agent <name>`, `-a` | Install to the named agent. Repeatable, partial-match. |
 | `--agent '*'` | Every known agent at project scope, regardless of detection. |
 | `--path <dir>`, `-p` | Custom skills directory. Repeatable. Bypasses detection. |
 | `--all` | Every project-detected agent + `.agents/skills/`. |
-| `--global`, `-G` | Use home scope (`~/.<agent>/skills/`). Modifier on `--agent`, or standalone for "every home-detected". |
+| `--global`, `-G` | Home scope (`~/.<agent>/skills/`). A modifier on `--agent`, or standalone for "every home-detected". |
 | `--yes`, `-y` | Skip the picker; use the non-interactive defaults. |
-
-Examples:
+| `--dry-run` | Print every file `install` would write, and write nothing. |
 
 ```bash
-$ npx @almyty/skills install acme/petstore                          # interactive picker
-$ npx @almyty/skills install acme/petstore --all                    # every project-detected
-$ npx @almyty/skills install acme/petstore --all --global           # project AND home detected
-$ npx @almyty/skills install acme/petstore --global                 # only home-detected agents
-$ npx @almyty/skills install acme/petstore -a codex                 # codex at whichever scope it lives
-$ npx @almyty/skills install acme/petstore -a codex --global        # force codex at ~/.codex/skills
-$ npx @almyty/skills install acme/petstore --agent '*' -y           # every known agent at project
-$ npx @almyty/skills install acme/petstore -p ./agents/skills       # custom directory
+$ npx @almyty/skills install acme/petstore                     # interactive picker
+$ npx @almyty/skills install acme/petstore --all               # every project-detected
+$ npx @almyty/skills install acme/petstore --all --global      # project AND home detected
+$ npx @almyty/skills install acme/petstore --global            # only home-detected agents
+$ npx @almyty/skills install acme/petstore -a codex            # codex, at whichever scope it lives
+$ npx @almyty/skills install acme/petstore -a codex --global   # force ~/.codex/skills
+$ npx @almyty/skills install acme/petstore --agent '*' -y      # every known agent, project scope
+$ npx @almyty/skills install acme/petstore -p ./agents/skills  # a directory you name
 ```
 
-The 25+ supported agents include Claude Code, Codex, Cursor, Windsurf,
-GitHub Copilot, Gemini CLI, Amp, Cline, Continue, Goose, Junie, Roo
-Code, Trae, OpenHands, OpenCode, Augment, and others. See
-`src/agents.ts` for the full registry — each entry maps a detection
-directory to the `<dir>/skills` path that agent reads on session start.
+`src/agents.ts` is the registry: each entry maps a detection directory
+to the `<dir>/skills` path that agent reads on session start.
+
+## Other options
+
+| Flag | Description |
+|------|-------------|
+| `--interval <s>`, `-i` | `daemon`/`watch` poll interval (default `60`) |
+| `--url <url>` | API URL (default `https://api.almyty.com`) |
+| `--dir <path>` | Project directory (default: cwd) |
+| `--json` | Machine-readable output on every read command |
+| `--help`, `-h` | Show help |
+| `--version`, `-v` | Print the version |
+
+Both `--flag value` and `--flag=value` are accepted. `run` forwards
+every flag the CLI does not own to the skill as a parameter, so
+`run acme/pet/get-pet --petId 123` sends `{ petId: "123" }`.
+
+`run` prints its result as JSON always — the result *is* data. Every
+other read command prints for humans by default and takes `--json`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | unexpected error |
+| `2` | usage error (bad flags, unknown command, ambiguous ref) |
+| `3` | not authenticated — run `npx @almyty/auth login` |
+| `4` | no such gateway or skill |
+| `5` | the skill ran and failed |
 
 ## Configuration
 
-Create `.almytyrc` in your project or home directory:
+`.almytyrc`, JSON, in the project directory or `$HOME`:
 
 ```json
 {
+  "skillsDir": ".agents/skills",
+  "agents": ["Codex", "Claude Code"],
   "url": "https://api.almyty.com",
-  "token": "your-token"
+  "interval": 60
 }
 ```
 
+| Key | Effect |
+|-----|--------|
+| `skillsDir` | Install here and skip agent detection entirely |
+| `agents` | Whitelist of agent names (partial match) to install to |
+| `url` | API URL |
+| `interval` | `daemon`/`watch` poll interval, in seconds |
+
+There is **no credential key**. The token lives only in
+`~/.almyty/credentials.json` (written by `npx @almyty/auth login`) or in
+`ALMYTY_TOKEN`.
+
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
 | `ALMYTY_TOKEN` | Auth token override |
 | `ALMYTY_URL` | API URL override |
-| `ALMYTY_SKILLS_DIR` | Custom directory for installed skill files |
+| `ALMYTY_SKILLS_DIR` | Install directory override; wins over `.almytyrc` |
+| `ALMYTY_NON_INTERACTIVE=1` | Never prompt, even in a terminal |
+| `CI` | Any truthy value has the same effect |
+| `NO_COLOR` | Drops colour from the interactive picker |
 
 ## Authentication
 
-Requires `npx @almyty/auth login` first. Reads credentials from `~/.almyty/credentials.json`.
+Run `npx @almyty/auth login` once. `search` and `list` are org-scoped —
+they look through the gateways your account can see, so there is no
+credential-free public index to search. With no credential, every
+command that talks to the API prints the login instruction and exits
+`3`; `installed` and `remove` are local and need none.
 
 ## About almyty
 
@@ -122,8 +202,10 @@ almyty is the full-stack platform for AI agents, agnostic by design: any LLM, an
 API turned into tools, served over MCP, A2A, UTCP, and Agent Skills. Open source,
 no lock-in.
 
-- Website — https://almyty.com
-- Docs — https://docs.almyty.com
-- Source — https://github.com/almyty-inc/almyty
+- Website: https://almyty.com
+- Docs: https://docs.almyty.com
+- Source: https://github.com/almyty-inc/almyty
+
+This CLI is part of the `@almyty/*` suite (versioned together at 1.x) and works with the almyty platform 0.1 and later.
 
 Apache-2.0 © Almyty Inc.

package/dist/auth.d.ts

@@ -1,6 +1,13 @@
 /**
- * Thin re-export from the shared @almyty/client credential resolver.
- * Keeps `./auth.js` imports working across the skills-cli codebase.
+ * Credential access for the skills CLI.
+ *
+ * Thin re-export of the shared resolver in @almyty/client, so there is
+ * one credential file and one way to read it.
+ *
+ * `resolveCredentialsOrExit` is not re-exported. index.ts does the check
+ * itself in `requireAuth` — it predates the shared helper exiting 3, and
+ * either route is correct now. Both answer a missing credential with 3,
+ * which is what a script branches on.
  */
-export { resolveCredentials, resolveCredentialsOrExit, resolveCredentialsOrExit as resolveAuth, loadCredentials, CREDENTIALS_FILE, } from '@almyty/client';
+export { resolveCredentials, loadCredentials, CREDENTIALS_FILE, } from '@almyty/client';
 export type { StoredCredentials } from '@almyty/client';

package/dist/auth.js

@@ -1,5 +1,12 @@
 /**
- * Thin re-export from the shared @almyty/client credential resolver.
- * Keeps `./auth.js` imports working across the skills-cli codebase.
+ * Credential access for the skills CLI.
+ *
+ * Thin re-export of the shared resolver in @almyty/client, so there is
+ * one credential file and one way to read it.
+ *
+ * `resolveCredentialsOrExit` is not re-exported. index.ts does the check
+ * itself in `requireAuth` — it predates the shared helper exiting 3, and
+ * either route is correct now. Both answer a missing credential with 3,
+ * which is what a script branches on.
  */
-export { resolveCredentials, resolveCredentialsOrExit, resolveCredentialsOrExit as resolveAuth, loadCredentials, CREDENTIALS_FILE, } from '@almyty/client';
+export { resolveCredentials, loadCredentials, CREDENTIALS_FILE, } from '@almyty/client';

package/dist/cli-args.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Command-line parsing for @almyty/skills.
+ *
+ * Its own module so the surface can be unit-tested without importing
+ * the entry point (which would need a credential store and would run
+ * main() on import).
+ */
+export interface ParsedArgs {
+    command?: string;
+    ref?: string;
+    positional: string[];
+    flags: Record<string, string | string[] | boolean>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function getRef(args: ParsedArgs): string | null;
+export declare function parseRunParams(args: ParsedArgs): Record<string, any>;

package/dist/cli-args.js

@@ -0,0 +1,152 @@
+/**
+ * Repeatable flags accumulate into a string[] when supplied more
+ * than once. Used by `--agent` and `--path` so callers can pick
+ * multiple targets without inventing comma syntax (the selector
+ * also splits on comma/space, so both styles work).
+ */
+const REPEATABLE_FLAGS = new Set(['agent', 'path']);
+/** Switches: never take a value, never swallow the next token. */
+const BOOLEAN_FLAGS = new Set([
+    'all',
+    'yes',
+    'global',
+    'help',
+    'version',
+    'json',
+    'dry-run',
+]);
+/**
+ * Flags that belong to the CLI itself, so `run` does not forward them
+ * to the skill as parameters. `--json` and `--dry-run` were added
+ * later; without them here, `run x --json` would have sent the skill a
+ * parameter called `json`.
+ */
+const RESERVED_FLAGS = new Set([
+    'url',
+    'dir',
+    'help',
+    'version',
+    'interval',
+    'gateway',
+    'agent',
+    'path',
+    'all',
+    'yes',
+    'global',
+    'json',
+    'dry-run',
+]);
+function appendRepeatable(flags, key, value) {
+    const existing = flags[key];
+    if (existing === undefined || existing === true || existing === false) {
+        flags[key] = value;
+    }
+    else if (typeof existing === 'string') {
+        flags[key] = [existing, value];
+    }
+    else {
+        existing.push(value);
+    }
+}
+function setFlag(flags, key, value) {
+    if (REPEATABLE_FLAGS.has(key))
+        appendRepeatable(flags, key, value);
+    else
+        flags[key] = value;
+}
+export function parseArgs(argv) {
+    const result = { positional: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            result.positional.push(...argv.slice(i + 1));
+            break;
+        }
+        // Short aliases. `-g` stays on --gateway for back-compat; -G is
+        // --global.
+        if (arg === '-g') {
+            result.flags.gateway = argv[++i] ?? '';
+            continue;
+        }
+        if (arg === '-i') {
+            result.flags.interval = argv[++i] ?? '60';
+            continue;
+        }
+        if (arg === '-a') {
+            appendRepeatable(result.flags, 'agent', argv[++i] ?? '');
+            continue;
+        }
+        if (arg === '-p') {
+            appendRepeatable(result.flags, 'path', argv[++i] ?? '');
+            continue;
+        }
+        if (arg === '-y') {
+            result.flags.yes = true;
+            continue;
+        }
+        if (arg === '-G') {
+            result.flags.global = true;
+            continue;
+        }
+        if (arg === '-h') {
+            result.flags.help = true;
+            continue;
+        }
+        if (arg === '-v') {
+            result.flags.version = true;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            const body = arg.slice(2);
+            const eq = body.indexOf('=');
+            if (eq !== -1) {
+                // `--agent=codex` and `--input={"a":1}` both used to become a
+                // flag whose NAME was the whole `key=value` string.
+                setFlag(result.flags, body.slice(0, eq), body.slice(eq + 1));
+                continue;
+            }
+            if (BOOLEAN_FLAGS.has(body)) {
+                result.flags[body] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                setFlag(result.flags, body, next);
+                i++;
+            }
+            else {
+                result.flags[body] = true;
+            }
+            continue;
+        }
+        // A bare word containing a slash is a gateway/skill reference.
+        if (arg.includes('/')) {
+            result.ref = arg;
+            continue;
+        }
+        if (!result.command)
+            result.command = arg;
+        else
+            result.positional.push(arg);
+    }
+    return result;
+}
+export function getRef(args) {
+    if (args.ref)
+        return args.ref;
+    if (typeof args.flags.gateway === 'string' && args.flags.gateway) {
+        return args.flags.gateway;
+    }
+    if (args.positional.length > 0)
+        return args.positional[0];
+    return null;
+}
+export function parseRunParams(args) {
+    const params = {};
+    for (const [key, value] of Object.entries(args.flags)) {
+        if (RESERVED_FLAGS.has(key))
+            continue;
+        params[key] = value;
+    }
+    return params;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+export declare const EXIT: {
+    /** Success. */
+    readonly OK: 0;
+    /** Unexpected failure (a thrown error with no better classification). */
+    readonly ERROR: 1;
+    /** Bad or missing arguments, or an unknown command. */
+    readonly USAGE: 2;
+    /** No stored credential, or the API rejected the one we had. */
+    readonly AUTH: 3;
+    /** The named agent / gateway / skill / run does not exist. */
+    readonly NOT_FOUND: 4;
+    /** The command ran; the operation it asked for failed. */
+    readonly FAILED: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** One line per code, for `--help` output and READMEs. */
+export declare const EXIT_CODE_HELP: string;

package/dist/exit-codes.js

@@ -0,0 +1,32 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Unexpected failure (a thrown error with no better classification). */
+    ERROR: 1,
+    /** Bad or missing arguments, or an unknown command. */
+    USAGE: 2,
+    /** No stored credential, or the API rejected the one we had. */
+    AUTH: 3,
+    /** The named agent / gateway / skill / run does not exist. */
+    NOT_FOUND: 4,
+    /** The command ran; the operation it asked for failed. */
+    FAILED: 5,
+};
+/** One line per code, for `--help` output and READMEs. */
+export const EXIT_CODE_HELP = [
+    '  0  success',
+    '  1  unexpected error',
+    '  2  usage error (bad flags, unknown command)',
+    '  3  not authenticated — run `almyty login`',
+    '  4  not found (agent, gateway, skill, or run)',
+    '  5  the operation ran and failed',
+].join('\n');

package/dist/help.d.ts

@@ -0,0 +1,2 @@
+export declare function helpText(): string;
+export declare function printHelp(): void;

package/dist/help.js

@@ -0,0 +1,111 @@
+/**
+ * `--help` for @almyty/skills.
+ *
+ * Kept in its own module so the text can be asserted against the code's
+ * real surface: there are tests that every dispatched command, every
+ * parsed flag and every environment variable the code reads appears
+ * here. `watch` was implemented and dispatched while appearing nowhere
+ * in --help, which is how a command becomes source-only folklore.
+ */
+import { VERSION } from './version.js';
+import { AGENT_CONFIGS } from './agents.js';
+export function helpText() {
+    return `@almyty/skills v${VERSION}
+
+Turn any API in your almyty gateways into a SKILL.md your coding agent
+reads on its next session. ${AGENT_CONFIGS.length} agents are recognised, plus the universal
+.agents/skills/ convention.
+
+Usage:
+  npx @almyty/skills <command> [options]
+
+Commands:
+  install <ref>                  Write skills into local AI coding agents
+  list [ref]                     Skills available to you, all or per gateway
+  search <query>                 Search your gateways' skills by keyword
+  run <ref> [--key value ...]    Execute one skill and print its result
+  installed                      Skills this CLI has installed here
+  remove                         Remove every skill this CLI installed here
+  gateways                       Your gateways, and the ref to install each
+  daemon                         Re-sync every skill on a timer
+  watch <ref>                    Re-sync one gateway on a timer
+  help                           Show this help
+
+References:
+  org/gateway                    All skills from one gateway
+  org/gateway/skill              One skill
+  skill-name                     Search by name, install if it is unambiguous
+  <uuid>                         A gateway by id
+  A leading @ is optional: @acme/petstore and acme/petstore are the same.
+
+Install targets:
+  --agent, -a <name>             Install to the named agent. Repeatable,
+                                 partial match ("-a codex -a claude").
+                                 '*' or 'all' means every known agent.
+  --path, -p <dir>               Install to this directory. Repeatable.
+                                 Bypasses agent detection entirely.
+  --all                          Every PROJECT-detected agent, plus the
+                                 universal .agents/skills/. Skips the picker.
+  --global, -G                   Home scope (~/.codex/skills/ etc.) instead
+                                 of project scope. With --all, adds
+                                 home-detected agents to the project ones.
+  --yes, -y                      Skip the picker; use the non-interactive
+                                 defaults (project-detected + universal).
+  --dry-run                      Print every file install would write, and
+                                 write nothing.
+
+Options:
+  --interval, -i <seconds>       daemon/watch poll interval (default 60)
+  --url <url>                    API URL (default https://api.almyty.com)
+  --dir <path>                   Project directory (default: cwd)
+  --json                         Machine-readable output, no decoration
+  --help, -h                     Show this help
+  --version, -v                  Print the version
+
+Config (.almytyrc, in the project dir or $HOME, JSON):
+  skillsDir                      Install here and skip detection
+  agents                         Whitelist of agent names to install to
+  url                            API URL
+  interval                       daemon/watch poll interval, in seconds
+  The credential is NOT read from here — it lives in
+  ~/.almyty/credentials.json, written by \`npx @almyty/auth login\`.
+
+Environment:
+  ALMYTY_TOKEN                   Token override
+  ALMYTY_URL                     API URL override
+  ALMYTY_SKILLS_DIR              Install directory override
+  ALMYTY_NON_INTERACTIVE=1       Never prompt, even in a terminal
+  CI                             Same effect as ALMYTY_NON_INTERACTIVE
+  NO_COLOR                       Drop colour from the interactive picker
+
+Target selection:
+  With no target flag in an interactive terminal, install shows a
+  multi-select picker: detected agents pre-checked, every other known
+  agent as opt-in, the universal directory, and a custom path. In CI or
+  a pipe the picker is skipped and install writes to the detected agents
+  plus .agents/skills/ — run --dry-run first to see exactly where.
+
+Installing overwrites a SKILL.md of the same name in the target
+directory. Nothing else in those directories is touched, and \`remove\`
+only deletes skills carrying almyty's own frontmatter marker.
+
+Exit codes:
+  0  success
+  1  unexpected error
+  2  usage error (bad flags, unknown command)
+  3  not authenticated — run \`npx @almyty/auth login\`
+  4  no such gateway or skill
+  5  the skill ran and failed
+
+Examples:
+  npx @almyty/skills gateways
+  npx @almyty/skills install acme/petstore --dry-run
+  npx @almyty/skills install acme/petstore -a codex -a claude
+  npx @almyty/skills install acme/petstore --all --global
+  npx @almyty/skills search weather --json
+  npx @almyty/skills run acme/petstore/get-pet --petId 123
+`;
+}
+export function printHelp() {
+    console.log(helpText());
+}