[STG-2511] feat: add browse skills show and agent-facing --help header

[shrey150]

Why

Agents run browse inside sandboxes/harnesses we don't control, so they can't rely on a copied SKILL.md or a docs URL staying in sync with the installed CLI version. Serving the skill straight from the binary means the guidance is always version-matched to whatever browse the agent actually has.

This converges with the shape competitors have already landed on:

• agent-browser: agent-browser skills get core --full + a top-of---help "Start here (for AI agents)" header
• Modal: modal skills show
• browser-use: skill show

What changed

• Added browse skills show (packages/cli/src/commands/skills/show.ts), following the existing skills topic command style (BrowseCommand base, single-line description, examples). It resolves and prints the bundled SKILL.md via the same bundledCliSkillPath() helper skills install already uses (exported from packages/cli/src/lib/skills/install.ts), so path resolution is shared and works in both src and dist layouts. Reads the file synchronously and calls this.error(...) with a clear message + non-zero exit if it's missing/unreadable.
• Added a custom oclif Help class (packages/cli/src/help.ts) that prepends a short agent-facing block before oclif's auto-generated VERSION/USAGE/DESCRIPTION/TOPICS/COMMANDS sections on root help only (browse --help and bare browse). Wired via "helpClass": "./dist/help.js" in packages/cli/package.json's oclif config. Per-command --help views (e.g. browse open --help) are unaffected.
• Added a patch changeset — browse is in the changesets ignore list by default, but per team convention it still gets patch changesets for release-impacting CLI changes.
• Tests: new packages/cli/tests/skills-show.test.ts (happy path + resolution from a different cwd), plus updates to packages/cli/tests/cli-surface.test.ts for the new skills show command help, the agent header appearing before USAGE on root help, and its absence on command help.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
node packages/cli/bin/run.js skills show | head -20	Prints bundled SKILL.md frontmatter: name: browse, description: Use the browse CLI for..., # Browse CLI heading	Proves the command reads and prints the real bundled skill from the local build, not a mock
node packages/cli/bin/run.js skills show | wc -lc	369 17221 (369 lines, 17221 bytes)	Confirms full file is printed, not truncated
node packages/cli/bin/run.js --help | head -25	Output opens with Start here (for AI agents): / browse skills show / rationale block, then Unified Browserbase CLI..., VERSION, USAGE, TOPICS (incl. skills)	Confirms header renders before the auto-generated sections on --help
node packages/cli/bin/run.js | head -25	Same header block, same ordering, for bare browse with no args	Confirms bare invocation (not just --help) also gets the header
node packages/cli/bin/run.js open --help | head -15	Standard command help (Open a URL in a browse driver session., USAGE, ARGUMENTS, FLAGS) with no agent header	Confirms per-command help is unaffected
cd /tmp && node <worktree>/packages/cli/bin/run.js skills show | head -3	Same SKILL.md frontmatter, run from an unrelated cwd	Confirms path resolution is relative to the module file, not process.cwd() — required for the dist-layout published package
pnpm test:cli (vitest)	Test Files 24 passed (24), Tests 349 passed (349)	Full existing CLI suite plus new/updated tests all green — no regressions
pnpm lint (prettier + eslint + tsc)	All three steps pass with no output/errors	Static checks clean

Linear

https://linear.app/browserbase/issue/STG-2511/add-browse-skills-show-agent-facing-help-header

🤖 Generated with Claude Code

---

Summary by cubic

Adds browse skills show to print the bundled SKILL.md for version-matched guidance, and adds an agent-facing header on root help pointing to it. Addresses STG-2511.

• New Features

  • browse skills show prints the bundled skill via bundledCliSkillPath() and, on error, uses fail() (exit 1 with resultCode: "skill_show_missing").
  • Root help (browse --help and bare browse) prepends a short “Start here” header; per-command help is unchanged. Wired via helpClass in packages/cli/package.json.
  • Exported bundledCliSkillPath() so path resolution works in both src and dist.

• Refactors

  • Use fs/promises.readFile for async skill file reads.

^{Written for commit 2a74053. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 2a74053

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 7 files

Confidence score: 5/5

• Safe to merge after the addressed issues were fixed.

Architecture diagram

sequenceDiagram
    participant Agent as AI Agent
    participant CLI as browse CLI (oclif)
    participant Help as BrowseHelp (custom Help class)
    participant CmdShow as SkillsShow command
    participant FS as Node.js File System
    participant BundledSkill as bundled SKILL.md

    Note over Agent,BundledSkill: Agent-Facing Root Help Flow (browse --help / browse)
    Agent->>CLI: browse --help (or bare browse)
    CLI->>Help: showRootHelp()
    Help->>Help: log AGENT_HEADER ("Start here (for AI agents):…")
    Help->>CLI: super.showRootHelp() – auto-generated VERSION, USAGE, TOPICS, COMMANDS
    CLI-->>Agent: Full help output with agent header prepended

    Note over Agent,BundledSkill: Per-Command Help Flow (unaffected)
    Agent->>CLI: browse open --help
    CLI->>CLI: default oclif command help
    CLI-->>Agent: Standard command help (no agent header)

    Note over Agent,BundledSkill: Skills Show Flow
    Agent->>CLI: browse skills show
    CLI->>CmdShow: run()
    CmdShow->>CmdShow: bundledCliSkillPath() → path to skills/browse/ directory
    CmdShow->>FS: join(path, "SKILL.md")
    FS-->>CmdShow: resolved absolute path to SKILL.md

    alt Success: SKILL.md exists and is readable
        CmdShow->>FS: readFileSync(skillMdPath, "utf8")
        FS-->>CmdShow: file contents (markdown string)
        CmdShow->>CmdShow: this.log(contents) – print to stdout
        CmdShow-->>CLI: exit code 0
        CLI-->>Agent: Full SKILL.md content printed
    else Error: SKILL.md missing or unreadable
        CmdShow->>FS: readFileSync(skillMdPath, "utf8")
        FS-->>CmdShow: error (ENOENT, EACCES, etc.)
        CmdShow->>CmdShow: this.error("Could not read…") – non-zero exit
        CmdShow-->>CLI: exit code non-zero (oclif handles formatted error display)
        CLI-->>Agent: Error message to stderr
    end

    Note over Agent,FS: Path Resolution (handles both src and dist layouts)
    CmdShow->>CmdShow: packageRoot() – based on __dirname of module file
    CmdShow->>FS: join(packageRoot(), "skills", "browse")
    FS-->>CmdShow: path → works from any process.cwd()

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>