[STG-2274] docs(cli): add 401 playbook + anti-retry guidance to bundled browse skill
Summary
Adds death-loop prevention guidance to the bundled browse skill (packages/cli/skills/browse/SKILL.md) — the skill agents install via browse skills install.
Impact if merged
Most agent traffic reaches the CLI through this bundled skill — it is the agent interface. The current text has no 401/invalid-key playbook and no anti-retry rule, the two behaviors behind the death-loop population: 71 installs generating 92.3% of all CLI telemetry (~5.5M events/30d) retrying get/screenshot, including ~375k events from tagged claude-code/codex agents — the core ICP. Docs-only, zero runtime risk; pairs with the in-flight driver-error remediation PR (the code-side fix for the same loops).
Changes
- 401 playbook (Troubleshooting): a set
BROWSERBASE_API_KEYmakesbrowsedefault to remote mode (src/lib/driver/remote.tsdefaultRemoteTarget), so an invalid key turns every driver command into a 401. New entry tells agents to fix the key at https://browserbase.com/settings, unset it, or pass--local. - Anti-retry rule (Best Practices #9 + Troubleshooting): never retry a failing command unchanged — if the same command fails twice with the same error, stop, run
browse doctor --json, then change approach. Init failures are cached in the daemon for several seconds (INIT_FAILURE_RETRY_MSinsession-manager.ts), so instant retries return identical errors.
3. Screenshot guidance — moved to #2246 per review, where it documents the new file-by-default behavior that PR ships (reverted here in cb6e0c6db).
No changeset: docs/prompt-text only — ships with the next regular browse release, no version bump needed.
E2E Test Matrix
| Command / flow | Observed output | Confidence / sufficiency |
|---|---|---|
<local build>: pnpm turbo run build --filter=browse... then node bin/run.js skills install | Installed from <worktree>/packages/cli/skills/browse to ~/.agents/skills/browse across 71 agents (universal + symlinked) | Proves the bundled skill file under review is exactly what skills install ships |
grep -n "401 Unauthorized|Never retry a failing command|stop retrying" ~/.agents/skills/browse/SKILL.md | 3 hits: Best Practices #9 (anti-retry), 401 troubleshooting entry, Troubleshooting anti-retry rule | Proves both remaining additions are present in the installed copy agents actually read (screenshot row moved to #2246) |
npx vitest run tests/skills.test.ts tests/skills-install.test.ts | 22/22 passed | Skill packaging/install tests cover the edited file's frontmatter and install path |
npx vitest run (full packages/cli suite) | 213/213 passed, 15 files | Supporting — proves no CLI breakage; this PR touches no TS |
npx prettier --check packages/cli/skills/browse/SKILL.md | "All matched files use Prettier code style!" | Formatting matches repo style |
🤖 Generated with Claude Code
Summary by cubic
Add a 401 troubleshooting playbook and an anti-retry rule to the bundled browse skill docs to prevent agent death-loops and reduce noisy telemetry. Addresses Linear STG-2274; docs-only change in packages/cli/skills/browse/SKILL.md.
- Docs
- 401 Unauthorized playbook for invalid
BROWSERBASE_API_KEY(fix the key, unset it, or use--local). - Anti-retry rule: never repeat an unchanged failing command. If it fails twice, stop, run
browse doctor --json, then change approach (fix key, switch--local/--remote, orbrowse stop --force). Init failures can be cached for a few seconds, so instant retries re-fail.
- 401 Unauthorized playbook for invalid