browser-act

---
name: youtube-transcript-analysis-api-skill
description: "This skill helps users extract YouTube video transcripts and perform deep competitive analysis on the content. Agent should proactively apply this skill when users express needs like analyze YouTube video content strategy, perform competitive video content analysis, extract and analyze YouTube subtitles for marketing insights, understand competitor value propositions from their videos, identify target audience from YouTube video content, analyze pain points and needs mentioned in YouTube videos, evaluate competitor CTA strategies in video content, find content gaps in competitor YouTube videos, analyze video narrative structure and hooks, extract key messaging and positioning from YouTube content, benchmark competitor video content quality, research competitor marketing angles through video analysis, identify audience signals and terminology level in videos, analyze emotional tone and persuasion techniques in YouTube content."
metadata: {"openclaw":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# YouTube Transcript Analysis API Skill

## 📖 Brief
This skill provides an end-to-end YouTube video transcript extraction and deep content analysis service. By extracting video transcripts and then systematically analyzing them, users can understand competitors' core value propositions, target audience profiles, pain point strategies, and content gaps — all without manually watching hours of video.

**This skill works in two phases:**
1. **Phase 1 — Transcript Extraction**: Uses BrowserAct API to extract raw transcript data (supports single video and batch modes).
2. **Phase 2 — Deep Analysis**: The Agent performs structured 8-dimension analysis on the extracted transcripts.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-set workflows avoid AI generative hallucinations, ensuring stable and precise data extraction.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP restrictions or geo-blocking**: No need to handle regional IP restrictions or geofencing.
4. **Faster execution**: Tasks execute faster compared to pure AI-driven browser automation solutions.
5. **Extremely high cost-efficiency**: Significantly lowers data acquisition costs compared to high-token-consuming AI solutions.

## 🔑 API Key Guide
Before running, check the `BROWSERACT_API_KEY` environment variable. If not set, do not take other measures; ask and wait for the user to provide it.
**Agent must inform the user**:
> "Since you haven't configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key."

## 🛠️ Input Parameters
The Agent should determine the extraction mode based on the user's needs:

### Mode A: Single Video Analysis
Use when the user provides a specific YouTube video URL.

1. **TargetURL**
   - **Type**: `string`
   - **Description**: The URL of the YouTube video to extract and analyze.
   - **Example**: `https://www.youtube.com/watch?v=st534T7-mdE`
   - **Required**: Yes

### Mode B: Batch Video Analysis
Use when the user wants to search and analyze multiple videos by keyword.

1. **KeyWords**
   - **Type**: `string`
   - **Description**: The keyword to search for on YouTube.
   - **Example**: `AI Automation`, `SaaS Marketing`
   - **Required**: Yes

2. **Upload_date**
   - **Type**: `string`
   - **Description**: Filter for the upload date of the videos.
   - **Example**: `This week`
   - **Default**: `This week`

3. **Datelimit**
   - **Type**: `number`
   - **Description**: The number of videos to extract and analyze.
   - **Example**: `3`
   - **Default**: `3`

### Optional Analysis Parameters
These parameters are set by the user's intent, not script arguments:

4. **Analysis Language**
   - **Type**: `string`
   - **Description**: The language the analysis report should be written in. Defaults to the same language as the user's request.
   - **Example**: `Chinese`, `English`

5. **Analysis Focus**
   - **Type**: `string`
   - **Description**: The user may specify an analysis focus. The Agent must dynamically adjust the depth of specific dimensions based on this focus. For example:
     - *Competitor Analysis* -> Deep dive into Dim 7 (Business Model) and Dim 8 (Gaps).
     - *Viral Deconstruction* -> Deep dive into Dim 1 (Hook), Dim 4 (Emotional Arc), and Dim 5 (Viral Drivers).
     - *Audience Research* -> Deep dive into Dim 3 (Persona & Intent) and Dim 4 (Pain Points).
   - **Default**: All 8 dimensions balanced.
   - **Example**: `Competitor Analysis`, `Viral Deconstruction`, `Audience Research`

## 🚀 Invocation Method
The Agent should execute the unified extraction script based on the mode:

**Mode A — Single Video:**
```bash
python -u ./scripts/youtube_transcript_analysis_api.py single "TargetURL"
```

**Mode B — Batch Videos:**
```bash
python -u ./scripts/youtube_transcript_analysis_api.py batch "keywords" "Upload_date" Datelimit
```

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take several minutes. The script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`).
**Agent guidelines**:
- While waiting for the script to return results, keep monitoring the terminal output.
- As long as the terminal continues to output new status logs, the task is running normally. Do not misjudge it as deadlocked.
- Only consider triggering the retry mechanism if the status remains unchanged for a long time or the script stops outputting without returning a result.

### Post-Extraction Workflow
After the script completes and returns transcript data, the Agent must proceed with two additional steps:

**Step 1: Present Video Metadata** — Display the extracted metadata to the user. *(Note: Do NOT output the full raw transcript text in your response, as it is too long. Use it internally for your analysis.)*

**Step 2: Perform Concise 8-Dimension Analysis** — Analyze the transcript across the 8 dimensions. ⚠️ **CRITICAL: The analysis MUST be extremely concise, bullet-point driven, and free of filler words.** Directly state the facts, evidence, and actionable insights without verbose explanations. Use the same language as the user's request.

## 📊 Data Output
After successful execution, the output includes two parts:

### Part 1: Video Metadata
The script returns the following fields for each video:
- `video_title`: The title of the YouTube video
- `video_url`: The direct link to the original video
- `publisher`: The name of the channel publishing the video
- `channel_link`: The URL of the publisher's YouTube channel
- `video_likes_count`: The number of likes the video has received
- `transcript`: The complete extracted transcript/subtitles of the video (used internally for analysis, do not display full text)

### Part 2: 8-Dimension Analysis
After presenting raw data, the Agent must produce structured analysis on the transcript content across the following 8 dimensions:

#### Dimension 1: Content Structure & Hook
Analyze the video's narrative architecture:
- **Opening Hook**: What is the core hook in the first 30 seconds? Quote it and explain the hook logic (e.g., curiosity gap, bold claim).
- **Narrative Framework**: Identify the overall structure (e.g., Problem-Agitate-Solve, Hero's Journey, Listicle).
- **Pacing & Time Allocation**: Proportion of intro vs. core content vs. pitch/CTA.

#### Dimension 2: Core Messaging
Extract the central message:
- **Single Core Viewpoint**: What is the ONE key thesis the video conveys?
- **Supporting Arguments**: How is the viewpoint supported? (Data, analogies, personal experience).
- **Conclusion Clarity**: Is the conclusion clear and memorable?

#### Dimension 3: Audience Persona & Intent
Identify the intended viewer and their mindset:
- **Target Viewer Profile & Level**: Who is this for? (Beginner, Expert) What prior knowledge is assumed?
- **Viewer Intent**: Why are they watching? (To learn a skill, be entertained, make a buying decision, or validate existing beliefs?)

#### Dimension 4: Pain Points & Emotional Arc
Map the emotional journey and problems addressed:
- **Explicit & Implicit Pain Points**: What specific problems are stated or implied? Quote exact words.
- **Emotional Arc**: How does the content shift the viewer's emotion? (e.g., from anxiety/confusion to clarity/relief/empowerment). This emotional shift drives retention and sharing.

#### Dimension 5: Viral & Engagement Drivers
Analyze the spreading mechanism:
- **Shareability Factors**: Why is this video shared? (Controversial takes, highly relatable scenarios, title/thumbnail alignment inferred from script).
- **Memorable/Quotable Phrasing**: Extract unique expressions, catchy concepts, or "aha" moments that stick in the mind.

#### Dimension 6: Evidence & Credibility
Evaluate trust-building elements:
- **Authority Signals**: Data cited, expert references, or professional background mentioned.
- **Social Proof & Empathy**: Real user stories, case studies, or the creator sharing their own past struggles to build rapport.

#### Dimension 7: Business Model & Conversion
Deconstruct the monetization and CTA strategy:
- **Primary Monetization Goal**: What is the underlying business purpose? (Ad revenue, selling a course, affiliate marketing, brand sponsorship, lead generation).
- **CTA Strategy**: What actions are requested? How is urgency or value constructed to drive this action?

#### Dimension 8: Categorized Content Gaps
Identify strategic opportunities by splitting gaps into three layers:
- **Creator's Weaknesses**: Arguments that lack evidence, logical flaws, or poorly explained concepts.
- **Unresolved Viewer Questions**: What specific questions would the audience still have after watching?
- **Industry Whitespace**: What related angles or broader perspectives did the video entirely miss that you could cover?

### Output Format

**For Single Video Analysis:**
```
## Video Metadata
[Present video metadata. DO NOT print full transcript]

## Concise Deep Analysis
*(Output in extremely brief bullet points, max 1-2 short sentences per point)*

### 1. Content Structure & Hook
[Concise bullets]

### 2. Core Messaging
[Concise bullets]

### 3. Audience Persona & Intent
[Concise bullets]

### 4. Pain Points & Emotional Arc
[Concise bullets]

### 5. Viral & Engagement Drivers
[Concise bullets]

### 6. Evidence & Credibility
[Concise bullets]

### 7. Business Model & Conversion
[Concise bullets]

### 8. Categorized Content Gaps
[Concise bullets]

### Key Takeaways
[3 short, actionable strategic insights]
```

**For Batch Video Analysis:**
```
## Video Metadata
[Present all video metadata. DO NOT print full transcripts]

## Concise Individual Analysis
[Repeat the concise 8-dimension analysis for EACH video using brief bullet points]

## Cross-Video Comparative Analysis
[After analyzing all videos individually, provide a comparative summary]:
- Common value propositions: What themes appear across multiple videos?
- Shared target audience: Is there a consistent audience profile?
- Recurring pain points: Which problems are mentioned most frequently?
- Dominant content strategies: What narrative structures and CTA patterns are most common?
- Competitive differentiation: How do different creators/brands position themselves differently?
- Industry content gaps: What topics are consistently missing across all analyzed videos?
```

## ⚠️ Error Handling & Retry
If an error occurs during script execution (e.g., network fluctuations or task failure), the Agent should follow this logic:

1. **Check Output Content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. **Do not retry**; guide the user to re-check and provide the correct API Key.
   - If the output **contains** `"concurrent"` or `"too many running tasks"` or similar concurrency limit messages, it means the current subscription plan's concurrent task limit has been reached. **Do not retry**; guide the user to upgrade their plan.
     **Agent must inform the user**:
     > "The current task cannot be executed because your BrowserAct account has reached the limit of concurrent tasks. Please go to the [BrowserAct Plan Upgrade Page](https://www.browseract.com/reception/recharge) to upgrade your subscription plan and enjoy more concurrent task benefits."
   - If the output **does not contain** the above error keywords but the task failed (e.g., output starts with `Error:` or returns empty results), the Agent should **automatically try to re-execute the script once**.

2. **Retry Limit**:
   - Automatic retry is limited to **one time**. If the second attempt fails, stop retrying and report the specific error information to the user.

3. **Analysis Phase Notes**:
   - If the transcript is too short (fewer than 50 words), note this and provide analysis only on available content.
   - If the transcript appears to be auto-generated and contains many errors, note this caveat at the beginning of the analysis.

## 🌟 Typical Use Cases
1. **Competitive content strategy analysis**: Analyze competitors' top-performing videos to understand their messaging and positioning.
2. **Target audience research**: Identify who competitors are targeting and how they speak to them.
3. **Pain point discovery**: Extract customer pain points mentioned in competitor videos for product development insights.
4. **Content gap identification**: Find topics competitors haven't covered well to create differentiated content.
5. **CTA strategy benchmarking**: Understand how competitors drive conversions through their video content.
6. **Value proposition mapping**: Map out what value propositions competitors emphasize most.
7. **Messaging framework extraction**: Learn from competitors' narrative structures and persuasion techniques.
8. **Market trend analysis**: Batch analyze recent videos in a niche to identify emerging themes and shifts.
9. **Content quality benchmarking**: Evaluate the depth and credibility of competitor content.
10. **Marketing copy inspiration**: Extract memorable phrases and emotional hooks for your own content creation.

FILE:scripts/youtube_transcript_analysis_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
SINGLE_TEMPLATE_ID = "87197468034420377"
BATCH_TEMPLATE_ID = "87198942474882969"
API_BASE_URL = "https://api.browseract.com/v2/workflow"


def run_single_video_task(api_key, target_url):
    """
    Starts a single YouTube video transcript extraction task and polls for completion.
    Returns the transcript and metadata as a string, or None on failure.
    """
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": SINGLE_TEMPLATE_ID,
        "input_parameters": [
            {"name": "TargetURL", "value": target_url}
        ]
    }

    # 1. Start Task
    print(f"[Single Mode] Starting transcript extraction for: {target_url}", flush=True)
    try:
        res = requests.post(
            f"{API_BASE_URL}/run-task-by-template",
            json=payload, headers=headers, timeout=30
        ).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        res_str = str(res)
        if "Invalid authorization" in res_str:
            print("Error: Invalid authorization. Please check your BrowserAct API Key.", flush=True)
        elif "concurrent" in res_str.lower() or "too many running tasks" in res_str.lower():
            print("Error: Concurrent task limit reached. Please upgrade your plan at https://www.browseract.com/reception/recharge", flush=True)
        else:
            print(f"Error: Could not start task. Response: {res}", flush=True)
        return None

    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)

    # 2. Poll for Completion
    max_poll_time = 900
    poll_start = time.time()
    finished = False
    while time.time() - poll_start < max_poll_time:
        try:
            status_res = requests.get(
                f"{API_BASE_URL}/get-task-status?task_id={task_id}",
                headers=headers, timeout=30
            ).json()
            status = status_res.get("status")

            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)

            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                finished = True
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)

        time.sleep(10)

    if not finished:
        print(f"Error: Task polling timed out after {max_poll_time} seconds.", flush=True)
        return None

    # 3. Get Results
    try:
        task_info = requests.get(
            f"{API_BASE_URL}/get-task?task_id={task_id}",
            headers=headers, timeout=30
        ).json()

        output = task_info.get("output", {})
        result_string = output.get("string")

        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None


def run_batch_video_task(api_key, keywords, upload_date="This week", limit=3):
    """
    Starts a batch YouTube video transcript extraction task and polls for completion.
    Returns transcripts and metadata for multiple videos as a string, or None on failure.
    """
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": BATCH_TEMPLATE_ID,
        "input_parameters": [
            {"name": "KeyWords", "value": keywords},
            {"name": "Upload_date", "value": upload_date},
            {"name": "Datelimit", "value": str(limit)}
        ]
    }

    # 1. Start Task
    print(f"[Batch Mode] Searching for '{keywords}' | Upload date: {upload_date} | Limit: {limit}", flush=True)
    try:
        res = requests.post(
            f"{API_BASE_URL}/run-task-by-template",
            json=payload, headers=headers, timeout=30
        ).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        res_str = str(res)
        if "Invalid authorization" in res_str:
            print("Error: Invalid authorization. Please check your BrowserAct API Key.", flush=True)
        elif "concurrent" in res_str.lower() or "too many running tasks" in res_str.lower():
            print("Error: Concurrent task limit reached. Please upgrade your plan at https://www.browseract.com/reception/recharge", flush=True)
        else:
            print(f"Error: Could not start task. Response: {res}", flush=True)
        return None

    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)

    # 2. Poll for Completion
    max_poll_time = 900
    poll_start = time.time()
    finished = False
    while time.time() - poll_start < max_poll_time:
        try:
            status_res = requests.get(
                f"{API_BASE_URL}/get-task-status?task_id={task_id}",
                headers=headers, timeout=30
            ).json()
            status = status_res.get("status")

            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)

            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                finished = True
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)

        time.sleep(10)

    if not finished:
        print(f"Error: Task polling timed out after {max_poll_time} seconds.", flush=True)
        return None

    # 3. Get Results
    try:
        task_info = requests.get(
            f"{API_BASE_URL}/get-task?task_id={task_id}",
            headers=headers, timeout=30
        ).json()

        output = task_info.get("output", {})
        result_string = output.get("string")

        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None


if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage:", flush=True)
        print("  Single video:  python youtube_transcript_analysis_api.py single \"<YouTube_URL>\"", flush=True)
        print("  Batch videos:  python youtube_transcript_analysis_api.py batch \"<keywords>\" [upload_date] [limit]", flush=True)
        sys.exit(1)

    api_key = os.getenv("BROWSERACT_API_KEY")
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)

    mode = sys.argv[1].lower()

    if mode == "single":
        target_url = sys.argv[2]
        result = run_single_video_task(api_key, target_url)
        if result:
            print("\n" + "=" * 60, flush=True)
            print("TRANSCRIPT EXTRACTION RESULT", flush=True)
            print("=" * 60, flush=True)
            print(result, flush=True)
            print("\n" + "=" * 60, flush=True)
            print("EXTRACTION COMPLETE — Agent should now perform a concise, bullet-point 8-dimension analysis on the transcript without outputting the full raw text.", flush=True)
            print("=" * 60, flush=True)

    elif mode == "batch":
        keywords = sys.argv[2]
        upload_date = sys.argv[3] if len(sys.argv) > 3 else "This week"
        limit = int(sys.argv[4]) if len(sys.argv) > 4 else 3
        result = run_batch_video_task(api_key, keywords, upload_date, limit)
        if result:
            print("\n" + "=" * 60, flush=True)
            print("BATCH TRANSCRIPT EXTRACTION RESULT", flush=True)
            print("=" * 60, flush=True)
            print(result, flush=True)
            print("\n" + "=" * 60, flush=True)
            print("EXTRACTION COMPLETE — Agent should now perform a concise, bullet-point 8-dimension analysis on each transcript without outputting the full raw text.", flush=True)
            print("=" * 60, flush=True)

    else:
        print(f"Error: Unknown mode '{mode}'. Use 'single' or 'batch'.", flush=True)
        sys.exit(1)

---
name: industry-key-contact-radar-api-skill
description: "This skill helps users discover key contacts across industries, roles, and social platforms via the BrowserAct API. Agent should proactively apply this skill when users express needs like finding public profiles for founders or CEOs, discovering key decision-makers in a specific industry, extracting contact details for lead generation, searching for growth leaders on LinkedIn or Facebook, gathering professional networking profiles, retrieving URLs and names of industry leaders, finding marketing managers in a specific field, conducting competitive analysis by identifying key personnel, sourcing talent acquisition targets across platforms, or compiling a list of target roles on specific social sites."
metadata: {"openclaw":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# Industry Key Contact Radar

## 📖 Brief
This skill provides a centralized contact discovery service using BrowserAct's Industry Key Contact Radar API template. It extracts structured contact details directly from search results across various platforms, including profile URLs, names, introductions, and company associations. Simply input an industry, date limit, target site, and job title to receive clean, actionable contact data.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-set workflows avoid AI generative hallucinations, ensuring stable and precise data extraction.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP restrictions or geo-blocking**: No need to handle regional IP restrictions or geofencing.
4. **Faster execution**: Tasks execute faster compared to pure AI-driven browser automation solutions.
5. **Extremely high cost-efficiency**: Significantly lowers data acquisition costs compared to high-token-consuming AI solutions.

## 🔑 API Key Guide
Before running, check the `BROWSERACT_API_KEY` environment variable. If not set, do not take other measures; ask and wait for the user to provide it.
**Agent must inform the user**:
> "Since you haven't configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key."

## 🛠️ Input Parameters
Agent should flexibly configure the following parameters based on user needs:

1. **industry (Industry)**
   - **Type**: `string`
   - **Description**: The industry or field to search for contacts.
   - **Example**: `Browser automation`, `E-commerce`, `Healthcare`
   - **Default**: `Browser automation`

2. **Datelimit (Max Items)**
   - **Type**: `number`
   - **Description**: Maximum number of records to extract. For the first run, the default value is recommended.
   - **Example**: `10`
   - **Default**: `10`

3. **site (Target Site)**
   - **Type**: `string`
   - **Description**: The social platform or website to search on.
   - **Example**: `facebook.com`, `linkedin.com`, `github.com`
   - **Default**: `facebook.com`

4. **Job_Title (Job Title)**
   - **Type**: `string`
   - **Description**: The specific role or job title of the target contact.
   - **Example**: `founder`, `CEO`, `marketing manager`
   - **Default**: `founder`

## 🚀 Invocation Method
Agent should use the following independent script to achieve "one-line command result":

```bash
# Example
python -u ./scripts/industry_key_contact_radar_api.py "Browser automation" 10 "facebook.com" "founder"
```

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take some time (several minutes). The script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`).
**Agent guidelines**:
- While waiting for the script result, keep monitoring the terminal output.
- As long as the terminal is outputting new status logs, the task is running normally; do not mistake it for a deadlock or unresponsiveness.
- Only if the status remains unchanged for a long time or the script stops outputting without returning a result should you consider triggering the retry mechanism.

## 📊 Data Output
After successful execution, the script parses and prints results directly from the API response. Results include:
- `url`: The URL link to the contact's public profile
- `name`: The name of the contact or profile title
- `Introduction`: A brief introduction or bio description of the contact
- `Company`: The company or organization associated with the contact

## ⚠️ Error Handling & Retry
If an error occurs during script execution (e.g., network fluctuations or task failure), the Agent should follow this logic:

1. **Check Output Content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. **Do not retry**; guide the user to re-check and provide the correct API Key.
   - If the output **contains** `"concurrent"` or `"too many running tasks"` or similar concurrency limit messages, it means the current subscription plan's concurrent task limit has been reached. **Do not retry**; guide the user to upgrade their plan.
     **Agent must inform the user**:
     > "The current task cannot be executed because your BrowserAct account has reached the limit of concurrent tasks. Please go to the [BrowserAct Plan Upgrade Page](https://www.browseract.com/reception/recharge) to upgrade your subscription plan and enjoy more concurrent task benefits."
   - If the output **does not contain the above error keywords** but the task failed (e.g., output starts with `Error:` or returns empty results), the Agent should **automatically try to re-execute the script once**.

2. **Retry Limit**:
   - Automatic retry is limited to **one time**. If the second attempt fails, stop retrying and report the specific error information to the user.

## 🌟 Typical Use Cases
1. **Lead Generation**: Finding public profiles for founders and CEOs in target industries.
2. **Talent Acquisition**: Sourcing growth leaders and key roles for recruiting.
3. **Competitive Analysis**: Identifying key personnel in competing organizations.
4. **Professional Networking**: Gathering profiles for industry connections.
5. **Market Intelligence**: Collecting URLs and names of industry leaders.
6. **Cross-Platform Discovery**: Searching target profiles on specific sites like LinkedIn or GitHub.
7. **B2B Outreach**: Finding decision-makers and extracting contact details.
8. **Brand Marketing**: Locating marketing managers in a specific field.
9. **Sales Prospecting**: Building lists of specific job titles across industries.
10. **Targeted Job Title Search**: Compiling a list of target roles on specific social sites.
FILE:scripts/industry_key_contact_radar_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "88313898888855812"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_industry_key_contact_radar_task(api_key, industry, date_limit=10, site="facebook.com", job_title="founder"):
    """
    Starts an Industry Key Contact Radar task and polls for completion.
    
    Args:
        api_key (str): BrowserAct API Key
        industry (str): The industry or field to search for contacts
        date_limit (int): Maximum number of records to extract
        site (str): The social platform or website to search on
        job_title (str): The specific role or job title of the target contact
    """
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "industry", "value": str(industry)},
            {"name": "Datelimit", "value": str(date_limit)},
            {"name": "site", "value": str(site)},
            {"name": "Job_Title", "value": str(job_title)}
        ]
    }

    # 1. Start Task
    print(f"Starting task via BrowserAct API...", flush=True)
    try:
        response = requests.post(
            f"{API_BASE_URL}/run-task-by-template",
            json=payload, headers=headers, timeout=30
        )
        res = response.json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        res_str = str(res)
        if "Invalid authorization" in res_str:
            print("Error: Invalid authorization. Please check your BrowserAct API Key.", flush=True)
        elif "concurrent" in res_str.lower() or "too many running tasks" in res_str.lower():
            print("Error: Concurrent task limit reached. Please upgrade your plan at https://www.browseract.com/reception/recharge", flush=True)
        else:
            print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started successfully. Task ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    print(f"Waiting for task completion...", flush=True)
    max_poll_time = 900
    poll_start = time.time()
    finished = False
    
    while time.time() - poll_start < max_poll_time:
        try:
            status_res = requests.get(
                f"{API_BASE_URL}/get-task-status?task_id={task_id}",
                headers=headers, timeout=30
            ).json()
            status = status_res.get("status")

            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)

            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                finished = True
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)

    if not finished:
        print(f"Error: Task polling timed out after {max_poll_time} seconds.", flush=True)
        return None

    # 3. Get Results
    print(f"Retrieving results...", flush=True)
    try:
        task_info_response = requests.get(
            f"{API_BASE_URL}/get-task?task_id={task_id}",
            headers=headers, timeout=30
        )
        task_info = task_info_response.json()
        
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Get API Key from environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python industry_key_contact_radar_api.py <industry> [date_limit] [site] [job_title]", flush=True)
        print("Example: python industry_key_contact_radar_api.py \"Browser automation\" 10 \"facebook.com\" \"founder\"", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Set it as an environment variable (BROWSERACT_API_KEY) or provide it in the chat.", flush=True)
        sys.exit(1)
        
    industry = sys.argv[1]
    date_limit = int(sys.argv[2]) if len(sys.argv) > 2 else 10
    site = sys.argv[3] if len(sys.argv) > 3 else "facebook.com"
    job_title = sys.argv[4] if len(sys.argv) > 4 else "founder"
    
    result = run_industry_key_contact_radar_task(api_key, industry, date_limit, site, job_title)
    if result:
        print(result, flush=True)

---
name: amazon-listing-competitor-analysis-skill
description: "This skill helps users analyze Amazon competitor listings by ASIN and produce structured competitive intelligence plus strategic opportunity points for their own go-to-market. The Agent should proactively apply this skill when users want to analyze a competitor Amazon listing by ASIN, understand what a top-ranked product does right in content keywords or visuals, find market gaps and unmet buyer needs, turn competitor research into opportunity maps for their brand, identify keyword placement patterns on rival listings, extract SEO insights from Amazon product pages, reverse-engineer competitor bullet and title strategies, mine competitor reviews for buyer psychology, compare seller and A plus content patterns, run gap analysis before launching a new SKU, research why a listing wins conversion signals, synthesize whitespace you can own versus the diagnosed listing, or say just look at this ASIN with a competitive or optimization angle."
metadata: {"openclaw":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# Amazon Listing Competitor Analysis

## 📖 Brief
This skill runs a two-phase workflow on a single **competitor** Amazon listing. **Phase 1** uses the BrowserAct Amazon Listing Extractor for SEO template to pull visible product data from that listing. **Phase 2** diagnoses what that competitor does well and where the market shows gaps, then closes with **your strategic opportunity points** (how you can win next to them). Do **not** end with instructions that read like editing or rewriting **this competitor's** listing; the analyzed ASIN is evidence only. Grounded in extracted data, not generic claims.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-defined workflows avoid AI-generated hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP restrictions or geo-blocking**: No need to deal with regional IP restrictions.
4. **Faster execution**: Task execution is faster compared to pure AI-driven browser automation solutions.
5. **Extremely high cost-efficiency**: Significantly reduces data acquisition costs compared to token-heavy AI solutions.

## 🔑 API Key Guide
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take any other actions; you should request and wait for the user to provide it.
**The Agent must inform the user**:
> "Since you haven't configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key."

## 🛠️ Input Parameters
The Agent should dynamically configure the following parameters based on user requirements when calling the script:

1. **ASIN**
   - **Type**: `string`
   - **Description**: The ASIN (Amazon Standard Identification Number) of the Amazon product to analyze.
   - **Example**: `B0CS62LY6P`
   - **Required**: Yes

2. **Marketplace_url**
   - **Type**: `string`
   - **Description**: The base URL of the Amazon marketplace. Use the correct regional site for the listing.
   - **Example**: `https://www.amazon.com/`, `https://www.amazon.de/`
   - **Default**: `https://www.amazon.com/`
   - **Required**: No (defaults when omitted)

## 🚀 Invocation Method
Run Phase 1 extraction with the script below. After structured data is returned, the Agent performs Phase 2 analysis using the framework in **Competitive Analysis Framework (Phase 2)**. The closing section must synthesize **opportunity points for the user’s business**, not a checklist of edits applied to the competitor page under review.

```bash
python -u ./scripts/amazon_listing_competitor_analysis.py "B0CS62LY6P" "https://www.amazon.com/"
```

When only the ASIN is needed, the marketplace argument may be omitted; the script defaults to `https://www.amazon.com/`.

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`) while running.
**Agent guidelines**:
- While waiting for the script to return a result, please keep monitoring the terminal output.
- As long as the terminal continues to output new status logs, it means the task is running normally. Do not mistakenly judge it as a deadlock or unresponsiveness.
- Only consider triggering the retry mechanism if the status remains unchanged for a long time or the script stops outputting without returning a result.

## 📊 Data Output
Upon successful execution, the script prints the API result string (or full task JSON if no string field is present). Typical fields include:
- `asin`, `title`, `product_url`, `brand`, `price`, `coupon_text`, `rating`, `review_count`, `best_sellers_rank`, `availability`, `prime_eligible`
- `description`, `short_description`, `category`, `key_features`, `bullet_points`
- `main_image_url`, `additional_image_urls`, `seller_name`, `ships_from`, `sold_by`
- `specifications`, `product_details`, `attributes`, and review-related blocks (reviewer, content, date, helpful votes, etc.)

Use this payload as the single source of truth for Phase 2; do not invent listing facts.

## ⚠️ Error Handling & Retry
If an error occurs during script execution (such as network fluctuations or task failure), the Agent should follow this logic:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. In this case, **do not retry**. Guide the user to recheck and provide the correct API Key.
   - If the output **contains** information related to concurrency limits like `"concurrent"` or `"too many running tasks"`, it means the concurrent task limit for the current subscription plan has been reached. In this case, **do not retry**. Guide the user to upgrade their plan.
     **The Agent must inform the user**:
     > "The current task cannot be executed because your BrowserAct account has reached the limit of concurrent tasks. Please go to the [BrowserAct Plan Upgrade Page](https://www.browseract.com/reception/recharge) to upgrade your subscription plan and enjoy more concurrent task benefits."
   - If the output **does not contain** the above error keywords, but the task fails to execute (e.g., the output starts with `Error:` or returns an empty result), the Agent should **automatically try to execute the script once more**.

2. **Retry limit**:
   - Automatic retry is limited to **once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

## 🌟 Typical Use Cases
1. **Competitor listing teardown**: Analyze one ASIN to see title formula, bullets, and differentiation language.
2. **Keyword placement audit**: Map where primary and long-tail terms appear across title, bullets, and description or A plus content.
3. **Visual strategy review**: Infer image narrative, infographic highlights, and video approach from extracted media data.
4. **Buyer-validated selling points**: Use high-helpful positive reviews to confirm what buyers value versus what the listing emphasizes.
5. **Unmet needs mining**: Use three-star and mixed reviews to find feature and expectation gaps.
6. **Pre-launch gap analysis**: Compare a planned positioning against a top competitor's listing structure.
7. **Cross-marketplace research**: Run the same ASIN on different regional Amazon URLs for localized copy signals.
8. **Opportunity backlog from a rival listing**: Turn extracted facts and gaps into a prioritized map of positioning, search, creative, and offer opportunities for your side of the market.
9. **SEO and conversion benchmarking**: Relate BSR, rating volume, and copy patterns without guessing unavailable metrics.
10. **Review-driven objection handling**: Surface recurring complaints to address in copy or images.

## 🧠 Competitive Analysis Framework (Phase 2)
After extraction succeeds, work through each dimension below. Every insight must be grounded in the actual extracted data.

### Layer 1 — What the Competitor Did Right

**1. Content Strategy**

- **Title formula**: Information order, primary keyword placement, brand-first vs feature-first vs use-case-first.
- **Bullet priority**: What Bullet 1 leads with; selling point order across bullets (signal of tested conversion order).
- **Differentiation language**: How generic category features are phrased to sound distinct.
- **A+ content**: Modules implied by extracted content (comparison table, brand story, lifestyle, spec callouts).

**2. Keyword Placement Strategy**

Map *where* terms appear (not only which terms exist):

- Title (first 80 chars) → primary ranking bets
- Bullets 1–2 → secondary high-weight terms
- Bullets 3–5 → long-tail and use-case terms
- Description / A+ → supplementary terms and synonyms

**3. Visual Content Strategy**

- **Image narrative arc**: Sequence story (hero, lifestyle, pain point, specs, size comparison, social proof, guarantee).
- **Infographic data**: Numbers or attributes highlighted and how they are presented.
- **Video** (if present in data): Hook length, demo vs lifestyle, subtitles.
- **Overall style**: Premium, approachable, technical, lifestyle-focused.

**4. Buyer-Validated Selling Points**

From four- to five-star reviews with high helpful votes:

- What reviewers praise that the listing underplays
- Unexpected benefits buyers mention

### Layer 2 — What the Market Lacks

**5. Unmet Buyer Needs**

From three-star reviews and recurring themes in low stars (non-defect noise):

- “I wish it had…”, “Would be five stars if…”, “Good but not great because…”

**6. Keyword Gaps**

- Natural search terms buyers would use that the listing does not cover
- High-traffic angles the data suggests but copy does not foreground

**7. Visual Content Gaps**

- Weak or missing context in existing images
- Absent image types (use-case, comparison, real-world scale)

### Required Output Format (Phase 2)
Produce the analysis using this structure. Be specific and quote or paraphrase extracted fields and reviews where useful. The final block is **your opportunity synthesis**; avoid imperatives that sound like “change this competitor's bullet five” or any direct edit list for the ASIN being studied.

```
Competitor ASIN: [ASIN] | Brand: [brand] | BSR: [rank] | Rating: [x.x] ([N] reviews)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ WHAT THIS COMPETITOR DOES RIGHT

Content Strategy:
  - Title formula: [describe the pattern and keyword placement]
  - Bullet priority: [what each bullet leads with and the logic behind the order]
  - Standout phrasing: [specific language worth noting or borrowing]
  - A+ modules: [which are used and what they emphasize]

Keyword Placement:
  - Primary (title, first 80 chars): [keywords]
  - High-weight (Bullets 1–2): [terms]
  - Long-tail (Bullets 3–5): [terms]
  - Supplementary (description/A+): [terms]

Visual Strategy:
  - Image sequence: [describe the narrative arc across images]
  - Infographic highlights: [what data/specs are called out]
  - Video: [approach if present, or "none"]

Buyer-Validated Selling Points:
  - "[specific insight from high-helpful reviews]"
  - "[another insight]"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🕳️ MARKET GAPS (OBSERVED ON THIS COMPETITOR LISTING)

Content gap: [selling points or use cases their copy under-serves, as seen in extracted text]
Keyword gap: [search intents or terms weakly covered on their page — note buyer language from reviews where possible]
Visual gap: [image or video proof types missing or weak on their gallery or A+]
Unmet buyer needs: [recurring themes from 3-star and mixed reviews, quoted or paraphrased]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 YOUR STRATEGIC OPPORTUNITY POINTS (FOR YOUR BRAND OR ROADMAP — NOT EDITS TO THIS LISTING)

The ASIN above is the competitor under diagnosis. Below, translate gaps into **where you can win**; do not phrase outcomes as rewriting their bullets or their title.

Positioning and messaging whitespace:
  - [Claim, use case, or audience angle they under-own; why it is an opening for you]

Search and intent capture:
  - [Queries or intents implied by reviews or category that their listing weakly serves; how you could own a different slice of demand]

Trust, proof, and creative differentiation:
  - [Proof points, demos, or gallery angles they lack that you could credibly own]

Product, offer, or bundle opportunity:
  - [Unmet needs from reviews that map to a SKU, variant, bundle, warranty, or service on your side — stay factual to extracted complaints and wishes]

Competitive strengths to respect or neutralize:
  - [What this competitor does so well in copy, visuals, or social proof that you should assume as the bar before claiming superiority]
```

FILE:scripts/amazon_listing_competitor_analysis.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "88457577087632388"
API_BASE_URL = "https://api.browseract.com/v2/workflow"


def run_amazon_listing_competitor_analysis_task(api_key, asin, marketplace_url="https://www.amazon.com/"):
    """
    Starts an Amazon listing extraction task for competitor analysis and polls for completion.
    Returns structured data as a string, or None on failure.
    """
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "ASIN", "value": asin},
            {"name": "Marketplace_url", "value": marketplace_url}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(
            f"{API_BASE_URL}/run-task-by-template",
            json=payload, headers=headers, timeout=30
        ).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        res_str = str(res)
        if "Invalid authorization" in res_str:
            print("Error: Invalid authorization. Please check your BrowserAct API Key.", flush=True)
        elif "concurrent" in res_str.lower() or "too many running tasks" in res_str.lower():
            print("Error: Concurrent task limit reached. Please upgrade your plan at https://www.browseract.com/reception/recharge", flush=True)
        else:
            print(f"Error: Could not start task. Response: {res}", flush=True)
        return None

    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)

    # 2. Poll for Completion
    max_poll_time = 900
    poll_start = time.time()
    finished = False
    while time.time() - poll_start < max_poll_time:
        try:
            status_res = requests.get(
                f"{API_BASE_URL}/get-task-status?task_id={task_id}",
                headers=headers, timeout=30
            ).json()
            status = status_res.get("status")

            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)

            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                finished = True
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)

        time.sleep(10)

    if not finished:
        print(f"Error: Task polling timed out after {max_poll_time} seconds.", flush=True)
        return None

    # 3. Get Results
    try:
        task_info = requests.get(
            f"{API_BASE_URL}/get-task?task_id={task_id}",
            headers=headers, timeout=30
        ).json()

        output = task_info.get("output", {})
        result_string = output.get("string")

        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python amazon_listing_competitor_analysis.py <asin> [marketplace_url]", flush=True)
        sys.exit(1)

    api_key = os.getenv("BROWSERACT_API_KEY")
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)

    asin = sys.argv[1]
    marketplace_url = sys.argv[2] if len(sys.argv) > 2 else "https://www.amazon.com/"

    result = run_amazon_listing_competitor_analysis_task(api_key, asin, marketplace_url)
    if result:
        print(result, flush=True)

---
name: browser-act
description: "Browser automation CLI for AI agents with anti-detection stealth browsing, captcha solving, and parallel multi-browser support. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, scraping sites with bot detection, or automating any browser task. Also use when the user needs to connect to their existing Chrome session, configure proxy-based stealth browsing, or run parallel browser sessions. Triggers on requests to open a website, fill out a form, click a button, take a screenshot, scrape data from a page, login to a site, automate browser actions, handle captcha challenges, or any task requiring programmatic web interaction."
allowed-tools: Bash(browser-act:*)
metadata:
  author: BrowserAct
  version: "1.1.0"
  install: "uv tool install browser-act-cli --python 3.12"
  homepage: "https://www.browseract.com"
  requires:
    runtime: "Python 3.12+, uv package manager"
    binaries: "Stealth mode: Chromium bundled by the CLI. Real Chrome mode: user's local Chrome/Chromium installation."
  data-paths: "macOS: ~/Library/Application Support/browseract/ | Windows: %APPDATA%\\browseract | Linux: -~/.local/share/browseract"
  config-files:
    - "<data-path>/config.json — CLI credentials and settings, managed internally. No env vars required."
  permissions:
    - "Network access — required for: CLI install from PyPI, captcha solving and stealth browser management via BrowserAct cloud API"
    - "Filesystem read/write at <data-path> — required for: storing browser profiles (cookies, cache), config.json (credentials), and session logs"
    - "CDP connection to local Chrome — required for: Real Chrome mode only, to control the user's running browser instance"
  data-privacy:
    local-only: "All cookies, login sessions, page content, and browser profile data are stored locally only — never uploaded."
    cloud-transmitted:
      captcha-solving: "page URL, captcha element coordinates"
      stealth-management: "browser name, proxy scheme/host, privacy mode"
    cloud-never-transmitted: "cookies, page HTML, screenshots, credentials, browsing history, form data"
  user-confirmation-required:
    - "First-time install (uv tool install): downloads and runs external package"
---

# Browser Automation with browser-act CLI

`browser-act` is a CLI for browser automation with stealth and captcha solving capabilities. It supports two browser types (Stealth and Real Chrome) and provides commands for navigation, page interaction, data extraction, tab/session management, and more.

All commands output human-readable text by default. Use `--format json` for structured JSON output, ideal for AI agent integration and scripting.

## Installation

Source: [browser-act-cli on PyPI](https://pypi.org/project/browser-act-cli/) · [Homepage](https://www.browseract.com)

```bash
# Upgrade if installed, otherwise install fresh
uv tool upgrade browser-act-cli || uv tool install browser-act-cli --python 3.12
```

The CLI is an open-source package published to PyPI by [BrowserAct](https://www.browseract.com). Run the install command at the start of every session to ensure the latest version.

**Global options** available on every command:

| Option | Default | Description |
|--------|---------|-------------|
| `--session <name>` | `default` | Session name (isolates browser state) |
| `--format <text\|json>` | `text` | Output format |
| `--no-auto-dialog` | off | Disable automatic JavaScript dialog handling (alerts, confirms, prompts) |
| `--version` | | Show version |
| `-h, --help` | | Show help |

## Browser Selection

browser-act supports two browser types. Choose based on the task:

| Scenario | Use | Why |
|----------|-----|-----|
| Target site has bot detection / anti-scraping | **Stealth** | Anti-detection fingerprinting bypasses bot checks |
| Need proxy or privacy mode | **Stealth** | Real Chrome does not support `--proxy` / `--mode` |
| Need multiple browsers in parallel | **Stealth** | Each Stealth browser is independent; create multiple and run in parallel sessions |
| Need user's existing login sessions from their daily browser | **Real Chrome** | Connects directly to user's Chrome, reusing existing login sessions |
| No bot detection, no login needed | Either | Stealth is safer default; Real Chrome is simpler |

### Stealth Browser

Local browsers with anti-detection fingerprinting. Ideal for sites with bot detection.

```bash
# Create
browser-act browser create "my-browser"
browser-act browser create "my-browser" --proxy socks5://host:port --mode private

# Update
browser-act browser update <browser_id> --name "new-name"
browser-act browser update <browser_id> --proxy http://proxy:8080 --mode private

# List / Delete / Clear profile
browser-act browser list                                    # List all stealth browsers
browser-act browser list --page 2 --page-size 10            # Paginated listing
browser-act browser delete <browser_id>                     # ⚠ Destructive: always confirm with user before deleting
browser-act browser clear-profile <browser_id>
```

| Option | Description |
|--------|-------------|
| `--desc` | Browser description |
| `--proxy <url>` | Proxy with scheme (`http`, `https`, `socks4`, `socks5`), e.g. `socks5://host:port` |
| `--mode <normal\|private>` | `normal` (default): persists cache, cookies, login across launches. `private`: fresh environment every launch, no saved state |

Stealth browsers in `normal` mode (default) persist cookies, cache, and login sessions across launches — you can log in once and reuse the session, similar to a regular browser profile. Use `--mode private` when the task should not persist any state.

**Data storage:** Profile data is stored at platform-specific paths — macOS: `~/Library/Application Support/browseract/`, Windows: `%APPDATA%\browseract`, Linux: `-~/.local/share/browseract`. To clean up persistent data, delete the browser with `browser-act browser delete <browser_id>` or use `browser-act browser clear-profile <browser_id>` to reset its profile.

### Real Chrome

Two modes: auto-connect to your running Chrome (default), or use a BrowserAct-managed kernel.

```bash
browser-act browser real open https://example.com                  # Auto-connect to running Chrome 
browser-act browser real open https://example.com --ba-kernel      # Use BrowserAct-provided browser kernel
```

Both browser types support `--headed` to show the browser UI (default: headless). Use for debugging:

```bash
browser-act browser open <browser_id> https://example.com --headed
browser-act browser real open https://example.com --ba-kernel --headed
```


## Core Workflow

Every browser automation follows this loop: **Open → Inspect → Interact → Verify**

1. **Open**: `browser-act browser open <browser_id> <url>` (Stealth) or `browser-act browser real open <url>` (Real Chrome)
2. **Inspect**: `browser-act state` — returns interactive elements with index numbers
3. **Interact**: use indices from `state` (`browser-act click 5`, `browser-act input 3 "text"`)
4. **Verify**: `browser-act state` or `browser-act screenshot` — confirm result

```bash
browser-act browser open <browser_id> https://example.com
browser-act state
# Output: [3] input "Search", [5] button "Go"

browser-act input 3 "browser automation"
browser-act click 5
browser-act wait stable
browser-act state    # Always re-inspect after page changes
```

**Important:** After any action that changes the page (click, navigation, form submit), run `wait stable` then `state` to get fresh element indices. Old indices become invalid after page changes.

## Command Chaining

Commands can be chained with `&&` in a single shell invocation. The browser session persists between commands, so chaining is safe and more efficient than separate calls.

```bash
# Open + wait + inspect in one call
browser-act browser open <browser_id> https://example.com && browser-act wait stable && browser-act state

# Chain multiple interactions
browser-act input 3 "browser automation" && browser-act click 5

# Navigate and capture
browser-act navigate https://example.com/dashboard && browser-act wait stable && browser-act screenshot
```

**When to chain:** Use `&&` when you don't need to read intermediate output before proceeding (e.g., fill multiple fields, then click). Run commands separately when you need to parse the output first (e.g., `state` to discover indices, then interact using those indices).

## Command Reference

### Navigation

```bash
browser-act navigate <url>      # Navigate to URL
browser-act back                # Go back
browser-act forward             # Go forward
browser-act reload              # Reload page
```

### Page State & Interaction

```bash
# Inspect
browser-act state                         # Interactive elements with index numbers
browser-act screenshot                    # Screenshot (auto path)
browser-act screenshot ./page.png         # Screenshot to specific path

# Interact (use index from state)
browser-act click <index>                 # Click element
browser-act hover <index>                 # Hover over element
browser-act input <index> "text"          # Click element, then type text
browser-act keys "Enter"                  # Send keyboard keys
browser-act scroll down                   # Scroll down (default 500px)
browser-act scroll up --amount 1000       # Scroll up 1000px
```

### Data Extraction

```bash
browser-act get title                     # Page title
browser-act get html                      # Full page HTML
browser-act get text <index>              # Text content of element
browser-act get value <index>             # Value of input/textarea
browser-act get markdown                  # Page as markdown
```

### JavaScript Evaluation

```bash
browser-act eval "document.title"         # Execute JavaScript
```

### Tab Management

```bash
browser-act tab list                      # List open tabs
browser-act tab switch <tab_id>           # Switch to tab
browser-act tab close                     # Close current tab
browser-act tab close <tab_id>            # Close specific tab
```

### Wait

```bash
browser-act wait stable                   # Wait for page stable (doc ready + network idle, default 30s)
browser-act wait stable --timeout 60000   # Custom timeout (ms)
```

### Network Inspection

```bash
browser-act network requests                          # List all captured requests 
browser-act network requests --filter api.example.com # Filter by URL substring
browser-act network requests --type xhr,fetch         # Resource type: xhr,fetch,document,script,stylesheet,image,font,media,websocket,ping,preflight,other
browser-act network requests --method POST            # HTTP method: GET, POST, PUT, DELETE, etc.
browser-act network requests --status 2xx             # Filter by http status code (200, 2xx, 400-499)
browser-act network request <request_id>              # View full detail: headers, post data, response headers & body
browser-act network clear                             # Clear tracked requests
browser-act network har start                         # Start HAR recording
browser-act network har stop                          # Stop and save to default path (~/.browseract/har/)
browser-act network har stop ./trace.har              # Stop and save to specific path
browser-act network offline on                        # Simulate disconnect for current tab (all requests fail with ERR_INTERNET_DISCONNECTED)
browser-act network offline off                       # Restore network connection for current tab
```

Use `network request <request_id>` to get full detail for a single request. The detail view includes: request headers, post data (for POST/PUT), response headers, and response body. Binary responses show a `[base64, N chars]` placeholder instead of raw content.

### Dialog Management

Handle JavaScript dialogs (alert, confirm, prompt). By default, browser-act auto-accepts dialogs. Use `--no-auto-dialog` to disable this and handle them manually.

```bash
browser-act dialog status                 # Check if a dialog is currently open
browser-act dialog accept                 # Accept (OK) the current dialog
browser-act dialog accept "some text"     # Accept with text input (for prompt dialogs)
browser-act dialog dismiss                # Dismiss (Cancel) the current dialog
```

**Manual dialog flow:** Pass `--no-auto-dialog` when opening the browser, then use `dialog status` to detect dialogs and `dialog accept` / `dialog dismiss` to handle them.

### Captcha Solving

When a page presents a captcha challenge, use `solve-captcha` to solve it automatically. This is a built-in capability of the browser-act service — run the command directly without hesitation.

```bash
browser-act solve-captcha                 # Solve captcha on current page
```

## Parallel Automation

Use separate sessions to run multiple browsers in parallel. Each `--session <name>` creates an isolated browser context — commands to different sessions can execute concurrently without conflicts.

```bash
# Create stealth browsers for each task
browser-act browser create "site-a" --desc "Scraper for site A"
browser-act browser create "site-b" --desc "Scraper for site B"

# Open each in its own session (run in parallel)
browser-act --session site-a browser open <browser_id_a> https://site-a.com
browser-act --session site-b browser open <browser_id_b> https://site-b.com

# Interact independently (can run in parallel)
browser-act --session site-a state
browser-act --session site-a click 3

browser-act --session site-b state
browser-act --session site-b click 5

# Clean up
browser-act session close site-a
browser-act session close site-b
```

Always close sessions when done to free resources.

## Session Management

Sessions isolate browser state. Each session runs its own background server.

```bash
# Use a named session
browser-act --session scraper navigate https://example.com
browser-act --session scraper state

# List active sessions
browser-act session list

# Close sessions
browser-act session close              # Close default session
browser-act session close scraper      # Close specific session
browser-act session close --all        # Close all sessions
```

The server auto-shuts down after a period of inactivity.

## Site Notes

Operational experience accumulated during browser automation is stored per domain in `references/site-notes/`.

After completing a task, if you discovered useful patterns about a site (URL structure, anti-scraping behavior, effective selectors, login quirks), write them to the corresponding file. Only write verified facts, not guesses.

**File format:**

```markdown
---
domain: example.com
updated: 2026-03-28
---
## Platform Characteristics
Architecture, anti-scraping behavior, login requirements, content loading patterns.

## Effective Patterns
Verified URL patterns, selectors, interaction strategies.

## Known Pitfalls
What fails and why.
```

**Before operating on a target site**, check if a note file exists and read it for prior knowledge. Notes are dated — treat them as hints that may have changed, not guarantees.

## System Commands

```bash
browser-act report-log                    # Upload logs to help diagnose issues
browser-act feedback "message"            # Send feedback to help improve this skill
```

If you encounter issues or have suggestions for improving browser-act, use `feedback` to let us know. This directly helps us improve the tool and this skill.

## Troubleshooting

- **`browser-act: command not found`** — Run `uv tool install browser-act-cli --python 3.12`

## References

| Path | Description |
|------|-------------|
| `references/SECURITY.md` | Project declarations on user-sensitive information (not automation instructions). |
| `references/site-notes/{domain}.md` | Per-site operational experience. Read before operating on a known site. |

FILE:references/site-notes/example.com.md
---
domain: example.com
updated: 2026-03-28
---

## Platform Characteristics

Static site with no bot detection or login requirements. Pages load instantly with minimal JavaScript. No anti-scraping measures in place.

## Effective Patterns

- Direct navigation works reliably: `browser-act navigate https://example.com`
- Full page content available via `get markdown` without scrolling
- Single-page structure — no pagination or lazy loading

## Known Pitfalls

None identified. This is a simple reference site with no dynamic content.

FILE:references/SECURITY.md
# Security & Privacy

This document is a project-level declaration on how browser-act handles user-sensitive information — including data storage, credentials, cloud transmission, and persistent state. It is intended for security review and user transparency, and is **not** part of the automation instructions.

## Credentials

Managed by the CLI internally (stored in `<data-path>/config.json`). No environment variables required.

## Local Data

All cookies, login sessions, and browser profile data are stored locally and are **never uploaded** to BrowserAct or any third-party service. Data paths:
- macOS: `~/Library/Application Support/browseract/`
- Windows: `%APPDATA%\browseract`
- Linux: `-~/.local/share/browseract`

## Cloud Service Calls

Captcha solving and stealth browser management call BrowserAct cloud services, transmitting only minimal metadata. No cookies, page HTML, screenshots, credentials, or browsing content is sent.

## Real Chrome

Auto-connect mode (`browser real open` without `--ba-kernel`) connects to the user's running Chrome via CDP, reusing existing login sessions. This controls the browser instance in place — it does **not** extract or upload cookies.

## Persistence

Stealth browsers in `normal` mode create persistent profiles on disk (cookies, cache, login state) — this is by design for workflow continuity (e.g., staying logged in across sessions). Use `--mode private` for ephemeral sessions with no saved state. Persistent data is scoped per browser ID and can be removed at any time with `browser delete` or `browser clear-profile`.

## Auditability

The CLI source code is available on [PyPI](https://pypi.org/project/browser-act-cli/). All CLI commands run locally and produce human-readable output by default, making agent actions visible and inspectable.

---
name: youtube-transcript-extractor-api-skill
description: "This skill helps users automatically extract YouTube video transcripts and metadata via the BrowserAct API. The Agent should proactively apply this skill when users express needs like extracting full transcript from a specific YouTube video, getting subtitles and metadata for video content analysis, gathering video titles and likes counts, summarizing YouTube videos without watching them, collecting channel details from a video URL, tracking transcript automation for specific videos, scraping YouTube subtitles for internal knowledge bases, fetching full video content for AI summarization pipelines, downloading structured transcripts from YouTube links, analyzing video text content for media research, monitoring video publisher information and channel links, or building datasets from YouTube video transcripts."
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# YouTube Transcript Extractor API Skill

## 📖 Introduction
This skill provides a one-stop video transcript extraction service using BrowserAct's YouTube Transcript Extractor API template. It can directly extract full video transcripts and metadata from any YouTube video. By simply providing the TargetURL, you can get clean, ready-to-use transcript and metadata.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-set workflows avoid generative AI hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP access restrictions or geofencing**: No need to deal with regional IP limits.
4. **Faster execution**: Compared to pure AI-driven browser automation solutions, task execution is much faster.
5. **High cost-effectiveness**: Significantly reduces data acquisition costs compared to AI solutions that consume large amounts of tokens.

## 🔑 API Key Setup
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take any other actions; you must request and wait for the user to provide it.
**The Agent must inform the user at this point**:
> "Since you haven't configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key first."

## 🛠️ Input Parameters
The Agent should configure the following parameter based on the user's needs when calling the script:

1. **TargetURL (Target URL)**
   - **Type**: `string`
   - **Description**: The URL of the YouTube video you want to extract the transcript and metadata from.
   - **Example**: `https://www.youtube.com/watch?v=st534T7-mdE`

## 🚀 Usage (Recommended)
The Agent should execute the following independent script to achieve "one command, get results":

```bash
# Example Call
python -u ./scripts/youtube_transcript_extractor_api.py "TargetURL"
```

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take a long time (several minutes). While running, the script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`).
**Agent Instructions**:
- While waiting for the script to return results, please keep an eye on the terminal output.
- As long as the terminal continues to output new status logs, it means the task is running normally. Do not misjudge it as a deadlock or unresponsiveness.
- Only if the status remains unchanged for a long time or the script stops outputting without returning a result, should you consider triggering the retry mechanism.

## 📊 Data Output Description
After successful execution, the script will parse and print the results directly from the API response. The results include:
- `video_title`: The title of the YouTube video
- `video_url`: The direct link to the original video
- `publisher`: The name of the channel publishing the video
- `channel_link`: The URL of the publisher's YouTube channel
- `video_likes_count`: The number of likes the video has received
- `transcript`: The complete extracted transcript/subtitles of the video

## ⚠️ Error Handling & Retry
During script execution, if an error occurs (such as network fluctuation or task failure), the Agent should follow this logic:

1. **Check output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. In this case, **do not retry**, and guide the user to check and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (for example, the output starts with `Error:` or returns an empty result), the Agent should **automatically try to execute the script one more time**.

2. **Retry limits**:
   - Automatic retry is limited to **only once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

FILE:scripts/youtube_transcript_extractor_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "87197468034420377"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_youtube_transcript_extractor_task(api_key, target_url):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "TargetURL", "value": target_url}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python youtube_transcript_extractor_api.py <target_url>", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    target_url = sys.argv[1]
    
    result = run_youtube_transcript_extractor_task(api_key, target_url)
    if result:
        print(result, flush=True)

---
name: youtube-batch-transcript-extractor-api-skill
description: "This skill helps users automatically extract YouTube video transcripts and metadata in batch via the BrowserAct API. The Agent should proactively apply this skill when users express needs like batch extract full transcripts from YouTube videos for specific keywords, scrape YouTube subtitles for a list of videos, get batch video metadata and likes counts for analysis, automate YouTube search and subtitle extraction, collect multiple video transcripts published this week, download bulk YouTube video subtitles without writing crawler scripts, build a dataset of transcripts from top YouTube videos, extract YouTube video URLs and publisher info in batch, gather full video content for AI summarization pipelines, monitor recent YouTube videos and extract their transcripts, batch retrieve structured subtitle data for media research, extract transcripts from trending YouTube content automatically."
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# YouTube Batch Transcript Extractor API Skill

## 📖 Introduction
This skill uses the BrowserAct YouTube Batch Transcript Extractor API template to provide users with an automated service for extracting YouTube video transcripts and metadata in batch. Simply by providing search keywords and filters, you can batch extract full video transcripts, likes, and channel metadata without writing crawler scripts.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-set workflows avoid generative AI hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP access restrictions or geofencing**: No need to deal with regional IP restrictions.
4. **Faster execution**: Tasks execute faster compared to pure AI-driven browser automation solutions.
5. **High cost-effectiveness**: Significantly reduces data acquisition costs compared to AI solutions that consume a large number of tokens.

## 🔑 API Key Guide Process
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take any other actions; you should request and wait for the user to provide it collaboratively.
**The Agent must inform the user at this time**:
> "Since you have not yet configured the BrowserAct API Key, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key first."

## 🛠️ Input Parameters
When calling the script, the Agent should flexibly configure the following parameters based on user needs:

1. **KeyWords**
   - **Type**: `string`
   - **Description**: The keyword to search for on YouTube.
   - **Example**: `OpenClaw`, `AI Automation`

2. **Upload_date**
   - **Type**: `string`
   - **Description**: Filter for the upload date of the videos.
   - **Optional values**: `Today`, `This week`, `This month`, `This year`.
   - **Default value**: `This week`

3. **Datelimit**
   - **Type**: `number`
   - **Description**: The number of videos to extract. Adjust as needed.
   - **Default value**: `5`
   - **Recommendation**: Set a smaller value (1-5) for quick tests and a larger value for bulk extraction.

## 🚀 Invocation Method (Recommended)
The Agent should execute the following independent script to achieve "one-line command to get results":

```bash
# Example invocation
python -u ./scripts/youtube_batch_transcript_extractor_api.py "keywords" "Upload_date" Datelimit
```

### ⏳ Execution Status Monitoring
Since this task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output timestamped status logs** (e.g., `[14:30:05] Task Status: running`) while running.
**Agent Notes**:
- While waiting for the script to return results, please keep an eye on the terminal output.
- As long as the terminal is still outputting new status logs, it means the task is running normally. Please do not mistakenly judge it as a deadlock or unresponsiveness.
- Only consider triggering the retry mechanism if the status remains unchanged for a long time or the script stops outputting without returning a result.

## 📊 Data Output Description
After successful execution, the script will parse and print the results directly from the API response. The results include:
- `Video title`: The title of the YouTube video.
- `Video URL`: The direct link to the original video.
- `Publisher`: The name of the channel publishing the video.
- `Channel link`: The URL of the publisher's YouTube channel.
- `Video likes count`: The number of likes the video has received.
- `Subtitles`: The complete extracted transcript/subtitles of the videos.

## ⚠️ Error Handling & Retry
If an error is encountered during the execution of the script (such as network fluctuation or task failure), the Agent should follow the logic below:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it indicates that the API Key is invalid or expired. **Do not retry** at this time. You should guide the user to recheck and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (for example, the output starts with `Error:` or returns an empty result), the Agent should **automatically try to execute the script once more**.

2. **Retry limits**:
   - Automatic retry is limited to **once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

FILE:scripts/youtube_batch_transcript_extractor_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "87198942474882969"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_youtube_transcript_task(api_key, keywords, upload_date="This week", limit=5):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "KeyWords", "value": keywords},
            {"name": "Upload_date", "value": upload_date},
            {"name": "Datelimit", "value": str(limit)}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python youtube_batch_transcript_extractor_api.py <keywords> [upload_date] [limit]", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    keywords = sys.argv[1]
    upload_date = sys.argv[2] if len(sys.argv) > 2 else "This week"
    limit = sys.argv[3] if len(sys.argv) > 3 else 5
    
    result = run_youtube_transcript_task(api_key, keywords, upload_date, limit)
    if result:
        print(result, flush=True)

---
name: amazon-buy-box-monitor-api-skill
description: This skill helps users extract basic product details other sellers prices and seller ratings from Amazon via ASIN automatically using the BrowserAct API. Agent should proactively apply this skill when users express needs like query Amazon buy box information, monitor Amazon product prices, extract Amazon product details by ASIN, check other sellers prices on Amazon, get Amazon seller ratings and feedback count, monitor buy box ownership for a specific ASIN, track Amazon fulfillment methods for competitors, compare Amazon product prices across different sellers, retrieve Amazon buy box availability status, analyze Amazon seller profile details.
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# Amazon Buy Box Monitor API Skill

## 📖 Introduction
This skill provides users with an automated Amazon Buy Box monitoring service using the BrowserAct API template. It can directly extract structured data including basic product details, other sellers' prices, and seller ratings from Amazon via a specific ASIN. No coding or proxies are required, and users only need to provide the ASIN and an optional marketplace URL to retrieve clean and usable data.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-set workflows avoid AI generative hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP access restrictions or geo-fencing**: No need to handle regional IP restrictions.
4. **More agile execution speed**: Faster task execution compared to purely AI-driven browser automation solutions.
5. **Extremely high cost-effectiveness**: Significantly reduces data acquisition costs compared to AI solutions that consume massive amounts of tokens.

## 🔑 API Key Guidance
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take any other actions; you must prompt and wait for the user to provide it.
**The Agent must inform the user at this time**:
> "Since you have not configured the BrowserAct API Key, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) first to get your Key."

## 🛠️ Input Parameters
When calling the script, the Agent should flexibly configure the following parameters based on the user's needs:

1. **ASIN**
   - **Type**: `string`
   - **Description**: The Amazon Standard Identification Number. This is the unique identifier for the product on Amazon.
   - **Example**: `B005O2ZU68`
   - **Required**: Yes

2. **Marketplace_url**
   - **Type**: `string`
   - **Description**: The Amazon marketplace URL indicating the region.
   - **Default value**: `https://amazon.com/`
   - **Example**: `https://amazon.co.uk/`
   - **Required**: Yes

## 🚀 Invocation Method (Recommended)
The Agent should execute the following standalone script to achieve "one command to get results":

```bash
# Example invocation
python -u ./scripts/amazon_buy_box_monitor_api.py "ASIN" "Marketplace_url"
```

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take some time (several minutes). The script will **continuously output status logs with timestamps** while running (e.g., `[14:30:05] Task Status: running`).
**Agent Instructions**:
- While waiting for the script to return results, please keep paying attention to the terminal output.
- As long as the terminal is still outputting new status logs, it means the task is running normally. Do not misjudge it as deadlocked or unresponsive.
- If the status remains unchanged for a long time or the script stops outputting without returning a result, then consider triggering the retry mechanism.

## 📊 Data Output Description
After successful execution, the script will parse and print the result directly from the API response. The result includes:
- `asin`: The Amazon Standard Identification Number
- `product_title`: The title of the product
- `buy_box_owner`: The owner of the buy box
- `buy_box_price`: The current buy box price
- `currency`: The currency of the price
- `fulfillment_method`: The fulfillment method (e.g., FBA, FBM)
- `availability_status`: Stock availability status
- `other_sellers`: An array of other sellers including their name, price, shipping fee, and seller rating
- `seller_info`: Detailed information about the main seller including rating and feedback count

## ⚠️ Error Handling & Retry
If an error is encountered during the execution of the script (such as network fluctuations or task failure), the Agent should follow this logic:

1. **Check output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. In this case, **do not retry**, but guide the user to re-check and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task fails (e.g., output starts with `Error:` or returns empty results), the Agent should **automatically attempt to execute the script once more**.

2. **Retry limits**:
   - Automatic retry is limited to **only once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

## 🌟 Typical Use Cases
1. **Query Amazon buy box information**: Find out who currently owns the buy box for a specific ASIN.
2. **Monitor Amazon product prices**: Track the current price and buy box price changes.
3. **Extract Amazon product details by ASIN**: Get basic product information like title and brand.
4. **Check other sellers prices on Amazon**: Analyze pricing strategies of competitors for the same product.
5. **Get Amazon seller ratings and feedback count**: Evaluate the reputation of sellers on the listing.
6. **Monitor buy box ownership for a specific ASIN**: Check if a particular seller maintains the buy box.
7. **Track Amazon fulfillment methods for competitors**: Determine whether competitors are using FBA or FBM.
8. **Compare Amazon product prices across different sellers**: View shipping fees and total prices from multiple sellers.
9. **Retrieve Amazon buy box availability status**: Check if the product is in stock or backordered.
10. **Analyze Amazon seller profile details**: Extract detailed seller info and recent feedback summaries.
FILE:scripts/amazon_buy_box_monitor_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "87215742629531801"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_amazon_buy_box_monitor_task(api_key, asin, marketplace_url="https://amazon.com/"):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "ASIN", "value": asin},
            {"name": "Marketplace_url", "value": marketplace_url}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python amazon_buy_box_monitor_api.py <asin> [marketplace_url]", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    asin = sys.argv[1]
    marketplace_url = sys.argv[2] if len(sys.argv) > 2 else "https://amazon.com/"
    
    result = run_amazon_buy_box_monitor_task(api_key, asin, marketplace_url)
    if result:
        print(result, flush=True)

---
name: zhihu-search-api-skill
description: "This skill helps users automatically extract structured article details and full content from Zhihu via the BrowserAct API. Agent should proactively apply this skill when users express needs like: searching for Zhihu articles on a specific topic, tracking industry trends on Zhihu, monitoring public relations or sentiment on Zhihu, collecting competitor updates, getting the latest reports on specific keywords, monitoring brand exposure in Zhihu media, researching market hot topics, summarizing daily Zhihu industry news, retrieving hot events from the past week, extracting structured data for market research, finding full Zhihu articles for AI agents, extracting full article body from Zhihu links."
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# Zhihu Search API Automated Extraction Skill

## 📖 Brief
This skill uses BrowserAct's Zhihu Search API template to provide a one-stop article extraction service. It extracts structured article details and full content from Zhihu article search results based on keywords and publication date filters.

## ✨ Features
1. **No hallucinations, ensuring stable and precise data extraction**: Pre-set workflows avoid AI generative hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP access restrictions and geo-fencing**: No need to deal with regional IP limits.
4. **Faster execution speed**: Compared to pure AI-driven browser automation solutions, task execution is much faster.
5. **Extremely high cost-effectiveness**: Significantly reduces data acquisition costs compared to AI solutions that consume a large number of tokens.

## 🔑 API Key Guide
Before running, you need to check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take other actions; wait for the user to provide it.
**The Agent must inform the user at this time:**
> "Since you have not configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) first to get your Key."

## 🛠️ Input Parameters
The Agent should flexibly configure the following parameters according to user needs when calling the script:

1. **keyword (Search Keywords)**
   - **Type**: `string`
   - **Description**: Search keywords used to find Zhihu articles. Can be company name, industry term, etc.
   - **Example**: `AI agent`, `openclaw`

2. **Publish_date (Publication Date Range)**
   - **Type**: `string`
   - **Description**: Filter articles by publication date.
   - **Options**:
     - `7d`: Past 7 days
     - `30d`: Past 30 days
     - `90d`: Past 90 days
     - `1y`: Past year
     - `all`: Any time
   - **Default**: `7d`

3. **Date_limit (Extraction Limit)**
   - **Type**: `number`
   - **Description**: Maximum number of articles to extract.
   - **Default**: `10`

## 🚀 Recommended Usage
The Agent should execute the following independent script to achieve "one command gets results":

```bash
# Example call
python -u ./scripts/zhihu_search_api.py "keyword" "Publish_date" limit
```

### ⏳ Execution Status Monitoring
Because this task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`) while running.
**Agent Must Know:**
- While waiting for the script to return a result, keep monitoring the terminal output.
- As long as the terminal is still outputting new status logs, it means the task is running normally, do not mistake it for a deadlock or unresponsiveness.
- If the status remains unchanged for a long time or the script stops outputting without returning a result, then consider triggering the retry mechanism.

## 📊 Data Output
Upon successful execution, the script will directly parse and print the result from the API response. The result includes:
- `title`: Full article title
- `body_content`: Full body content of the article
- `image_url`: Main image URL or article cover image URL
- `author`: Article author or publishing account name
- `publication_date`: Article publication date
- `url_link`: Original article URL

## ⚠️ Error Handling & Retry
During the execution of the script, if an error is encountered (such as network fluctuations or task failure), the Agent should follow this logic:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. Do **not retry** at this time, and guide the user to check and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (for example, the output starts with `Error:` or the return result is empty), the Agent should **automatically try to execute the script once more**.

2. **Retry limits**:
   - Automatic retry is limited to **one time**. If the second attempt still fails, stop retrying and report the specific error information to the user.

## 🌟 Typical Use Cases
1. **Industry Trend Tracking**: Find the latest industry dynamics on specific topics like "low-altitude economy" or "generative AI" on Zhihu.
2. **Public Relations Monitoring**: Monitor the media exposure of a specific brand or company on Zhihu over the past 30 days.
3. **Competitor Intelligence Gathering**: Collect recent product information or market activities published by competitors on Zhihu.
4. **Market Hotspot Research**: Get popular Zhihu reports on specific keywords across different time dimensions.
5. **Character Dynamics Tracking**: Retrieve the latest Zhihu articles and interviews of industry leaders or public figures.
6. **Daily Briefing Summary**: Automatically extract and summarize daily industry news briefings from Zhihu.
7. **Global Event Monitoring**: Real-time access to major breaking news and discussions on Zhihu.
8. **Structured Data Extraction**: Extract structured information such as article titles, authors, and links from Zhihu for market research analysis.
9. **Media Exposure Analysis**: Evaluate the spread and popularity of a specific project or event on Zhihu.
10. **Long-term Thematic Research**: Retrieve in-depth reports and discussions on a specific technical topic from the past year.
FILE:scripts/zhihu_search_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "85791338888470667"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_zhihu_search_task(api_key, keyword, publish_date="7d", limit=10):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "keyword", "value": keyword},
            {"name": "Publish_date", "value": publish_date},
            {"name": "Date_limit", "value": str(limit)}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python zhihu_search_api.py <keyword> [publish_date] [limit]", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    keyword = sys.argv[1]
    publish_date = sys.argv[2] if len(sys.argv) > 2 else "7d"
    limit = sys.argv[3] if len(sys.argv) > 3 else 10
    
    result = run_zhihu_search_task(api_key, keyword, publish_date, limit)
    if result:
        print(result, flush=True)

---
name: web-search-scraper-api-skill
description: "This skill helps users automatically extract complete Markdown content from any website via the BrowserAct Web Search Scraper API. The Agent should proactively apply this skill when users express needs like extract complete markdown from a specific website, scrape the content of an article link, get the text from a target url, convert a webpage to markdown format, fetch the main content of a blog post, extract data from a given web page, parse the html of a website into markdown, download the readable text from a news article, obtain the content of a tutorial page, extract all the markdown text from any http or https url, scrape documentation from a web link, or grab the text of a single webpage."
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# Web Search Scraper API Skill

## 📖 Introduction
This skill provides users with a one-stop web page extraction service through the BrowserAct Web Search Scraper API template. It can directly extract structured markdown content from any given URL. By simply inputting the target URL, you can get clean and usable markdown data.

## ✨ Features
1. **No hallucinations, ensuring stable and precise data extraction**: Pre-set workflows avoid AI generative hallucinations.
2. **No human-machine verification issues**: No need to deal with reCAPTCHA or other verification challenges.
3. **No IP access restrictions or geofencing**: No need to handle regional IP limitations.
4. **More agile execution speed**: Compared to purely AI-driven browser automation solutions, task execution is faster.
5. **Extremely high cost-effectiveness**: Compared to AI solutions that consume a lot of Tokens, it can significantly reduce the cost of data acquisition.

## 🔑 API Key Guidance Process
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take other actions first; you should ask and wait for the user to provide it cooperatively.
**The Agent must inform the user at this time**:
> "Since you have not configured the BrowserAct API Key, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) first to get your Key."

## 🛠️ Input Parameters Details
Agent should flexibly configure the following parameters based on user needs when calling the script:

1. **target_url**
   - **Type**: `string`
   - **Description**: The website URL to extract content from. Supports any HTTP/HTTPS URL.
   - **Example**: `https://www.browseract.com`

## 🚀 Invocation Method (Recommended)
Agent should execute the following independent script to achieve "one command gets the result":

```bash
# Example invocation
python -u ./scripts/web_search_scraper_api.py "target_url"
```

### ⏳ Execution Status Monitoring
Since the task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`) while running.
**Notice for Agent**:
- While waiting for the script to return results, please keep paying attention to the terminal output.
- As long as the terminal is still outputting new status logs, it means the task is running normally. Do not misjudge it as a deadlock or unresponsiveness.
- If the status remains unchanged for a long time or the script stops outputting and no result is returned, the retry mechanism can be triggered.

## 📊 Data Output Description
Upon successful execution, the script will directly parse and print the result from the API response. The result contains:
- `content`: The complete markdown content of the webpage.

## ⚠️ Error Handling & Retry Mechanism
During the execution of the script, if an error occurs (such as network fluctuation or task failure), the Agent should follow this logic:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. At this time, **do not retry**, and you should guide the user to recheck and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (for example, the output starts with `Error:` or the returned result is empty), the Agent should **automatically try to re-execute the script once**.

2. **Retry limit**:
   - Automatic retry is limited to **once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

## 🌟 Typical Use Cases
1. **Article Extraction**: Scrape the main content of a news article link into markdown.
2. **Blog Post Parsing**: Download the readable text from a target blog post URL.
3. **Webpage to Markdown**: Convert any given website URL into clean markdown format.
4. **Documentation Scraping**: Fetch the contents of a tutorial or documentation page for offline reading.
5. **Content Monitoring**: Automatically extract the text from a specific webpage for updates.
6. **Data Processing**: Parse the HTML of an arbitrary HTTP/HTTPS URL to structure its content.

FILE:scripts/web_search_scraper_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "85961818557645714"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_task(api_key, target_url):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "target_url", "value": target_url}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python web_search_scraper_api.py <target_url>", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    target_url = sys.argv[1]
    
    result = run_task(api_key, target_url)
    if result:
        print(result, flush=True)

---
name: youtube-influencer-finder-api-skill
description: This skill helps users extract YouTube influencer profiles including social links, subscriber counts, and channel stats via the BrowserAct API. Agent should proactively apply this skill when users express needs like finding YouTube creators for specific keywords, discovering influencers for a marketing campaign, extracting YouTube channel contact emails, scraping YouTube influencer social media links, gathering subscriber counts for YouTube creators, researching top YouTube channels in a specific niche, compiling a list of YouTube content creators with recent uploads, collecting YouTube creator profiles for outreach, extracting total views and video counts for specific YouTube influencers, building a database of YouTube partners for market research, finding YouTube influencers who uploaded videos this month, or monitoring competitor influencer activities on YouTube.
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# YouTube Influencer Finder API Skill

## 📖 Brief
This skill provides a one-stop YouTube influencer data extraction service using the BrowserAct YouTube Influencer Finder API template. It directly extracts structured creator profile data from YouTube search results, including contact details, social links, and channel statistics. Just input search keywords and an upload date filter to get clean, usable influencer data.

## ✨ Features
1. **No hallucinations, ensuring stable and accurate data extraction**: Pre-set workflows avoid generative AI hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP restrictions or geo-blocking**: No need to deal with regional IP limits.
4. **Faster execution**: Tasks execute faster compared to purely AI-driven browser automation solutions.
5. **Extremely high cost-efficiency**: Significantly reduces data acquisition costs compared to AI solutions that consume massive amounts of tokens.

## 🔑 API Key Guide
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take other actions first; you should ask and wait for the user to provide it.
**Agent must inform the user**:
> "Since you haven't configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key."

## 🛠️ Input Parameters
When calling the script, the Agent should flexibly configure the following parameters based on user needs:

1. **keywords**
   - **Type**: `string`
   - **Description**: Search keywords for finding YouTube influencers. Can be any keyword.
   - **Example**: `openclaw`, `tech reviewer`, `gaming`
   - **Default**: `openclaw`

2. **Upload_Date**
   - **Type**: `string`
   - **Description**: Filter creators by their recent upload date.
   - **Options**:
     - `Today`
     - `This Week`
     - `This Month`
     - `This Year`
   - **Default**: `This Month`

## 🚀 Invocation Method (Recommended)
The Agent should execute the following independent script to achieve "one command gets results":

```bash
# Example invocation
python -u ./scripts/youtube_influencer_finder_api.py "keywords" "Upload_Date"
```

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output status logs with timestamps** while running (e.g., `[14:30:05] Task Status: running`).
**Agent guidelines**:
- While waiting for the script to return results, please keep an eye on the terminal output.
- As long as the terminal continues to output new status logs, it means the task is running normally. Do not misjudge it as a deadlock or unresponsiveness.
- If the status remains unchanged for a long time or the script stops outputting without returning a result, only then consider triggering the retry mechanism.

## 📊 Data Output
After successful execution, the script will parse and print the results directly from the API response. The results include:
- `total_views`: Total channel views
- `video_count`: Total number of videos
- `subscriber_count`: Total subscriber count
- `registration_date`: Channel registration date
- `country`: Creator's country/region
- `youtube_channel`: Direct link to YouTube channel
- `email_action`: Contact email if available
- `link`: All visible social links (Platform: URL format, multiple links separated by line breaks)
- `profile_description`: Channel description and bio
- `profile_name`: Creator's channel name

## ⚠️ Error Handling & Retry
During script execution, if errors occur (such as network fluctuations or task failure), the Agent should follow this logic:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. At this point, **do not retry**, but guide the user to recheck and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task fails (for example, the output starts with `Error:` or returns an empty result), the Agent should **automatically try to run the script once more**.

2. **Retry limit**:
   - Automatic retry is limited to **once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

FILE:scripts/youtube_influencer_finder_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "85430137964765321"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_youtube_influencer_task(api_key, keywords, upload_date="This Month"):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "keywords", "value": keywords},
            {"name": "Upload_Date", "value": upload_date}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python youtube_influencer_finder_api.py <keywords> [upload_date]", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    keywords = sys.argv[1]
    upload_date = sys.argv[2] if len(sys.argv) > 2 else "This Month"
    
    result = run_youtube_influencer_task(api_key, keywords, upload_date)
    if result:
        print(result, flush=True)

---
name: reddit-competitor-analysis-api-skill
description: "This skill helps users extract structured data from Reddit posts and comments via BrowserAct API. Agent should proactively apply this skill when users express needs like analyzing competitor mentions on Reddit, tracking brand sentiment in Reddit comments, extracting Reddit discussions for market research, finding popular Reddit posts by keywords, monitoring community feedback on specific topics, gathering user reviews from Reddit threads, searching for Reddit posts within a specific date range, sorting Reddit discussions by relevance or hotness, compiling nested Reddit comments for deep analysis, building a structured dataset of Reddit conversations, discovering trending topics in specific subreddits, or monitoring social media activity for specific brands on Reddit."
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python3"],"env":["BROWSERACT_API_KEY"]}}}
---

# Reddit Competitor Analysis API Skill

## 📖 Introduction
This skill uses the BrowserAct Reddit Competitor Analysis API template to provide users with a one-stop Reddit data collection service. It can extract full post details and comments from Reddit search results. Just input search keywords and filtering conditions to directly get clean and usable Reddit data.

## ✨ Features
1. **No hallucinations, ensuring stable and precise data extraction**: Pre-set workflows avoid AI generative hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP access restrictions or geofencing**: No need to handle regional IP limitations.
4. **Faster execution**: Compared to pure AI-driven browser automation solutions, task execution is faster.
5. **Extremely high cost-effectiveness**: Significantly reduces data acquisition costs compared to highly token-consuming AI solutions.

## 🔑 API Key Guide
Before running, you must check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take any other actions; you should request and wait for the user to provide it collaboratively.
**The Agent must inform the user at this time**:
> "Since you have not configured the BrowserAct API Key, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key first."

## 🛠️ Input Parameters
When calling the script, the Agent should flexibly configure the following parameters based on user needs:

1. **Keywords (Search keywords)**
   - **Type**: `string`
   - **Description**: Search keywords for Reddit posts.
   - **Example**: `openclaw`

2. **Publication_date (Publication date)**
   - **Type**: `string`
   - **Description**: Filter posts by publication date range.
   - **Options**: `All time`, `Past year`, `Past month`, `Past week`, `Today`, `Past hour`
   - **Default**: `Past week`

3. **Post_sort_by (Search sort)**
   - **Type**: `string`
   - **Description**: Sort Reddit post search results by selected criteria.
   - **Options**: `Relevance`, `Hot`, `Top`, `New`, `Comment count`
   - **Default**: `Relevance`

4. **Comment_sort_by (Comment sort)**
   - **Type**: `string`
   - **Description**: Sort extracted comments by.
   - **Options**: `Best`, `Top`, `New`, `Controversial`, `Q&A`
   - **Default**: `Best`

5. **Data_limit (Comments per post)**
   - **Type**: `number`
   - **Description**: Maximum number of comments to extract per post.
   - **Default**: `10`

## 🚀 Usage (Recommended)
The Agent should execute the following independent script to achieve "one-line command to get results". Note that the script path `./scripts/...` is relative to this skill's directory:

```bash
# Example invocation
python3 -u ./scripts/reddit_competitor_analysis_api.py "keywords" "publication_date" "post_sort_by" "comment_sort_by" data_limit
```

### ⏳ Task Status Monitoring
Since this task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output status logs with timestamps** (e.g., `[14:30:05] Task Status: running`) while running.
**Agent Must Know**:
- While waiting for the script to return results, please keep an eye on the terminal output.
- As long as the terminal is still outputting new status logs, it means the task is running normally. Please do not mistakenly judge it as a deadlock or unresponsiveness.
- Only if the status remains unchanged for a long time or the script stops outputting and no result is returned, you can consider triggering the retry mechanism.

## 🔧 OpenClaw Adaptation Guide
Since BrowserAct tasks may take a long time to run (5-20 minutes), when the Agent executes in the OpenClaw environment, it needs to:

1. **Run in background mode (using JSON parameters for `exec` tool):**
   - `command`: `"python3 -u ./scripts/reddit_competitor_analysis_api.py ..."`
   - `background`: `true`
   - `timeout`: `1800`

2. **Or increase yieldMs:**
   - `command`: `"python3 -u ./scripts/reddit_competitor_analysis_api.py ..."`
   - `yieldMs`: `600000`
   - `timeout`: `1800`

3. **Use process poll to monitor:**
   - `action`: `"poll"`
   - `sessionId`: `"xxx"`
   - `timeout`: `300000`

## 📊 Data Output Description
After successful execution, the script will directly parse and print the results from the API response. The results include:
- `post_title`: Full post title
- `publish_time`: Post publication time
- `like_count`: Number of upvotes on the post
- `comment_count`: Total number of comments
- `publish_channel`: Subreddit where the post was published
- `comment_author`: Username of the commenter
- `comment_time_utc`: Comment timestamp
- `comments`: Full comment text
- `comment_upvotes`: Number of upvotes on the comment
- `comment_level`: Nesting level of the comment
- `comment_author_url`: Link to the commenter's profile
- `reply_to`: Parent comment or post being replied to

## ⚠️ Error Handling & Retry
During the execution of the script, if an error occurs (such as network fluctuation or task failure), the Agent should follow this logic:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. At this time, **do not retry**, but guide the user to recheck and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (for example, the output starts with `Error:` or the returned result is empty), the Agent should **automatically try to execute the script again**.

2. **Retry limit**:
   - Automatic retry is limited to **one time**. If the second attempt still fails, stop retrying and report the specific error message to the user.

FILE:scripts/reddit_competitor_analysis_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "85401899001481609"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_reddit_competitor_analysis_task(api_key, keywords, publication_date="Past week", post_sort_by="Relevance", comment_sort_by="Best", data_limit=10):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "KeyWords", "value": keywords},
            {"name": "publication_date", "value": publication_date},
            {"name": "Relevance", "value": post_sort_by},
            {"name": "Sort_by", "value": comment_sort_by},
            {"name": "Datelimit", "value": str(data_limit)}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python3 reddit_competitor_analysis_api.py <keywords> [publication_date] [post_sort_by] [comment_sort_by] [data_limit]", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    keywords = sys.argv[1]
    publication_date = sys.argv[2] if len(sys.argv) > 2 else "Past week"
    post_sort_by = sys.argv[3] if len(sys.argv) > 3 else "Relevance"
    comment_sort_by = sys.argv[4] if len(sys.argv) > 4 else "Best"
    data_limit = sys.argv[5] if len(sys.argv) > 5 else 10
    
    result = run_reddit_competitor_analysis_task(api_key, keywords, publication_date, post_sort_by, comment_sort_by, data_limit)
    if result:
        print(result, flush=True)

---
name: amazon-best-selling-products-finder-api-skill
description: "This skill helps users extract structured best-selling product data from Amazon via the BrowserAct API. Agent should proactively apply this skill when users express needs like search for best selling products on Amazon, extract Amazon product data based on keywords, find top rated Amazon products, monitor Amazon competitor prices and sales, discover trending products on Amazon marketplace, extract Amazon product titles prices and ratings, gather Amazon product sales volume for market research, search Amazon best sellers in specific region, collect Amazon product reviews and promotion details, analyze Amazon product availability and badges, get Amazon product data for market analysis."
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["python"],"env":["BROWSERACT_API_KEY"]}}}
---

# Amazon Best Selling Products Finder API Skill

## 📖 Skill Introduction
This skill provides users with a one-stop product data extraction service using the BrowserAct Amazon Best Selling Products Finder API template. It can directly extract structured best-selling product data from Amazon. By inputting search keywords, data limit, and marketplace URL, you can easily get clean and usable product data including titles, prices, ratings, reviews, sales volume, and promotional details.

## ✨ Features
1. **No hallucinations, ensuring stable and precise data extraction**: Preset workflows avoid AI generative hallucinations.
2. **No CAPTCHA issues**: No need to handle reCAPTCHA or other verification challenges.
3. **No IP access restrictions and geofencing**: No need to handle regional IP restrictions.
4. **More agile execution speed**: Compared to pure AI-driven browser automation solutions, task execution is faster.
5. **Extremely high cost-effectiveness**: Significantly reduces data acquisition costs compared to AI solutions that consume a large number of Tokens.

## 🔑 API Key Guide Flow
Before running, first check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take other actions; require and wait for the user to collaborate to provide it.
**The Agent must inform the user at this time**:
> "Since you have not configured the BrowserAct API Key yet, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key."

## 🛠️ Input Parameters
When calling the script, the Agent should flexibly configure the following parameters based on user needs:

1. **KeyWords**
   - **Type**: `string`
   - **Description**: Search keywords used to find Amazon products.
   - **Example**: `iphone 17 pro max`, `gaming mouse`, `running shoes`

2. **Date_limit**
   - **Type**: `number`
   - **Description**: Maximum number of products to extract.
   - **Default**: `10`
   - **Recommendation**: Set to a lower number for quick checks, or higher for comprehensive analysis.

3. **Marketplace_url**
   - **Type**: `string`
   - **Description**: Amazon marketplace URL for region-specific searches.
   - **Default**: `https://www.amazon.com`
   - **Example**: `https://www.amazon.co.uk`, `https://www.amazon.de`

## 🚀 Call Method (Recommended)
The Agent should execute the following standalone script to achieve "one command to get results":

```bash
# Call example
python -u ./scripts/amazon_best_selling_products_finder_api.py "search keywords" limit "marketplace_url"
```

### ⏳ Running Status Monitoring
Since this task involves automated browser operations, it may take a long time (several minutes). The script will **continuously output status logs with timestamps** (e.g. `[14:30:05] Task Status: running`) during execution.
**Agent notice**:
- While waiting for the script to return the result, please keep an eye on the terminal output.
- As long as the terminal is still outputting new status logs, it means the task is running normally. Please do not mistakenly judge it as a deadlock or unresponsive.
- If the status remains unchanged for a long time or the script stops outputting and no result is returned, the retry mechanism can be triggered.

## 📊 Data Output Description
After successful execution, the script will parse and print the result directly from the API response. The result contains:
- `title`: Product title
- `brand`: Brand name
- `list_price`: Original list price
- `current_price`: Current selling price
- `star_rating`: Average star rating
- `review_count`: Total review count
- `past_month_sales`: Sales volume in the past month
- `availability`: Stock status
- `promotion`: Promotional offers
- `asin`: Amazon Standard Identification Number
- `category`: Product category
- `badge`: Badges like Amazon's Choice
- `product_url`: Direct link to the product

## ⚠️ Error Handling & Retry Mechanism
During the execution of the script, if an error occurs (such as network fluctuation or task failure), the Agent should follow this logic:

1. **Check the output content**:
   - If the output **contains** `"Invalid authorization"`, it means the API Key is invalid or expired. At this time, **do not retry**, and guide the user to recheck and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (for example, the output starts with `Error:` or the returned result is empty), the Agent should **automatically try to execute the script again once**.

2. **Retry limit**:
   - Automatic retry is limited to **once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

## 🌟 Typical Use Cases
1. **Market Research**: Extract product listings and ratings to analyze the current market for specific keywords.
2. **Competitor Analysis**: Monitor competitor pricing, discounts, and sales volume over time.
3. **Trending Products Discovery**: Find the best-selling and highly rated products within a specific category.
4. **Price Monitoring**: Track current prices and list prices to optimize purchasing strategies.
5. **Cross-Region Analysis**: Compare product availability and pricing across different Amazon marketplaces.

FILE:scripts/amazon_best_selling_products_finder_api.py
import os
import time
import requests
import json
import sys
import datetime
import io

# Force UTF-8 encoding for standard output and error streams
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

# API Configuration
TEMPLATE_ID = "85569073892601737"
API_BASE_URL = "https://api.browseract.com/v2/workflow"

def run_amazon_best_selling_products_finder_task(api_key, keywords, limit=10, marketplace_url="https://www.amazon.com"):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {
        "workflow_template_id": TEMPLATE_ID,
        "input_parameters": [
            {"name": "KeyWords", "value": keywords},
            {"name": "Date_limit", "value": str(limit)},
            {"name": "Marketplace_url", "value": marketplace_url}
        ]
    }

    # 1. Start Task
    print(f"Start Task", flush=True)
    try:
        res = requests.post(f"{API_BASE_URL}/run-task-by-template", json=payload, headers=headers).json()
    except Exception as e:
        print(f"Error: Connection to API failed - {e}", flush=True)
        return None

    if "id" not in res:
        print(f"Error: Could not start task. Response: {res}", flush=True)
        return None
    
    task_id = res["id"]
    print(f"Task started. ID: {task_id}", flush=True)
    
    # 2. Poll for Completion
    while True:
        try:
            status_res = requests.get(f"{API_BASE_URL}/get-task-status?task_id={task_id}", headers=headers).json()
            status = status_res.get("status")
            
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Task Status: {status}", flush=True)
            
            if status == "finished":
                print(f"[{timestamp}] Task finished successfully.", flush=True)
                break
            elif status in ["failed", "canceled"]:
                print(f"Error: Task {status}. Please check your BrowserAct dashboard.", flush=True)
                return None
        except Exception as e:
            timestamp = datetime.datetime.now().strftime("%H:%M:%S")
            print(f"[{timestamp}] Polling error: {e}. Retrying...", flush=True)
            
        time.sleep(10)
    
    # 3. Get Results
    try:
        task_info = requests.get(f"{API_BASE_URL}/get-task?task_id={task_id}", headers=headers).json()
        
        # Extract data from output["string"] as requested
        # Usually task_info['output']['string'] contains the result
        output = task_info.get("output", {})
        result_string = output.get("string")
        
        if result_string:
            return result_string
        else:
            return json.dumps(task_info, ensure_ascii=False)
    except Exception as e:
        print(f"Error: Failed to retrieve results - {e}", flush=True)
        return None

if __name__ == "__main__":
    # Prioritize command line API key, then environment variable
    api_key = os.getenv("BROWSERACT_API_KEY")
    
    if len(sys.argv) < 2:
        print("Usage: python amazon_best_selling_products_finder_api.py <keywords> [limit] [marketplace_url]", flush=True)
        sys.exit(1)
        
    if not api_key:
        print("\n[!] ERROR: BrowserAct API Key is missing.", flush=True)
        print("Please follow these steps:", flush=True)
        print("1. Go to: https://www.browseract.com/reception/integrations", flush=True)
        print("2. Copy your API Key.", flush=True)
        print("3. Provide it to me or set it as an environment variable (BROWSERACT_API_KEY).", flush=True)
        sys.exit(1)
        
    keywords = sys.argv[1]
    limit = sys.argv[2] if len(sys.argv) > 2 else 10
    marketplace_url = sys.argv[3] if len(sys.argv) > 3 else "https://www.amazon.com"
    
    result = run_amazon_best_selling_products_finder_task(api_key, keywords, limit, marketplace_url)
    if result:
        print(result, flush=True)