[STG-2191] feat(cli): static browse skill nudge + de-spam update notice

.changeset/browse-skill-nudge.md

@@ -0,0 +1,7 @@
+---
+"browse": patch
+---
+
+Surface the browse skill at runtime with two static touchpoints. Root help (`browse` / `browse --help`) now always leads with a "Start here (for AI agents)" banner pointing to `browse skills install`. Separately, the first regular command on a fresh install prints a one-time stderr hint (never stdout) when the canonical skill dir (`~/.agents/skills/browse`) is absent — gated by a once-per-install marker file in the CLI cache dir, skipped on `help`/`skills` commands and in CI/tests, and disabled with `BROWSE_DISABLE_SKILL_NUDGE=1`. No agent detection, session keys, or time windows are involved; the only check is one canonical-path lookup. Command telemetry includes a `skill_present` property driven by the same check so skill adoption is measurable.
+
+Also stop the "Update available" notice from printing on every command. The update check still refreshes its cache silently in the background, but the notice is now shown only on the human-facing surfaces — `browse` / `browse --help` and `browse doctor` — so it no longer spams scripts and agent command loops.

packages/cli/package.json

@@ -24,6 +24,7 @@
     "bin": "browse",
     "dirname": "browse",
     "commands": "./dist/commands",
+    "helpClass": "./dist/lib/help",
     "hooks": {
       "init": "./dist/hooks/init.js",
       "prerun": "./dist/hooks/prerun.js",

packages/cli/src/commands/doctor.ts

@@ -1,3 +1,5 @@
+import { join } from "node:path";
+
 import { Flags } from "@oclif/core";
 
 import { BrowseCommand } from "../base.js";
@@ -8,6 +10,7 @@ import {
 import { buildDoctorReport, renderDoctorReport } from "../lib/driver/doctor.js";
 import { sessionName } from "../lib/driver/flags.js";
 import { outputJson } from "../lib/output.js";
+import { getUpdateNotice } from "../lib/update.js";
 
 export default class Doctor extends BrowseCommand {
   static override description =
@@ -42,6 +45,20 @@ export default class Doctor extends BrowseCommand {
     }
 
     this.log(renderDoctorReport(report));
+    await this.writeUpdateNotice();
     if (report.verdict === "fail") this.exit(1);
   }
+
+  private async writeUpdateNotice(): Promise<void> {
+    try {
+      const notice = await getUpdateNotice(this.config.version, process.env, {
+        cacheFile: join(this.config.cacheDir, "update-check.json"),
+      });
+      if (notice) {
+        process.stderr.write(`\n${notice}`);
+      }
+    } catch {
+      // Best-effort update notice should never affect doctor output.
+    }
+  }
 }

packages/cli/src/hooks/init.ts

@@ -3,22 +3,41 @@ import { join } from "node:path";
 import type { Hook } from "@oclif/core";
 
 import { startTelemetryInvocation } from "../lib/telemetry.js";
-import { maybeAutoUpdateCli } from "../lib/update.js";
+import {
+  scheduleBackgroundUpdateCheck,
+  takeUpdateNotice,
+} from "../lib/update.js";
 
-const hook: Hook.Init = async function ({ config }) {
+const hook: Hook.Init = async function ({ config, id }) {
   try {
     startTelemetryInvocation();
   } catch {
     // Best-effort telemetry should never affect CLI behavior.
   }
 
   try {
-    await maybeAutoUpdateCli(config.version, process.env, {
+    // Silent: refresh the cached latest version when stale, but never print.
+    await scheduleBackgroundUpdateCheck(process.env, {
       cacheFile: join(config.cacheDir, "update-check.json"),
     });
   } catch {
     // Best-effort update checks should never affect CLI behavior.
   }
+
+  try {
+    // Remind until upgraded, at most once per interval; help and doctor render
+    // it themselves, so skip those surfaces to avoid double-printing.
+    if (id && id !== "help" && id !== "doctor") {
+      const notice = await takeUpdateNotice(config.version, process.env, {
+        cacheFile: join(config.cacheDir, "update-check.json"),
+      });
+      if (notice) {
+        process.stderr.write(`\n${notice}`);
+      }
+    }
+  } catch {
+    // Best-effort update notices should never affect CLI behavior.
+  }
 };
 
 export default hook;

packages/cli/src/lib/driver/daemon/client.ts

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import net from "node:net";
 
 import { fail } from "../../errors.js";
+import { maybeNudgeInstallSkill } from "../../skill-nudge.js";
 import type { DriverCommandName } from "../commands/types.js";
 import { targetsCompatible } from "../mode.js";
 import type { ConnectionTarget, DriverStatus, OpenResult } from "../types.js";
@@ -56,6 +57,12 @@ export async function ensureDriverDaemon({
     }
     spawnDaemon(session, target);
     await waitForSocketReady(getSocketPath(session), 30_000);
+    try {
+      // A fresh daemon marks the start of a browser session.
+      await maybeNudgeInstallSkill();
+    } catch {
+      // Best-effort nudge must never affect daemon startup.
+    }
   } finally {
     await releaseLock(session);
   }

packages/cli/src/lib/help.ts

@@ -0,0 +1,39 @@
+import { join } from "node:path";
+
+import { Help } from "@oclif/core";
+
+import { getUpdateNotice } from "./update.js";
+
+const AGENT_START_HERE = `Start here (for AI agents):
+  Run \`browse skills install\` to load the browse skill into your coding agent
+  (Claude Code, Codex, Cursor, Gemini, …), then prefer \`browse\` for browser
+  automation.
+`;
+
+/**
+ * Root-help override that leads with an agent-targeted "Start here" pointer to
+ * the browse skill — static help text, always shown on bare `browse` and
+ * `browse --help` (both route through showRootHelp). Also surfaces the update
+ * notice here and in `doctor` — the only human-facing surfaces that show it,
+ * so it never spams commands.
+ */
+export default class BrowseHelp extends Help {
+  public override async showRootHelp(): Promise<void> {
+    this.log(AGENT_START_HERE);
+    await super.showRootHelp();
+    await this.writeUpdateNotice();
+  }
+
+  private async writeUpdateNotice(): Promise<void> {
+    try {
+      const notice = await getUpdateNotice(this.config.version, process.env, {
+        cacheFile: join(this.config.cacheDir, "update-check.json"),
+      });
+      if (notice) {
+        process.stderr.write(`\n${notice}`);
+      }
+    } catch {
+      // Best-effort update notice should never affect help output.
+    }
+  }
+}

packages/cli/src/lib/skill-nudge.ts

@@ -0,0 +1,61 @@
+import { isBrowseSkillInstalled } from "./skill-presence.js";
+
+/**
+ * Stderr tip suggesting `browse skills install`, shown when a new browser
+ * session's daemon starts and the bundled skill is not installed. The daemon
+ * spawn is the session boundary, so the tip appears once per session until
+ * the skill is installed — no marker files or time windows. Best-effort and
+ * stderr-only: it can never affect machine-readable stdout.
+ */
+export async function maybeNudgeInstallSkill(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  if (isNudgeDisabled(env)) {
+    return;
+  }
+
+  if (await isBrowseSkillInstalled()) {
+    return;
+  }
+
+  writeNudge();
+}
+
+function writeNudge(): void {
+  process.stderr.write(
+    [
+      "Tip: browse works best with its skill loaded into your agent.",
+      "Run:",
+      "  browse skills install",
+      "",
+    ].join("\n"),
+  );
+}
+
+function isNudgeDisabled(env: NodeJS.ProcessEnv): boolean {
+  if (
+    env.BROWSE_DISABLE_SKILL_NUDGE === "1" ||
+    env.BB_DISABLE_SKILL_NUDGE === "1"
+  ) {
+    return true;
+  }
+  if (env.NODE_ENV === "test") {
+    return true;
+  }
+  return isCiEnvironment(env);
+}
+
+function isCiEnvironment(env: NodeJS.ProcessEnv): boolean {
+  const value = env.CI;
+  if (!value) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return !(
+    normalized === "" ||
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no" ||
+    normalized === "off"
+  );
+}

packages/cli/src/lib/skill-presence.ts

@@ -0,0 +1,36 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Check the canonical install locations for the bundled browse skill, matching
+ * the `skills` CLI's own two scopes (its source resolves
+ * `join(global ? homedir() : cwd, ".agents", "skills")`):
+ *
+ *   - global:  `~/.agents/skills/browse` — what `browse skills install`
+ *     itself writes (`npx skills add --global --agent '*'`)
+ *   - project: `<cwd>/.agents/skills/browse` — `skills add` without `-g`
+ *
+ * Agent-specific dirs are symlinks/copies alongside the canonical dir, so two
+ * filesystem checks cover every agent at both scopes.
+ */
+export async function isBrowseSkillInstalled(
+  home: string = homedir(),
+  cwd: string = process.cwd(),
+): Promise<boolean> {
+  const candidates = [
+    join(home, ".agents", "skills", "browse"),
+    join(cwd, ".agents", "skills", "browse"),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return true;
+    } catch {
+      // Keep checking the remaining scopes.
+    }
+  }
+
+  return false;
+}

packages/cli/src/lib/telemetry.ts

@@ -7,6 +7,7 @@ import type { Command } from "@oclif/core";
 
 import { detectAgent } from "./agent.js";
 import { getRunTelemetry, resetRunTelemetry } from "./run-telemetry.js";
+import { isBrowseSkillInstalled } from "./skill-presence.js";
 import type { CommandFailureTelemetry } from "./errors.js";
 
 const browserbaseTelemetrySource = "cli";
@@ -141,6 +142,9 @@ function createCliTelemetry(options: CreateCliTelemetryOptions): CliTelemetry {
     ? resolveAnonymousInstallId(env, options.sessionId)
     : Promise.resolve("");
   const agentPromise = telemetryEnabled ? detectAgent() : Promise.resolve(null);
+  const skillPresentPromise: Promise<boolean | null> = telemetryEnabled
+    ? isBrowseSkillInstalled().catch(() => null)
+    : Promise.resolve(null);
 
   const baseProperties: TelemetryProperties = {
     source: browserbaseTelemetrySource,
@@ -157,9 +161,10 @@ function createCliTelemetry(options: CreateCliTelemetryOptions): CliTelemetry {
         return;
       }
 
-      const [distinctId, agent] = await Promise.all([
+      const [distinctId, agent, skillPresent] = await Promise.all([
         distinctIdPromise,
         agentPromise,
+        skillPresentPromise,
       ]);
 
       await posthogCapture(transport, {
@@ -170,6 +175,7 @@ function createCliTelemetry(options: CreateCliTelemetryOptions): CliTelemetry {
         properties: {
           ...baseProperties,
           agent,
+          skill_present: skillPresent,
           ...properties,
         },
       });