v0.2.5: Linux-specific install commands + docs URL for agents (#13)

Problem: on the Dashboard "Install" modal, Linux users saw the macOS
command (brew install --cask …) with no fallback. Five agents were
affected — Antigravity, Qoder, Trae, Warp, Windsurf — whose install_command
was macOS-specific. The UI copied the brew command verbatim, which fails
on Linux, and linked to a formulae.brew.sh page that's meaningless there.

Schema changes:
  - `install_command_linux?: string | null`
  - `install_docs_url_linux?: string | null`
Added through the full stack: agents/*.toml → src/main/types.ts →
src/main/registry.ts → src/main/skill-json.ts → src/shared/rpc-schema.ts
→ src/mainview/hooks/useAgents.ts → Dashboard.tsx.

Renderer logic:
  - New `detectOS()` prefers `window.api.platform` from the Electron preload
    (reliable — Electron sets it to `darwin`/`win32`/`linux`) and falls
    back to userAgent sniffing for plain-Vite dev.
  - `getInstallCommand(agent)` returns the OS-specific command, falling
    back to `install_command` ONLY when it starts with a cross-platform
    prefix (npm/npx/pnpm/yarn/bun/pip/pipx/cargo/go/curl/wget). macOS-
    specific installers (brew, mas) never leak to Linux/Windows now.
  - `getInstallDocsUrl(agent)` checks for a Linux override before falling
    back to the shared `install_docs_url`.
  - `Dashboard.tsx::InstallGuideModal` replaces its inline
    `isWindows ? … : …` with these helpers so all three OSes are handled
    uniformly.

TOML data:
  - qoder: `install_command_linux = "npm install -g @qoder-ai/qodercli"`
    (the Windows command happens to be the right one for Linux too).
  - antigravity, warp, windsurf, trae: no `install_command_linux` (Google
    and Warp distribute through their own apt/yum repos with per-distro
    one-liners; Trae has no native Linux build yet). All four get an
    `install_docs_url_linux` pointing at the official Linux download page
    so users click through to authoritative instructions instead of a
    useless brew-cask URL.

Version bump to 0.2.5 so the change lands via electron-updater.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: beautyfree

agents/antigravity.toml

@@ -6,7 +6,12 @@ skill_format = "skill-md"
 cli_command = "antigravity"
 install_command = "brew install --cask antigravity"
 install_command_windows = "winget install Google.Antigravity"
+# Linux: Google ships .deb and .tar.gz from their official download page but
+# doesn't publish a stable one-liner install script we can hardcode. Leave the
+# command empty — the UI hides the "copy install command" block when null and
+# shows the docs-URL button instead, which points to the Linux download page.
 install_docs_url = "https://formulae.brew.sh/cask/antigravity"
+install_docs_url_linux = "https://antigravity.google/download/linux"
 install_source_label = "homebrew-cask"
 
 [[additional_readable_paths]]

agents/qoder.toml

@@ -6,5 +6,8 @@ skill_format = "skill-md"
 cli_command = "qodercli"
 install_command = "brew install qoderai/qoder/qodercli --cask"
 install_command_windows = "npm install -g @qoder-ai/qodercli"
+# qodercli is a cross-platform npm package — the Windows command works as-is
+# on Linux too.
+install_command_linux = "npm install -g @qoder-ai/qodercli"
 install_docs_url = "https://docs.qoder.com/cli/quick-start"
 install_source_label = "official-docs"

agents/trae.toml

@@ -6,5 +6,9 @@ skill_format = "skill-md"
 cli_command = "trae"
 install_command = "brew install --cask trae"
 install_command_windows = "winget install ByteDance.Trae"
+# Trae has no native Linux desktop build as of 2026 (only macOS, Windows, and
+# the web-based Cloud IDE). No install_command_linux — the UI hides the copy-
+# command block and points the user at the web IDE via docs URL.
 install_docs_url = "https://formulae.brew.sh/cask/trae"
+install_docs_url_linux = "https://www.trae.ai/download"
 install_source_label = "homebrew-cask"

agents/warp.toml

@@ -5,7 +5,11 @@ global_paths = ["~/.warp/skills"]
 skill_format = "skill-md"
 install_command = "brew install --cask warp"
 install_command_windows = "winget install Warp.Warp"
+# Linux: Warp publishes deb/rpm/pkg.tar.zst via their APT/YUM repos. The
+# docs page covers every distro's package-manager recipe — safer than
+# hardcoding a single distro's commands here.
 install_docs_url = "https://www.warp.dev/"
+install_docs_url_linux = "https://docs.warp.dev/getting-started/installation-and-setup"
 install_source_label = "official-site"
 detect_paths = ["/Applications/Warp.app", "~/AppData/Roaming/warp/Warp", "~/.local/share/warp-terminal"]
 

agents/windsurf.toml

@@ -6,5 +6,9 @@ skill_format = "skill-md"
 cli_command = "windsurf"
 install_command = "brew install --cask windsurf"
 install_command_windows = "winget install Codeium.Windsurf"
+# Linux: Windsurf ships AppImage, deb, and tar.gz + GPG-signed apt/yum repos.
+# Their download page renders distro-specific one-liners (e.g. apt vs dnf vs
+# tarball), so we route the user there instead of hardcoding one flavor.
 install_docs_url = "https://formulae.brew.sh/cask/windsurf"
+install_docs_url_linux = "https://windsurf.com/editor/download-linux"
 install_source_label = "homebrew-cask"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "skiller",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "A desktop app for managing AI agent skills across Claude Code, Cursor, Copilot, Gemini CLI, and more",
   "license": "MIT",
   "author": {

src/main/registry.ts

@@ -66,7 +66,9 @@ export function loadAgentConfigs(dir: string): AgentConfig[] {
 			cli_command: parsed.cli_command as string | null | undefined,
 			install_command: parsed.install_command as string | null | undefined,
 			install_command_windows: parsed.install_command_windows as string | null | undefined,
+			install_command_linux: parsed.install_command_linux as string | null | undefined,
 			install_docs_url: parsed.install_docs_url as string | null | undefined,
+			install_docs_url_linux: parsed.install_docs_url_linux as string | null | undefined,
 			install_source_label: parsed.install_source_label as string | null | undefined,
 			detect_paths: (parsed.detect_paths as string[] | undefined)?.map((p) => expandHome(p)) ?? [],
 		});

src/main/skill-json.ts

@@ -67,7 +67,9 @@ export function agentConfigToJson(
 		cli_command: a.cli_command ?? null,
 		install_command: a.install_command ?? null,
 		install_command_windows: a.install_command_windows ?? null,
+		install_command_linux: a.install_command_linux ?? null,
 		install_docs_url: a.install_docs_url ?? null,
+		install_docs_url_linux: a.install_docs_url_linux ?? null,
 		install_source_label: a.install_source_label ?? null,
 		detect_paths: a.detect_paths,
 		detected: a.detected,

src/main/types.ts

@@ -30,7 +30,9 @@ export interface AgentConfig {
 	cli_command?: string | null;
 	install_command?: string | null;
 	install_command_windows?: string | null;
+	install_command_linux?: string | null;
 	install_docs_url?: string | null;
+	install_docs_url_linux?: string | null;
 	install_source_label?: string | null;
 	detect_paths: string[];
 	detected: boolean;

src/mainview/hooks/useAgents.ts

@@ -10,19 +10,92 @@ export interface AgentConfig {
   cli_command: string | null;
   install_command: string | null;
   install_command_windows: string | null;
+  install_command_linux: string | null;
   install_docs_url: string | null;
+  install_docs_url_linux: string | null;
   install_source_label: string | null;
   detected: boolean;
 }
 
-/** Get the platform-appropriate install command */
+type OS = "windows" | "linux" | "macos";
+
+function detectOS(): OS {
+  // window.api.platform comes from the Electron preload bridge. Fall back to
+  // userAgent sniffing for plain-Vite dev (`vite dev` without the Electron
+  // shell) so the install buttons still resolve to something sensible.
+  const native = (globalThis as { api?: { platform?: string } }).api?.platform;
+  if (native === "win32") return "windows";
+  if (native === "linux") return "linux";
+  if (native === "darwin") return "macos";
+  if (typeof navigator === "undefined") return "macos";
+  const ua = navigator.userAgent;
+  if (ua.includes("Windows")) return "windows";
+  if (ua.includes("Linux")) return "linux";
+  return "macos";
+}
+
+/**
+ * Get the platform-appropriate install command. `install_command` is the
+ * default (macOS-flavored — brew cask, curl | bash, npm -g). Windows and
+ * Linux get their own optional fields; if null, we fall back to the default
+ * ONLY when the default is plausibly cross-platform (starts with `npm `).
+ * Otherwise return null so the UI can show "no install command for this OS".
+ */
 export function getInstallCommand(agent: AgentConfig): string | null {
-  if (navigator.userAgent.includes("Windows")) {
-    return agent.install_command_windows ?? agent.install_command;
+  const os = detectOS();
+  if (os === "windows") {
+    return agent.install_command_windows ?? fallbackDefault(agent);
+  }
+  if (os === "linux") {
+    return agent.install_command_linux ?? fallbackDefault(agent);
   }
   return agent.install_command;
 }
 
+/**
+ * When a platform-specific command isn't defined, we fall back to the default
+ * `install_command` ONLY if it looks host-agnostic. Whitelist:
+ *   - node ecosystem (`npm`, `npx`, `pnpm`, `yarn`, `bun`)
+ *   - python (`pip`, `pipx`)
+ *   - rust/go (`cargo`, `go install`)
+ *   - `curl | bash` style installers — these are almost always cross-platform
+ *     in practice (the script inside branches on `uname`)
+ * Blacklist (implicit — anything not matched returns null): `brew`, `winget`,
+ * `choco`, `scoop`, `apt`, `snap`, `flatpak`, etc. — all OS-specific.
+ */
+function fallbackDefault(agent: AgentConfig): string | null {
+  const cmd = agent.install_command;
+  if (!cmd) return null;
+  const trimmed = cmd.trim();
+  const head = trimmed.split(/\s+/)[0];
+  const CROSS_PLATFORM_PREFIXES = [
+    "npm",
+    "npx",
+    "pnpm",
+    "yarn",
+    "bun",
+    "bunx",
+    "pip",
+    "pipx",
+    "cargo",
+    "go",
+    "curl", // curl|bash installers branch on uname internally
+    "wget",
+  ];
+  if (CROSS_PLATFORM_PREFIXES.includes(head)) return cmd;
+  return null;
+}
+
+/** Get the platform-appropriate docs URL. Linux can override the default
+ *  since the default often points at Homebrew-cask pages that are useless
+ *  for Linux users. */
+export function getInstallDocsUrl(agent: AgentConfig): string | null {
+  if (detectOS() === "linux" && agent.install_docs_url_linux) {
+    return agent.install_docs_url_linux;
+  }
+  return agent.install_docs_url;
+}
+
 export function useAgents() {
   return useQuery<AgentConfig[]>({
     queryKey: ["agents"],