---
name: qqbrowser-skill
description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, or automating any browser task.
source: https://pypi.org/project/qqbrowser-skill/
homepage: https://browser.qq.com/
permissions:
  - network: Required for browser navigation and web page interaction
  - filesystem: Required for downloading files and saving screenshots to temporary directories
---

# qqbrowser-skill

## Platform Support

- **Linux x86_64**: Supported
- **Windows**: Supported
- **macOS**: Supported
- Other Linux architectures (ARM, etc.) are not supported.

## Security

### Permissions

This skill requires the following permissions to function properly:

| Permission                   | Scope                      | Purpose                                                            |
| ---------------------------- | -------------------------- | ------------------------------------------------------------------ |
| **Network Access**           | Outbound HTTP/HTTPS        | Required for browser navigation, page loading, and web interaction |
| **File System (Read/Write)** | Temporary directories only | Required for saving screenshots (`.webp`) and downloaded files     |

### QQBrowser Binary

The `qqbrowser-skill install` command downloads the QQ Browser package from official Tencent distribution channels via HTTPS:

- **Base URL**: `https://dldir1v6.qq.com/invc/tt/QB/Public/`
- `dldir1v6.qq.com` is Tencent's official software distribution CDN.
- All downloads are performed over **HTTPS** to ensure transport-level security.

### File Storage

- **Screenshots**: Saved to the system's temporary directory (e.g., `/tmp/` on Linux) and returned as file paths.
- **Downloaded files**: Saved to the system's temporary directory or user-specified path via `browser_download_file` / `browser_download_url`.
- This skill does **not** access or modify files outside of its designated directories.

## Note:

Each command will return a snapshot of the current page after execution, including the encoded index of elements (format: `index_attrHash_xpathHash`, e.g. `2_sfli_qp0u`).
Please call the standalone qqbrowser-skill browser_snapshot command only when necessary to avoid unnecessary token consumption.

## ⚠️ MANDATORY: Task Recording Required

**EVERY browser automation task MUST be wrapped with `task_begin` and `task_end`.** This is NOT optional.

```bash
# ALWAYS start with task_begin BEFORE any browser commands
qqbrowser-skill task_begin --description "描述你要做的任务"

# ... your browser commands here ...

# ALWAYS end with task_end AFTER all browser commands are done
qqbrowser-skill task_end
```

**Rules:**

- `task_begin` MUST be the **first** command you execute (before `browser_go_to_url` or any other browser command)
- `task_end` MUST be the **last** command you execute (after the task is complete)
- There are NO exceptions to this rule — even for simple tasks like data extraction or page reading
- Failure to use `task_begin`/`task_end` means the task cannot be replayed or saved as a playbook later

## Core Workflow

Every browser automation follows this pattern:

1. **Record start**: `qqbrowser-skill task_begin --description "task description"`
2. **Navigate**: `qqbrowser-skill browser_go_to_url --url <url>`
3. **Snapshot**: `qqbrowser-skill browser_snapshot` (get indexed element refs)
4. **Interact**: Use element index to click, fill, select
5. **Re-snapshot**: After navigation or DOM changes, get fresh refs
6. **Record end**: `qqbrowser-skill task_end`

```bash
qqbrowser-skill task_begin --description "Fill out example form"
qqbrowser-skill browser_go_to_url --url https://example.com/form
qqbrowser-skill browser_snapshot
# Output includes element indices: [1_abc1_def2] input "email", [2_xyz3_uvw4] input "password", [3_klm5_nop6] button "Submit"

qqbrowser-skill browser_input_text --index 1_abc1_def2 --text "user@example.com"
qqbrowser-skill browser_input_text --index 2_xyz3_uvw4 --text "password123"
qqbrowser-skill browser_click_element --index 3_klm5_nop6
qqbrowser-skill browser_wait --seconds 2
qqbrowser-skill browser_snapshot  # Check result
qqbrowser-skill task_end
```

## Essential Commands

```bash
# Navigation
qqbrowser-skill browser_go_to_url --url <url>       # Navigate to URL
qqbrowser-skill browser_go_back                      # Go back
qqbrowser-skill browser_wait --seconds 3             # Wait for page load (default 3s)

# Snapshot & Screenshot
qqbrowser-skill browser_snapshot                     # Default mode: page content with element indices (for interaction)
qqbrowser-skill browser_snapshot --markdown          # Markdown mode: clean Markdown of the page (for reading/extraction, no indices)
qqbrowser-skill browser_screenshot                   # Take screenshot (returns temp file path of .webp image)
qqbrowser-skill browser_screenshot --full            # Full-page screenshot (returns temp file path)
qqbrowser-skill browser_screenshot --annotate        # Annotated screenshot with element labels (returns temp file path)

# Click & Input (use indices from snapshot, index is an encoded string like "2_sfli_qp0u")
qqbrowser-skill browser_click_element --index 2_sfli_qp0u      # Click element
qqbrowser-skill browser_dblclick_element --index 2_sfli_qp0u   # Double-click element
qqbrowser-skill browser_focus_element --index 2_sfli_qp0u      # Focus element
qqbrowser-skill browser_input_text --index 3_abc1_def2 --text "hello"  # Input text into element

# Scroll
qqbrowser-skill browser_scroll_down                  # Scroll down one page
qqbrowser-skill browser_scroll_down --amount 300     # Scroll down 300px
qqbrowser-skill browser_scroll_up                    # Scroll up one page
qqbrowser-skill browser_scroll_up --amount 300       # Scroll up 300px
qqbrowser-skill browser_scroll_to_text --text "Section 3"    # Scroll to text
qqbrowser-skill browser_scroll_to_top                # Scroll to top
qqbrowser-skill browser_scroll_to_bottom             # Scroll to bottom
qqbrowser-skill browser_scroll_by --direction down --pixels 500                          # Scroll page by direction
qqbrowser-skill browser_scroll_by --direction right --pixels 200 --index 3_klm5_nop6    # Scroll element by direction
qqbrowser-skill browser_scroll_into_view --index 5_xyz3_uvw4   # Scroll element into view

# Keyboard
qqbrowser-skill browser_keypress --key Enter         # Press a key
qqbrowser-skill browser_keyboard_op --action type --text "hello"        # Type text
qqbrowser-skill browser_keyboard_op --action inserttext --text "hello"  # Insert text without key events
qqbrowser-skill browser_keydown --key Shift          # Hold down a key
qqbrowser-skill browser_keyup --key Shift            # Release a key

# Dropdown
qqbrowser-skill browser_get_dropdown_options --index 2_abc1_def2           # Get dropdown options
qqbrowser-skill browser_select_dropdown_option --index 2_abc1_def2 --text "Option A"  # Select option

# Checkbox
qqbrowser-skill browser_check_op --index 4_klm5_nop6 --value               # Check checkbox
qqbrowser-skill browser_check_op --index 4_klm5_nop6 --no-value            # Uncheck checkbox

# Get Information
qqbrowser-skill browser_get_info --type text --index 1_abc1_def2   # Get element text
qqbrowser-skill browser_get_info --type url              # Get current URL
qqbrowser-skill browser_get_info --type title            # Get page title
qqbrowser-skill browser_get_info --type html --index 1_abc1_def2   # Get element HTML
qqbrowser-skill browser_get_info --type value --index 1_abc1_def2  # Get element value
qqbrowser-skill browser_get_info --type attr --index 1_abc1_def2 --attribute href   # Get attribute
qqbrowser-skill browser_get_info --type count            # Get element count
qqbrowser-skill browser_get_info --type box --index 1_abc1_def2    # Get bounding box
qqbrowser-skill browser_get_info --type styles --index 1_abc1_def2 # Get computed styles
qqbrowser-skill browser_check_state --state visible --index 1_abc1_def2    # Check visibility
qqbrowser-skill browser_check_state --state enabled --index 1_abc1_def2    # Check if enabled
qqbrowser-skill browser_check_state --state checked --index 1_abc1_def2    # Check if checked

# Find and Act (semantic locators)
qqbrowser-skill browser_find_and_act --by role --value button --action click --name "Submit"
qqbrowser-skill browser_find_and_act --by text --value "Sign In" --action click
qqbrowser-skill browser_find_and_act --by label --value "Email" --action fill --actionValue "user@test.com"
qqbrowser-skill browser_find_and_act --by placeholder --value "Search" --action type --actionValue "query"
qqbrowser-skill browser_find_and_act --by testid --value "submit-btn" --action click

# Download
qqbrowser-skill browser_download_file --index 5_xyz3_uvw4      # Download file by clicking element
qqbrowser-skill browser_download_url                 # Download from URL

# Tab Management
qqbrowser-skill browser_tab_open --url <url>         # Open URL in new tab
qqbrowser-skill browser_tab_list                     # List open tabs
qqbrowser-skill browser_tab_switch --tabId 2         # Switch to tab
qqbrowser-skill browser_tab_close --tabId 2          # Close tab

# Dialog
qqbrowser-skill browser_dialog --action accept       # Accept dialog
qqbrowser-skill browser_dialog --action dismiss      # Dismiss dialog
qqbrowser-skill browser_dialog --action accept --text "input text"  # Accept prompt with text

# JavaScript Evaluation
qqbrowser-skill browser_eval_content_js --script "document.title"                    # Evaluate JS and return result
qqbrowser-skill browser_eval_content_js --script "ZG9jdW1lbnQudGl0bGU=" --base64    # Evaluate base64-encoded JS script

# Replay (execute a recorded automation script)
qqbrowser-skill browser_replay --script /path/to/record.json                         # Replay from file
qqbrowser-skill browser_replay --script_content '{"version":"1.0",...}'              # Replay from JSON string
qqbrowser-skill browser_replay --script /path/to/record.json --variables '{"user":"test@example.com","pass":"123"}'  # With parameterized variables

# Task Completion
qqbrowser-skill browser_done --success --text "Task completed"      # Mark task as done
qqbrowser-skill browser_done --text "Still in progress"              # Mark task as incomplete

# Task Recording
qqbrowser-skill task_begin --description "description of what you are doing"   # Start recording commands
qqbrowser-skill task_end                                                        # Stop recording and save
qqbrowser-skill task_latest                                                     # Get the most recent task recording

# Help
qqbrowser-skill list                                 # List all available skills
qqbrowser-skill <skill_name> --help                  # Show help for a specific skill

# Skill Check
qqbrowser-skill status                               # Check skill status
```

## Common Patterns

### Form Submission

```bash
qqbrowser-skill browser_go_to_url --url https://example.com/signup
qqbrowser-skill browser_snapshot
qqbrowser-skill browser_input_text --index 1_abc1_def2 --text "Jane Doe"
qqbrowser-skill browser_input_text --index 2_xyz3_uvw4 --text "jane@example.com"
qqbrowser-skill browser_select_dropdown_option --index 3_klm5_nop6 --text "California"
qqbrowser-skill browser_check_op --index 4_pqr7_stu8 --value
qqbrowser-skill browser_click_element --index 5_vwx9_yza0
qqbrowser-skill browser_wait --seconds 2
qqbrowser-skill browser_snapshot  # Verify result
```

### Data Extraction

Choose the right `browser_snapshot` mode based on intent:

- **`browser_snapshot --markdown`** — preferred for **reading/summarizing** page content (articles, docs, search results, product pages). Returns clean Markdown with ads/nav/scripts stripped. Token-efficient, but contains **no element indices** — cannot be used to drive clicks or inputs.
- **`browser_snapshot`** (default) — required for **interacting** with the page. Returns indexed elements for use with `browser_click_element`, `browser_input_text`, etc.

```bash
qqbrowser-skill browser_go_to_url --url https://example.com/products
qqbrowser-skill browser_snapshot --markdown                # Read the whole page as clean markdown

# Use default snapshot + get_info when you need to interact or read a specific element
qqbrowser-skill browser_snapshot
qqbrowser-skill browser_get_info --type text --index 5_abc1_def2     # Get a specific element's text
```

### Infinite Scroll Pages

```bash
qqbrowser-skill browser_go_to_url --url https://example.com/feed
qqbrowser-skill browser_scroll_to_bottom     # Trigger lazy loading
qqbrowser-skill browser_wait --seconds 2     # Wait for content
qqbrowser-skill browser_snapshot             # Get updated content
```

## Element Index Lifecycle (Important)

Element indices are encoded strings (e.g. `2_sfli_qp0u`) that contain hash information for cross-snapshot matching. They are generated by each snapshot and may change when the page DOM changes. Always re-snapshot after:

- Clicking links or buttons that navigate
- Form submissions
- Dynamic content loading (dropdowns, modals, AJAX)

```bash
qqbrowser-skill browser_click_element --index 5_abc1_def2   # May navigate to new page
qqbrowser-skill browser_snapshot                             # MUST re-snapshot
qqbrowser-skill browser_click_element --index 1_xyz3_uvw4   # Use new indices
```

## Evaluation Report

See the full skill evaluation report: [QQBrowserSkillReport](https://bak.res.qq.com/nav/qqbrowser_skills/QQBrowserSkillReport.html)

## Task Recording (Important for AI Agents)

**IMPORTANT**: When using qqbrowser-skill to complete any automation task, you MUST wrap your commands with `task_begin` and `task_end`. This records all browser operations performed during the task, enabling replay and reuse later.

### Workflow

1. **Before starting any browser automation task**, call `task_begin` with a description of what you're about to do
2. Execute your browser commands as normal
3. **After completing the task**, call `task_end` to save the recording

### Commands

```bash
# Start recording — call this BEFORE any browser commands for the task
qqbrowser-skill task_begin --description "自动打开小红书并发布一篇笔记"

# ... execute browser commands normally ...
qqbrowser-skill browser_go_to_url --url https://www.xiaohongshu.com
qqbrowser-skill browser_snapshot
qqbrowser-skill browser_click_element --index 5_abc1_def2
# ... more commands ...

# Stop recording — call this AFTER all browser commands are done
qqbrowser-skill task_end

# Retrieve the most recent completed task recording
qqbrowser-skill task_latest
```

### Output

The recorded commands are saved as a JSON file in `~/.qqbrowser-skill/records/` directory. The output format is compatible with the `browser_replay` command, containing a `steps` array where each step has `action` and `params` fields.

### Notes

- `task_begin` and `task_end` do not interact with the browser — they only manage the recording state
- If `task_begin` is called while a previous recording is still active (not ended), the previous recording is discarded
- All browser skill commands executed between `task_begin` and `task_end` are automatically recorded
- The recorded file can be used as a reference for generating parameterized replay scripts
- Use `task_latest` to retrieve the content of the most recently completed recording (useful for reviewing or processing the recorded steps)

### Generating Replay Scripts / Playbooks

**CRITICAL**: When the user asks to "save as replay script", "generate playbook", "保存成回放脚本", "生成回放脚本", or any similar request to create a reusable automation script:

1. You **MUST** load and follow the `qqbrowser-playbook` skill instructions
2. You **MUST** use `task_latest` to get the recorded steps — do NOT fabricate steps
3. You **MUST** save the file to `~/.qqbrowser-skill/playbooks/<name>.json` (macOS/Linux) or `%LOCALAPPDATA%/qqbrowser-skill/playbooks/<name>.json` (Windows)
4. You **MUST** use the exact JSON format specified in the `qqbrowser-playbook` skill (with `metadata`, `params`, `settings`, `steps` structure)

**DO NOT**:

- Save to any other directory (e.g., `~/.qbotclaw/workspace/` or project directories)
- Use a flat/simplified JSON format — the format has specific nested structure requirements
- Skip loading the playbook skill — it contains the authoritative format specification
