mcpField
S
stagehand-expert

stagehand-expert

github.com/yuniorglezAgent workflows1438 installsUpdated 34w ago
Repository

About stagehand-expert

A skill for using Stagehand in browser automation and end-to-end testing. It covers natural-language actions, structured extraction, decision caching, and agent strategies for complex interfaces.

Key features

  1. 01Use Act, Observe, and Extract primitives
  2. 02Create Zod-validated structured extractions
  3. 03Cache decisions for deterministic CI tests
  4. 04Handle Shadow DOM and iframe interfaces
  5. 05Use visual CUA with safety callbacks

Use cases

  1. 01Building browser automation tests
  2. 02Extracting structured data from pages
  3. 03Running cached tests in CI
  4. 04Automating interfaces with complex frames or canvas

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/yuniorglez/gemini-elite-core --skill stagehand-expert

After installing, type/stagehand-expertin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
advanced-agent-caching.md
cdp-direct-communication.md
shadow-dom-iframe-mastery.md

Details

From the project README

🎭 Skill: Stagehand Expert (v4.1.0)

Executive Summary

The stagehand-expert is the elite specialist in browser automation and high-precision agent orchestration. In 2026, web automation has shifted from brittle selectors to Natural Language Primitives and Direct CDP Communication. This skill focuses on mastering Stagehand V3, leveraging Decision Caching for zero-cost CI/CD, and navigating complex Shadow DOM/iframe structures with 44% more velocity.

📋 Table of Contents

  1. Proactive Investigation Protocol
  2. The "Do Not" List (Anti-Patterns)
  3. Core Primitives (Act, Extract, Observe)
  4. Direct CDP & Performance
  5. Advanced Agent Caching
  6. Autonomous Agents (CUA)
  7. Reference Library

🔍 Proactive Investigation Protocol

Before writing a single test, the expert MUST perform a Deep Discovery:

  1. Route Mapping: identify the user flow from page.tsx or router configs.
  2. UI Component Audit: Read source code to find IDs, labels, and loading states.
  3. Vibe Check: Measure layout stability using the CDP "Vibe Score."
  4. Schema Inference: Analyze existing backend/DB types to create 100% compatible extract() Zod schemas.

🚫 The "Do Not" List (Anti-Patterns)

Anti-PatternWhy it fails in 2026Modern Alternative
Manual Frame SwitchingFragile and slow.Use DeepLocator (>>) & CDP.
Hardcoded Wait(2000)Unreliable and causes jank.Use domSettleTimeout.
Missing finally { close() }Leaves zombie processes.Mandatory try...finally.
LLM Calls in CISlow and expensive.Use Persistent Decision Caches.
Ignoring CSS AnimationsInteractions fail during transitions.Use Reanimated-aware Waiters.

⚡ Core Primitives Mastery

  • Act: Precise natural language instructions with mapped variables.
  • Observe: Single-turn identification of all page elements for 70% cost reduction.
  • Extract: Structured, Zod-validated data pulling with semantic flattening.

💾 Advanced Decision Caching

Transform E2E tests into a deterministic asset:

  • Develop Locally: Live LLM generates the cache.
  • Commit Cache: Store DOM snapshots and results in Git.
  • Zero-Cost CI: Run tests in "Cached-Only" mode.

See References: Agent Caching for details.

🤖 Autonomous Agents & CUA

For the most complex UIs (Cross-origin iframes, dynamic canvas):

  • Computer Use Agent (CUA): Pure visual reasoning for impossible-to-parse elements.
  • Safety Callbacks: Mandatory human-in-the-loop for financial or destructive actions.

📖 Reference Library

Detailed deep-dives into Stagehand Excellence:

Updated: January 22, 2026 - 21:20

Comments

Markdown supported