From 68994261871536ae4205d8cd00388d64f5e02c0a Mon Sep 17 00:00:00 2001
From: Oleks <oleks.kuksenko@gmail.com>
Date: Mon, 27 Jul 2026 21:50:19 +0300
Subject: [PATCH] docs: define 3 execution modes and decision matrix in
 SKILL.md and README.md

---
 README.md                          | 50 ++++++++++++++++++++++++++++++
 skills/browser-automation/SKILL.md | 23 ++++++++------
 2 files changed, 64 insertions(+), 9 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ebdeddf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+# Browser Plugin (`browser-plugin`)
+
+The `browser-plugin` provides real-time Chrome browser automation, tab inspection, accessibility auditing, DOM interaction, element screenshotting, and CDP trace performance profiling for Antigravity AI agents.
+
+---
+
+## Architecture & Integration Options
+
+### 1. Direct MCP Tool Calling (Fastest)
+
+Invoke browser tools directly from any active turn via `call_mcp_tool`:
+
+```json
+call_mcp_tool(
+  ServerName="browser-tools",
+  ToolName="chrome_read_page",
+  Arguments={"tabId": 863242845}
+)
+```
+
+- **Use when**: You need a quick DOM lookup, single screenshot, or single tab navigation while pair-programming.
+
+### 2. Skill-Guided Workflows (`browser-automation`)
+
+Activate the `browser-automation` skill in your turn for inline workflow guidance and DOM inspection strategies.
+
+- **Use when**: Performing multi-step browser interactions (form fills, visual regression checks, CDP trace analysis).
+
+### 3. Subagent Delegation (`browser:browser-agent` / `self`)
+
+Delegate long-running or multi-page browser exploration to a dedicated subagent via `invoke_subagent`:
+
+```json
+invoke_subagent(Subagents=[{
+  "TypeName": "browser:browser-agent",
+  "Role": "Browser Automation Agent",
+  "Prompt": "Inspect open tabs, navigate to target page, and report accessibility tree."
+}])
+```
+
+- **Use when**: Offloading heavy background web exploration, batch screenshot capture, or automated E2E testing without cluttering the main conversation window.
+
+---
+
+## Plugin Contents
+
+- **`plugin.json`**: Plugin manifest metadata.
+- **`.mcp.json`**: Endpoint definition (`http://127.0.0.1:12010/p/browser/mcp`).
+- **`agents/browser_agent.py`**: Agent builder for `browser:browser-agent`.
+- **`skills/browser-automation/SKILL.md`**: Skill documentation and decision matrix.
diff --git a/skills/browser-automation/SKILL.md b/skills/browser-automation/SKILL.md
index 2affe64..75c36cd 100644
--- a/skills/browser-automation/SKILL.md
+++ b/skills/browser-automation/SKILL.md
@@ -7,10 +7,22 @@ description: Real-time browser automation, tab inspection, accessibility auditin
 
 This skill provides full real-time control over the user's running Chrome browser instance through the **Browser MCP Server** (`http://127.0.0.1:12010/p/browser/mcp`).
 
-## Core Concepts & Tools
+---
+
+## 3 Modes of Execution: When to Use Which
+
+| Execution Option | Mechanism | When to Use | Key Advantages |
+| :--- | :--- | :--- | :--- |
+| **1. Direct MCP Tool Calls** | `call_mcp_tool(ServerName='browser-tools', ...)` | Quick DOM lookups, single element screenshots, checking tab URLs, or reading accessibility trees during active coding. | Fast, single-turn execution with zero context switching. |
+| **2. Skill-Guided Workflows** | Activate `browser-automation` skill in main session. | Guided multi-step tasks like form filling, visual regression auditing, or CDP performance tracing. | Detailed cheat-sheets, tab selector patterns, and DOM inspection strategies inline. |
+| **3. Subagent Delegation** | `invoke_subagent` with `browser:browser-agent` or `self`. | Heavy, multi-page background browser exploration, batch screenshot capturing, or automated E2E testing flows. | Keeps the main conversation context clean and focused on code while background worker handles browser state. |
+
+---
+
+## Tool Reference & Capabilities
 
 1. **Tab & Window Management**:
-   - `get_windows_and_tabs`: List all open browser windows, active tab ID, titles, and URLs.
+   - `get_windows_and_tabs`: List open browser windows, active tab ID, titles, and URLs.
    - `chrome_navigate`: Open a new URL or navigate an existing tab.
    - `chrome_switch_tab`: Switch focus to a specific tab ID.
    - `chrome_close_tabs`: Close one or more tabs.
@@ -28,10 +40,3 @@ This skill provides full real-time control over the user's running Chrome browse
 4. **Visual & Performance Auditing**:
    - `chrome_screenshot`: Capture full-page or element-specific PNG screenshots (`selector`, `name`, `fullPage`).
    - `performance_start_trace` / `performance_stop_trace`: Record and analyze CDP performance traces (LCP, CLS, long tasks).
-
-## Typical Workflow
-
-1. **Discover**: Call `get_windows_and_tabs` to identify open tabs.
-2. **Inspect**: Call `chrome_read_page` or `chrome_javascript` to inspect DOM state.
-3. **Interact**: Use `chrome_click_element`, `chrome_fill_or_select`, or `chrome_keyboard`.
-4. **Capture & Verify**: Use `chrome_screenshot` to verify visual layout and section placement.