skills.rest
browserbase
browserbaseOFFICIAL
Explore all skills by this author →
Website𝕏@browserbaseGitHub

optimize-agent-prompt

Optimizes Browserbase Agent system prompts through iterative traced runs and scoring.

3.7k|237|Updated Oct 12, 2025
Search Tags:#prompt optimization#system prompt#evaluation#Browser Automation#Browserbase#experiment harness#agent api
One-click install
npx skills add https://github.com/browserbase/skills --skill optimize-agent-prompt
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: optimize-agent-prompt
Source: https://github.com/browserbase/skills/tree/main/skills/optimize-agent-prompt
Command: npx skills add https://github.com/browserbase/skills --skill optimize-agent-prompt

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Writing an effective system prompt for a Browserbase Agent is guesswork: runs fail, loop, or return wrong data, and there is no systematic way to know which prompt change fixed what. This Skill turns prompt tuning into a controlled experiment by holding the task, result schema, and evaluation criteria fixed while iterating one prompt heuristic at a time.

Core Features & Use Cases

  • Experiment Harness: A Node.js CLI creates an isolated workspace, runs a fixed task against the Browserbase Agents API, and saves the system prompt, run status, messages, session logs, and a scored summary per iteration.
  • Trace-Based Diagnosis: Inspect ordered tool calls and tool results from Agent messages, plus CDP session logs, to find the first consequential failure before editing the prompt.
  • Scoring and Convergence: A built-in scorer combines required-field coverage, known-fact regex checks, factuality warnings, and terminal status, and a report command compares all runs so a winning prompt is confirmed with an unchanged rerun.
  • Use Case: A POC Agent keeps looping after a protected site returns 403. Run the baseline, inspect the trace, add a retry-cap heuristic to the prompt, rerun, and confirm the improved score with an unchanged confirmation run.

Quick Start

Ask the agent to set up an optimize-agent-prompt experiment workspace for your Browserbase Agent task, run the baseline prompt, and iterate on the system prompt until it converges.

Frequently Asked Questions about optimize-agent-prompt

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I optimize a Browserbase Agent system prompt?▼

Create an experiment workspace with the init command, define a fixed task and result schema in task.json, then run each prompt version with the run command. Inspect the trace, change one heuristic per iteration, and use the report command to compare scores until a prompt passes an unchanged confirmation run.

How do I diagnose why a Browserbase Agent run failed or looped?▼

Use the inspect command to list ordered tool calls and tool results from the run's messages and find the first consequential failure. Check session-logs.json for browser-level evidence like redirects, 403s, or failed requests only when browser behavior could explain the cause.

What are the requirements to run the prompt optimization harness?▼

You need Node.js 18 or later and the BROWSERBASE_API_KEY environment variable set. The harness script uses only Node.js built-in modules, so no npm packages need to be installed.

How is each Agent run scored during prompt optimization?▼

The scorer combines required-field coverage from the JSON Schema, case-insensitive known-fact regex checks, factuality-warning patterns, and whether the run reached COMPLETED status. Warnings subtract points, so a fast but wrong or unsafe run scores lower than a correct one.

When can I consider a Browserbase Agent prompt converged?▼

Converge only after the prompt passes at least two of the last three runs and one pass is an unchanged confirmation run. Do not claim the prompt is globally optimal from one task; describe it as the best prompt for the tested task distribution.

Can the harness stop a Browserbase Agent run that is spiraling?▼

Yes. The run command enforces a message budget and timeout, and calls the stop endpoint when limits are exceeded. It keeps polling until a terminal status so final artifacts like messages and summaries remain complete.

Related Skills

Explore More Software Engineering Skills→
browserbasebrowserbase
3.7k

autobrowse

Automate browser navigation and interaction using Claude Code and the Browse CLI.

Official
Advanced
skaile-aiskaile-ai

devlog

Record meaningful changes as devlog entries and update the DEVLOG.md index.

Official
Intermediate
mortenbroesbymortenbroesby
1

browser-testing-with-devtools

Automate browser verification using live DevTools runtime evidence.

Community
Intermediate
Soham407Soham407
1

zoom-out

Map relevant modules and callers using domain glossary vocabulary.

Community
Basic