optimize-agent-prompt
Builds and improves Browserbase Agent API demos through an Autobrowse-style outer loop: run a fixed task, collect Agent messages and session logs, score the result, revise one system-prompt heuristic, and confirm convergence
Install / Use
npx skills add browserbase/skills --skill optimize-agent-promptInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Education & ResearchSupported Platforms
Our assessment of optimize-agent-prompt
optimize-agent-prompt scores 89/100 on our quality scale, 182nd of 421 Education & Research skills we index (top 44%).
Its SKILL.md is 5.4 KB long, split into 7 sections with 5 code examples: a solid amount of guidance for an agent.
With 3,731 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so optimize-agent-prompt is actively maintained.
- Our last check on 2026-10-31 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
optimize-agent-prompt compared with similar skills
All 4 of these similar skills score higher than optimize-agent-prompt; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| optimize-agent-prompt (this skill)by browserbase | 89 | 3.7k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| last30days-skillby mvanhorn | 100 | 68.0k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install optimize-agent-prompt?
- Run
npx skills add browserbase/skills --skill optimize-agent-prompt. The install tabs above show the steps for each supported agent. - Which AI agents does optimize-agent-prompt work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is optimize-agent-prompt safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is optimize-agent-prompt still maintained?
- The repository was last updated about 2 months ago, so optimize-agent-prompt is actively maintained.
Skill content
View source on GitHubname: optimize-agent-prompt description: "Builds and improves Browserbase Agent API demos through an Autobrowse-style outer loop: run a fixed task, collect Agent messages and session logs, score the result, revise one system-prompt heuristic, and confirm convergence. Use when creating a Browserbase Agents demo or POC, optimizing an Agent system prompt, diagnosing flaky Agent runs, or applying auto-research/autobrowse to the Browserbase Agents API." license: MIT allowed-tools: Bash Read Write Edit Grep Glob
Optimize Agent Prompt
Optimize a Browserbase Agent's systemPrompt while holding its task, result schema, variables, and evaluation criteria fixed. Treat the outer agent as the teacher and each Browserbase Agent run as an inner-agent rollout.
Use Node.js 18 or later and set BROWSERBASE_API_KEY. The harness uses only Node.js built-in modules.
Set up the experiment
Choose a short experiment name and create an isolated workspace inside the demo or POC repository:
node <skill-dir>/scripts/optimize_agent_prompt.mjs init \
--workspace ./agent-prompt-optimization/<experiment-name> \
--name <experiment-name>
Edit the generated files:
task.json: keeptask,resultSchema, variables, browser settings, and evaluation oracle stable across iterations.prompts/iteration-001.md: write the minimal baseline system prompt. Include irreversible-action guardrails when applicable.
Use concrete success criteria. Prefer a strict JSON Schema with required fields and null for unavailable facts. Add known-field regexes and factuality-warning regexes under evaluation when a truth oracle exists. Read references/evaluation.md when designing the task or score.
Run the baseline
node <skill-dir>/scripts/optimize_agent_prompt.mjs run \
--workspace ./agent-prompt-optimization/<experiment-name> \
--prompt prompts/iteration-001.md \
--label iteration-001
The harness creates one reusable Browserbase Agent, updates its systemPrompt on later iterations, starts the run, polls messages and status, and writes:
runs/<label>/
├── system-prompt.md
├── created-run.json
├── run.json
├── messages.json
├── session-logs.json
└── summary.json
It stops a run after the configured message budget instead of paying for an unproductive spiral. Use --max-messages, --timeout-ms, --proxies, or --verified only when the task needs different values from task.json.
Diagnose from observable evidence
Start with the compact trajectory:
node <skill-dir>/scripts/optimize_agent_prompt.mjs inspect \
--workspace ./agent-prompt-optimization/<experiment-name> \
--label iteration-001
Then read summary.json and drill into messages.json at the first wrong or wasted turn. Agent messages expose ordered tool calls, tool results, errors, and final output. A reasoning part may contain no readable text; never require hidden chain-of-thought for the teacher loop.
Read session-logs.json only when browser-level evidence can distinguish the cause—for example, a redirect, 403, failed request, console error, or hidden endpoint. Empty session logs can mean the Agent completed with search/fetch tools and never drove its browser.
See references/api.md for endpoint shapes, pagination, result normalization, and trace caveats.
Improve one heuristic
Find the earliest consequential failure and state one counterfactual:
If the system prompt had instructed X, the Agent would have avoided Y, as shown by tool result Z.
Copy the current prompt to prompts/iteration-NNN.md and make one attributable change. Typical improvements are:
- cap retries after a repeated block or identical error;
- distinguish public identifiers from private/internal IDs;
- prefer search/fetch before launching a browser when interaction is unnecessary;
- separate current snapshots from dated historical events;
- define when a qualified fallback counts as completed;
- require
nullinstead of guessed values; - add a tool-call or evidence budget.
Keep wins. If the new run regresses, restore the previous prompt and test a different hypothesis rather than stacking more rules.
Judge and converge
Generate the comparison table after each run:
node <skill-dir>/scripts/optimize_agent_prompt.mjs report \
--workspace ./agent-prompt-optimization/<experiment-name>
Judge more than field completeness. Require:
- terminal status
COMPLETED; - required fields populated or explicitly nullable;
- known-fact checks passing when available;
- no factuality-warning match;
- provenance and safety constraints preserved;
- fewer messages or lower duration without quality loss.
Once a prompt wins, run it again unchanged with a new label. Converge only after it passes at least two of the last three runs and one pass is an unchanged confirmation. Do not call a prompt globally optimal from one task; describe it as the best prompt for the tested task distribution.
Graduate into the demo
Use the confirmed prompt as the Agent's production systemPrompt. Keep the strict result schema and per-run variables. Preserve the experiment workspace or its report so reviewers can audit why each instruction exists.
In the final handoff, report:
- baseline versus winning score, duration, and message count;
- the first wrong turn each prompt change fixed;
- whether session logs added evidence;
- the winning prompt path;
- confirmation-run results;
- limitations and the next holdout matrix.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
last30days-skill
68.0kAI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
