browser-edge-cases
SOP for debugging browser automation failures on complex websites
Install / Use
npx skills add aden-hive/hive --skill browser-edge-casesInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Tags
Our assessment of browser-edge-cases
browser-edge-cases scores 93/100 on our quality scale, 642nd of 2,790 Automation skills we index (top 24%).
Its SKILL.md is 6.9 KB long, well organised into 28 sections with 15 code examples: a thorough specification that gives an agent plenty to work with.
With 11,072 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 browser-edge-cases is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. 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-26. Automated pattern scan on 2026-09-26. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
browser-edge-cases compared with similar skills
All 4 of these similar skills score higher than browser-edge-cases; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| browser-edge-cases (this skill)by aden-hive | 93 | 11.1k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install browser-edge-cases?
- Run
npx skills add aden-hive/hive --skill browser-edge-cases. The install tabs above show the steps for each supported agent. - Which AI agents does browser-edge-cases 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 browser-edge-cases 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 is Apache-2.0-licensed and scores 100/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 browser-edge-cases still maintained?
- The repository was last updated about 2 months ago, so browser-edge-cases is actively maintained.
Skill content
View source on GitHubname: browser-edge-cases description: SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM. license: MIT
Browser Tool Edge Cases
Standard Operating Procedure for debugging and fixing browser automation failures on complex websites.
When to Use This Skill
browser_interact(action="scroll")succeeds but page doesn't movebrowser_interact(action="left_click")succeeds but no action triggeredbrowser_interact(action="type")text disappears or doesn't workbrowser_snapshothangs or returns stale contentbrowser_navigateloads wrong content
SOP: Debugging Browser Tool Failures
Phase 1: Reproduce & Isolate
1. Create minimal test case demonstrating failure
2. Test against simple site (example.com) to verify tool works
3. Test against problematic site to confirm issue
Quick isolation test:
# Test 1: Does the tool work at all?
await browser_navigate(tab_id, "https://example.com")
result = await browser_interact(action="scroll", tab_id=tab_id, scroll_direction="down", scroll_amount=100)
# Should work on simple sites
# Test 2: Does it fail on the problematic site?
await browser_navigate(tab_id, "https://linkedin.com/feed")
result = await browser_interact(action="scroll", tab_id=tab_id, scroll_direction="down", scroll_amount=100)
# If this fails but example.com works → site-specific edge case
Phase 2: Analyze Root Cause
Step 2a: Check console for errors
console = await browser_console(tab_id)
# Look for: CSP violations, React errors, JavaScript exceptions
Step 2b: Inspect DOM structure
html = await browser_html(tab_id)
snapshot = await browser_snapshot(tab_id)
# Look for:
# - Nested scrollable divs (overflow: scroll/auto)
# - Shadow DOM roots
# - iframes
# - Custom widgets
Step 2c: Identify the pattern
| Symptom | Likely Cause | Check |
|---------|--------------|-------|
| Scroll doesn't move | Nested scroll container | Look for overflow: scroll divs |
| Click no effect | Element covered | Check getBoundingClientRect vs viewport |
| Type clears | Autocomplete/React | Check for event listeners on input; try a type action with no selector |
| Snapshot hangs | Huge DOM | Check node count in snapshot |
| Snapshot stale | SPA hydration | Wait after navigation |
Phase 3: Implement Multi-Layer Fix
Pattern: Always have fallbacks
async def robust_operation(tab_id):
# Method 1: Primary approach
try:
result = await primary_method(tab_id)
if verify_success(result):
return result
except Exception:
pass
# Method 2: CDP fallback
try:
result = await cdp_fallback(tab_id)
if verify_success(result):
return result
except Exception:
pass
# Method 3: JavaScript fallback
return await javascript_fallback(tab_id)
Pattern: Always add timeouts
# Bad - can hang forever
result = await browser_snapshot(tab_id)
# Good - fails fast with useful error
try:
result = await browser_snapshot(tab_id, timeout_s=10.0)
except asyncio.TimeoutError:
# Handle timeout gracefully
result = await fallback_snapshot(tab_id)
Phase 4: Verify Fix
1. Run against problematic site → should work
2. Run against simple site → should still work (regression check)
3. Document in registry.md
Pattern Library
P1: Nested Scrollable Containers
Sites: LinkedIn, Twitter/X, any SPA with scrollable feeds
Detection:
// Find largest scrollable container
const candidates = [];
document.querySelectorAll('*').forEach(el => {
const style = getComputedStyle(el);
if (style.overflow.includes('scroll') || style.overflow.includes('auto')) {
const rect = el.getBoundingClientRect();
if (rect.width > 100 && rect.height > 100) {
candidates.push({el, area: rect.width * rect.height});
}
}
});
candidates.sort((a, b) => b.area - a.area);
return candidates[0]?.el;
Fix: Dispatch scroll events at container's center, not viewport center.
P2: Element Covered by Overlay
Sites: Modals, tooltips, SPAs with loading overlays
Detection:
const rect = element.getBoundingClientRect();
const centerX = rect.left + rect.width / 2;
const centerY = rect.top + rect.height / 2;
const topElement = document.elementFromPoint(centerX, centerY);
return topElement === element || element.contains(topElement);
Fix: Wait for overlay to disappear, or use JavaScript click.
P3: React Synthetic Events
Sites: React SPAs, modern web apps
Detection: If CDP click doesn't trigger handler but manual click works.
Fix: Use JavaScript click as primary:
element.click();
P4: Huge DOM / Accessibility Tree
Sites: LinkedIn, Facebook, Twitter (feeds with 1000s of nodes)
Detection:
document.querySelectorAll('*').length > 5000
Fix:
- Add timeout to snapshot operation
- Truncate tree at 2000 nodes
- Fall back to DOM-based snapshot if accessibility tree too large
P5: SPA Hydration Delay
Sites: React, Vue, Angular SPAs after navigation
Detection:
// Check if React app has hydrated
document.querySelector('[data-reactroot]') ||
document.querySelector('[data-reactid]')
Fix: Wait for specific selector after navigation:
await browser_navigate(tab_id, url, wait_until="load")
await browser_interact(action="wait", tab_id=tab_id, wait_for_selector='[data-testid="content"]', timeout_ms=5000)
P6: Shadow DOM
Sites: Components using Shadow DOM, Lit elements
Detection:
document.querySelectorAll('*').some(el => el.shadowRoot)
Fix: Pierce shadow root:
function queryShadow(selector) {
const parts = selector.split('>>>');
let node = document;
for (const part of parts) {
if (node.shadowRoot) {
node = node.shadowRoot.querySelector(part.trim());
} else {
node = node.querySelector(part.trim());
}
}
return node;
}
Quick Reference
| Issue | Primary Fix | Fallback |
|-------|-------------|----------|
| Scroll not working | Find scrollable container | Mouse wheel at container center |
| Click no effect | JavaScript click() | CDP mouse events |
| Type clears | use_insert_text=False (per-keystroke) | Use a type action (Input.insertText) |
| Snapshot hangs | Add timeout_s | DOM snapshot fallback |
| Stale content | Wait for selector | Increase wait_until timeout |
| Shadow DOM | Pierce selector | JavaScript traversal |
References
- registry.md - Full list of known edge cases
- scripts/test_case.py - Template for testing new cases
- BROWSER_USE_PATTERNS.md - Implementation patterns from browser-use
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.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
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.
