# Stagehand Expert

> Master Architect in Stagehand V3. Expert in Direct CDP Automation, Decision Caching, and Agentic Web Orchestration for 2026.

- Skill: `yuniorglez/stagehand-expert` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add yuniorglez/stagehand-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuniorglez/stagehand-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yuniorglez (https://skillmd.com/u/yuniorglez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuniorglez/stagehand-expert

---


# 🎭 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](#proactive-investigation-protocol)
2. [The "Do Not" List (Anti-Patterns)](#the-do-not-list-anti-patterns)
3. [Core Primitives (Act, Extract, Observe)](#core-primitives-act-extract-observe)
4. [Direct CDP & Performance](#direct-cdp--performance)
5. [Advanced Agent Caching](#advanced-agent-caching)
6. [Autonomous Agents (CUA)](#autonomous-agents-cua)
7. [Reference Library](#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-Pattern | Why it fails in 2026 | Modern Alternative |
| :--- | :--- | :--- |
| **Manual Frame Switching** | Fragile 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 CI** | Slow and expensive. | Use **Persistent Decision Caches**. |
| **Ignoring CSS Animations** | Interactions 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](./references/advanced-agent-caching.md) 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:

- [**Direct CDP Communication**](./references/cdp-direct-communication.md): Velocity and deep access.
- [**Agent Caching**](./references/advanced-agent-caching.md): Determinism and cost savings.
- [**Shadow DOM Mastery**](./references/shadow-dom-iframe-mastery.md): Jumping документ boundaries.
- [**Installation & Setup**](./references/setup-guide-v3.md): The Bun/Playwright stack.

---

*Updated: January 22, 2026 - 21:20*