feat(skills): rename "agent-browser" skill to "core"; make CLI-served main skill actually useful (#1253)

Before this change, the main skill served by the CLI (`agent-browser skills get agent-browser`) was a ~40-line discovery stub whose content was essentially "run `agent-browser skills get <name>` before doing anything." Agents already inside the CLI got no signal from it — the content they needed to actually use the tool lived only in the `--full` references. Split the two jobs apart: - **`skill-data/core/`** (new) — the runtime usage guide. 420-line `SKILL.md` covering the snapshot-and-ref loop, common workflows (login, extract, screenshot, multi-tab, sessions, iframes, dialogs), waiting strategies, element selection strategies, troubleshooting, and when to load a specialized skill. Supplementary `references/` and `templates/` (moved from `skills/agent-browser/`) provide the full command reference under `--full`. - **`skills/agent-browser/SKILL.md`** — still the discovery stub that `npx skills add` installs, now marked `hidden: true` so it stays out of `skills list` inside the CLI. Body is a clean pointer to `agent-browser skills get core` and the specialized skills. The `hidden: true` frontmatter flag is a new, general mechanism: skills marked hidden are omitted from `skills list` and `skills get --all` but can still be fetched by explicit name. This keeps the stub reachable for anyone who installed via `npx skills add` without polluting the CLI-side skill listing. ## Behavior ``` $ agent-browser skills list agentcore Run agent-browser on AWS Bedrock AgentCore cloud browsers... core Core agent-browser usage guide. Read this before running... dogfood Systematically explore and test a web application... electron Automate Electron desktop apps (VS Code, Slack, Discord...) slack Interact with Slack workspaces using browser automation... vercel-sandbox Run agent-browser + Chrome inside Vercel Sandbox microVMs... $ agent-browser skills get core # the actual usage guide # ~420 lines of workflows, patterns, troubleshooting $ agent-browser skills get agent-browser # still works if called explicitly # the thin stub, now pointing at `core` ``` External `npx skills add vercel-labs/agent-browser` behavior is unchanged: it finds and installs the thin `agent-browser` stub, which tells the agent to run `agent-browser skills get core` for real content. Version drift protection is preserved — the stub is the only thing that gets copied; the real content is always runtime-fetched. ## Updated - `cli/src/skills.rs` — `SkillInfo.hidden: bool`, parsed from frontmatter; `run_list` and `run_get --all` filter it. 3 new unit tests for the frontmatter parser. - `cli/src/output.rs` — top-level `--help` and `skills` subcommand help reference `skills get core` / `skills get core --full`. - `AGENTS.md` — "update these files for user-facing features" now points at `skill-data/core/` instead of the stub, with a note that the stub is not the right place for feature content. - `README.md`, `docs/src/app/skills/page.mdx` — describe the new split and `skills get core --full` as the recommended entry point. - `evals/cases/{command-usage,skill-selection}.ts` — expect `skills get core` in agent output instead of `skills get agent-browser`. Eval lib still reads `skills/agent-browser/SKILL.md` (simulating what an agent sees after `npx skills add`). All 11 skills unit tests pass. `cargo clippy -- -D warnings` and `cargo fmt --check` clean. Verified end-to-end: `skills list` shows `core` + specialized (no stub), `skills get core` returns the new content, `skills get agent-browser` still returns the stub on explicit request.
2026-04-16 14:36:59 -05:00
parent 1afcaa0e84
commit 4cc6ca40b7
19 changed files with 513 additions and 39 deletions
@@ -0,0 +1,193 @@
+# Session Management
+
+Multiple isolated browser sessions with state persistence and concurrent browsing.
+
+**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Named Sessions](#named-sessions)
+- [Session Isolation Properties](#session-isolation-properties)
+- [Session State Persistence](#session-state-persistence)
+- [Common Patterns](#common-patterns)
+- [Default Session](#default-session)
+- [Session Cleanup](#session-cleanup)
+- [Best Practices](#best-practices)
+
+## Named Sessions
+
+Use `--session` flag to isolate browser contexts:
+
+```bash
+# Session 1: Authentication flow
+agent-browser --session auth open https://app.example.com/login
+
+# Session 2: Public browsing (separate cookies, storage)
+agent-browser --session public open https://example.com
+
+# Commands are isolated by session
+agent-browser --session auth fill @e1 "user@example.com"
+agent-browser --session public get text body
+```
+
+## Session Isolation Properties
+
+Each session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Browsing history
+- Open tabs
+
+## Session State Persistence
+
+### Save Session State
+
+```bash
+# Save cookies, storage, and auth state
+agent-browser state save /path/to/auth-state.json
+```
+
+### Load Session State
+
+```bash
+# Restore saved state
+agent-browser state load /path/to/auth-state.json
+
+# Continue with authenticated session
+agent-browser open https://app.example.com/dashboard
+```
+
+### State File Contents
+
+```json
+{
+  "cookies": [...],
+  "localStorage": {...},
+  "sessionStorage": {...},
+  "origins": [...]
+}
+```
+
+## Common Patterns
+
+### Authenticated Session Reuse
+
+```bash
+#!/bin/bash
+# Save login state once, reuse many times
+
+STATE_FILE="/tmp/auth-state.json"
+
+# Check if we have saved state
+if [[ -f "$STATE_FILE" ]]; then
+    agent-browser state load "$STATE_FILE"
+    agent-browser open https://app.example.com/dashboard
+else
+    # Perform login
+    agent-browser open https://app.example.com/login
+    agent-browser snapshot -i
+    agent-browser fill @e1 "$USERNAME"
+    agent-browser fill @e2 "$PASSWORD"
+    agent-browser click @e3
+    agent-browser wait --load networkidle
+
+    # Save for future use
+    agent-browser state save "$STATE_FILE"
+fi
+```
+
+### Concurrent Scraping
+
+```bash
+#!/bin/bash
+# Scrape multiple sites concurrently
+
+# Start all sessions
+agent-browser --session site1 open https://site1.com &
+agent-browser --session site2 open https://site2.com &
+agent-browser --session site3 open https://site3.com &
+wait
+
+# Extract from each
+agent-browser --session site1 get text body > site1.txt
+agent-browser --session site2 get text body > site2.txt
+agent-browser --session site3 get text body > site3.txt
+
+# Cleanup
+agent-browser --session site1 close
+agent-browser --session site2 close
+agent-browser --session site3 close
+```
+
+### A/B Testing Sessions
+
+```bash
+# Test different user experiences
+agent-browser --session variant-a open "https://app.com?variant=a"
+agent-browser --session variant-b open "https://app.com?variant=b"
+
+# Compare
+agent-browser --session variant-a screenshot /tmp/variant-a.png
+agent-browser --session variant-b screenshot /tmp/variant-b.png
+```
+
+## Default Session
+
+When `--session` is omitted, commands use the default session:
+
+```bash
+# These use the same default session
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser close  # Closes default session
+```
+
+## Session Cleanup
+
+```bash
+# Close specific session
+agent-browser --session auth close
+
+# List active sessions
+agent-browser session list
+```
+
+## Best Practices
+
+### 1. Name Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+agent-browser --session github-auth open https://github.com
+agent-browser --session docs-scrape open https://docs.example.com
+
+# AVOID: Generic names
+agent-browser --session s1 open https://github.com
+```
+
+### 2. Always Clean Up
+
+```bash
+# Close sessions when done
+agent-browser --session auth close
+agent-browser --session scrape close
+```
+
+### 3. Handle State Files Securely
+
+```bash
+# Don't commit state files (contain auth tokens!)
+echo "*.auth-state.json" >> .gitignore
+
+# Delete after use
+rm /tmp/auth-state.json
+```
+
+### 4. Timeout Long Sessions
+
+```bash
+# Set timeout for automated scripts
+timeout 60 agent-browser --session long-task get text body
+```