chore: prompt compress skills and tool definition

[andyMrtnzP]

Makes skills and agent tool definition more token-effective

Summary by CodeRabbit

• Documentation
  • Reorganized and clarified guidance for captcha solving, cookie consent handling, dynamic content waiting, modal interactions, and tab management with improved subsections and examples.
  • Enhanced shadow DOM selector documentation and snapshot behavior explanations with better formatting and actionable steps.
  • Streamlined agent tool descriptions for improved clarity and consistency across all skill guides.

[coderabbitai]

Walkthrough

This PR restructures skill guidance documentation across eight markdown files and updates the agent tool description. Changes consolidate and clarify instructions for handling captcha solving, interactive UI patterns (modals, consent banners, shadow DOM), screenshots and snapshot misses, dynamic content waits, and tab management—without modifying executable logic or public APIs.

Changes

Skill Documentation and Agent Tool Updates

Layer / File(s)	Summary
Captcha and Bot-Challenge Handling src/skills/captchas.md	Emphasized solve command for captcha/bot-challenge pages with condensed "EXPERIMENTAL — Cloud-only" note and restructured documentation: dedicated params section (with type, wait, timeout), Response outcomes, numbered recipe steps, escalation guidance, and explicit "Don't" prohibitions against click-based checkbox interaction and evaluate-based token injection.
Interactive UI Element Patterns src/skills/modals.md, src/skills/cookie-consent.md, src/skills/shadow-dom.md	Modals: snapshot-driven workflow with role: dialog/alertdialog detection and ordered closing checklist (close control, aria-labeled button, Escape key, backdrop). Cookie-consent: condensed recipe with banner-first rule, shadow-DOM deep-selector fallback to attribute-based approach, updated "Don't" section. Shadow-DOM: streamlined < prefix format, iframe selector construction examples, and recovery steps for selector failures.
Screenshot and Snapshot Handling src/skills/screenshots.md, src/skills/snapshot-misses.md	Screenshots: new comparison table vs. snapshots, scope ordering (smallest to largest), format recommendations, "capture-after-action" pattern, and "Avoid" bullets listing OCR/multi-screenshot anti-patterns. Snapshot-misses: clarified recipe steps, icon-only button extraction, image alt-attribute handling, long-list pagination guidance, and "Don't" bullets on maxElements and evaluate usage.
Dynamic Content and Async Patterns src/skills/dynamic-content.md	Condensed decision tree for wait* methods with tightened examples, new "When timeout occurs" section with re-snapshot/selector-widening/fallback strategies, "Avoid" bullets replacing previous longer guidance, and minor heading adjustments for form redirects and lazy modals.
Tab Management and Multi-Target Handling src/skills/tabs.md	Clarified that snapshots provide tabs[]/activeTargetId state, updated when getTabs is unnecessary, refined closing/background-tab patterns with activeTargetId handling, and consolidated tab error-code and command do/don't rules.
Agent Tool Description Update src/tools/agent.ts	Updated TOOL_DESCRIPTION string constant to reflect consolidated instructions for proxy options, skill auto-injection, ReAct loop, snapshot/selector/tab rules, batching/async behavior, and error recovery—aligning with restructured skill guidance across all documents.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• browserless/browserless-mcp#47: Updates captcha handling documentation and agent tool description to reflect new solve command flow for bot challenges.
• browserless/browserless-mcp#46: Refines tab management documentation and agent tool instructions around snapshot-provided tab state and multi-target behavior.
• browserless/browserless-mcp#61: Documents proxy configuration in agent tool description; this PR aligns the tool description with that documented proxy behavior.

Suggested reviewers

• ashwinsingh2007
• artiom

Poem

🐰 A doc-weaving quest, bright and clear,
Skill guides now gleam without a sneer,
Modals and shadows, captchas with care—
The agent tool knows the paths to prepare. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is extremely brief ('Makes skills and agent tool definition more token-effective') and omits most required template sections including Related issues, Changes, Test plan, and Checklist.	Complete the PR description by adding Related issues (if applicable), a Changes section listing notable edits, Test plan (mark 'N/A — docs / chore / refactor only' if appropriate), and Checklist items.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'chore: prompt compress skills and tool definition' directly summarizes the main changes in the PR: consolidating and optimizing prompts/documentation for skills and agent tool definitions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/prompt-compress-skills

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/skills/shadow-dom.md`:
- Around line 5-11: Update the markdown to fix MD040/MD038: change the untyped
fenced block to include a language (e.g., replace the triple backtick block with
```text around the example `< *url-pattern* css-selector`) and normalize inline
code spans that contain a literal space by rewriting them to avoid spaces inside
a single code span (e.g., replace inline snippets like `deep-ref=< button#deny`,
`deep-ref=<`, and similar occurrences in the "Deep selectors: `< ` prefix"
section with human-readable concatenation forms such as backticked `<` followed
by " + space" or use two adjacent code spans like `<` and ` ` where appropriate)
so the code fence has a language and no inline code span contains an internal
space.

In `@src/tools/agent.ts`:
- Around line 672-675: The docs currently list proxy examples as if fields like
proxyCountry/proxySticky are top-level; clarify that these belong under the
proxy object by updating the text around the proxy examples (the lines
describing proxy: "residential", proxyCountry, proxyState, proxyCity,
proxySticky, proxyLocaleMatch, proxyPreset, externalProxyServer) to show the
correct shape and include an explicit JSON example such as { "proxy": { ... } }
so callers using the agent creation code (where the schema expects a proxy
object) won't send top-level fields and trigger INVALID_PARAMS.
- Around line 766-767: Update the documentation comment for the "close" command
so it no longer says "own call, NOT batched"; change it to state that "close"
may be included in batched commands and that the runtime will handle "close"
specially when present in a batch (so agents can include it in grouped actions).
Ensure the new wording replaces the existing line referencing "close" and
clarifies that batching "close" is supported by the runtime's batch handler.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e6237581-2ecb-4bd0-b2f5-e53ed0fb5d08

📥 Commits

Reviewing files that changed from the base of the PR and between f9ccc45 and ab3d796.

📒 Files selected for processing (9)

• src/skills/captchas.md
• src/skills/cookie-consent.md
• src/skills/dynamic-content.md
• src/skills/modals.md
• src/skills/screenshots.md
• src/skills/shadow-dom.md
• src/skills/snapshot-misses.md
• src/skills/tabs.md
• src/tools/agent.ts