x-collect-skill 1.0.2 → 2.1.0

package/README.md

@@ -18,7 +18,7 @@
 
 English | [中文](./README.zh-CN.md)
 
-X/Twitter topic intelligence skill for Claude Code. Uses Playwright browser automation to search x.com directly, scraping real tweets with engagement metrics.
+X/Twitter topic intelligence skill for Claude Code. Uses Actionbook browser automation to search x.com directly, scraping real tweets with engagement metrics.
 
 ## What it does
 
@@ -40,13 +40,18 @@ Output: JSONL + Markdown in `./x-collect-data/` with real handles, tweet text, l
 | Dependency | Purpose | Required |
 |------------|---------|----------|
 | [Claude Code](https://claude.ai/claude-code) | Runtime | Yes |
-| [Playwright MCP](https://github.com/microsoft/playwright-mcp) | Browser automation | Yes |
-| Logged-in X/Twitter session | Browser must have x.com logged in | Yes |
+| [Actionbook CLI](https://actionbook.dev) | Browser automation (`actionbook` command) | Yes |
+| Actionbook Chrome Extension | Controls user's existing Chrome browser | Yes |
+| Logged-in X/Twitter session | Chrome must have x.com logged in | Yes |
 
-### Install Playwright MCP
+### Setup Actionbook Extension
+
+Follow the official guide: **[Actionbook Installation](https://actionbook.dev/docs/guides/installation)**
 
 ```bash
-claude mcp add --scope user playwright -- npx @playwright/mcp@latest
+actionbook extension install           # install extension files
+# Then load unpacked extension in Chrome (chrome://extensions)
+actionbook extension serve             # start bridge (keep running)
 ```
 
 ## Install
@@ -130,14 +135,15 @@ Data saved to `./x-collect-data/`:
 
 ## How it works
 
-The skill uses Playwright MCP to:
-1. Navigate to x.com search pages with Top tab and various filters
-2. Wait for tweets to load
-3. Extract tweet data via DOM queries or accessibility tree snapshot
-4. Deduplicate by tweet URL
-5. Output JSONL + Markdown with Content Opportunity Summary
+The skill uses Actionbook Extension mode to:
+1. Control the user's Chrome browser (with existing x.com login)
+2. Navigate to x.com search pages with Top tab and various filters
+3. Wait for tweets to load
+4. Extract tweet data via JavaScript evaluation
+5. Deduplicate by tweet URL
+6. Output JSONL + Markdown with Content Opportunity Summary
 
-No third-party API needed — reads directly from x.com via Playwright browser automation.
+No third-party API needed — reads directly from x.com via Actionbook browser automation.
 
 ## Community
 

package/README.zh-CN.md

@@ -18,7 +18,7 @@
 
 [English](./README.md) | 中文
 
-X/Twitter 话题情报采集工具，Claude Code 专用 Skill。通过 Playwright 浏览器自动化直接搜索 x.com，抓取真实推文和互动数据。
+X/Twitter 话题情报采集工具，Claude Code 专用 Skill。通过 Actionbook 浏览器自动化直接搜索 x.com，抓取真实推文和互动数据。
 
 ## 功能
 
@@ -40,13 +40,18 @@ X/Twitter 话题情报采集工具，Claude Code 专用 Skill。通过 Playwrigh
 | 依赖 | 用途 | 必需 |
 |------|------|------|
 | [Claude Code](https://claude.ai/claude-code) | 运行环境 | 是 |
-| [Playwright MCP](https://github.com/microsoft/playwright-mcp) | 浏览器自动化 | 是 |
-| 已登录的 X/Twitter 会话 | 浏览器需已登录 x.com | 是 |
+| [Actionbook CLI](https://actionbook.dev) | 浏览器自动化（`actionbook` 命令） | 是 |
+| Actionbook Chrome 扩展 | 控制用户已有的 Chrome 浏览器 | 是 |
+| 已登录的 X/Twitter 会话 | Chrome 需已登录 x.com | 是 |
 
-### 安装 Playwright MCP
+### 安装 Actionbook 扩展
+
+请先按照官方指南完成安装：**[Actionbook 安装指南](https://actionbook.dev/docs/guides/installation)**
 
 ```bash
-claude mcp add --scope user playwright -- npx @playwright/mcp@latest
+actionbook extension install           # 安装扩展文件
+# 然后在 Chrome 中加载未打包扩展 (chrome://extensions)
+actionbook extension serve             # 启动桥接（保持运行）
 ```
 
 ## 安装
@@ -130,14 +135,15 @@ cp x-collect/SKILL.md ~/.claude/skills/x-collect/
 
 ## 工作原理
 
-通过 Playwright MCP 浏览器自动化：
-1. 导航到 x.com 搜索页（Top 标签页 + 各种过滤条件）
-2. 等待推文加载
-3. 通过 DOM 查询或无障碍树快照提取推文数据
-4. 按推文 URL 去重
-5. 输出 JSONL + Markdown，附带内容机会分析
+通过 Actionbook Extension 模式浏览器自动化：
+1. 控制用户的 Chrome 浏览器（使用已有的 x.com 登录状态）
+2. 导航到 x.com 搜索页（Top 标签页 + 各种过滤条件）
+3. 等待推文加载
+4. 通过 JavaScript 执行提取推文数据
+5. 按推文 URL 去重
+6. 输出 JSONL + Markdown，附带内容机会分析
 
-无需第三方 API，直接通过 Playwright 浏览器自动化读取 x.com。
+无需第三方 API，直接通过 Actionbook 浏览器自动化读取 x.com。
 
 ## 社区
 

package/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: x-collect
 description: |
-  X/Twitter topic intelligence tool. Uses Playwright browser automation to search
-  x.com directly, scraping real tweets, engagement metrics, and KOL accounts.
+  X/Twitter topic intelligence tool. Two search modes: Grok (quick AI-powered search)
+  and Actionbook DOM scraping (detailed multi-round collection with search operators).
   Outputs a structured intel report (JSONL + Markdown) with content opportunity analysis.
   Use when the user wants to research a topic on X/Twitter, find what's performing,
   or scout trending discussions before creating content.
@@ -15,27 +15,18 @@ allowed-tools:
   - Glob
   - Grep
   - AskUserQuestion
-  - mcp__playwright__browser_navigate
-  - mcp__playwright__browser_snapshot
-  - mcp__playwright__browser_take_screenshot
-  - mcp__playwright__browser_run_code
-  - mcp__playwright__browser_click
-  - mcp__playwright__browser_type
-  - mcp__playwright__browser_wait_for
-  - mcp__playwright__browser_press_key
-  - mcp__playwright__browser_tabs
 ---
 
 # X Topic Intelligence
 
-Research what's trending and performing on X/Twitter for any topic. Browse x.com directly via Playwright browser automation to find real tweets, engagement data, and KOL accounts.
+Research what's trending and performing on X/Twitter for any topic. Two search backends available — pick based on the task complexity.
 
 ---
 
 ## Usage
 
 ```
-/x-collect [topic]        # direct mode
+/x-collect [topic]        # auto-select mode based on topic complexity
 /x-collect                # interactive mode - asks for topic
 ```
 
@@ -44,100 +35,213 @@ When no topic is provided, use `AskUserQuestion`:
 
 ---
 
+## Search Mode Selection
+
+| | Grok Mode (quick) | Actionbook Scrape Mode (full) |
+|---|---|---|
+| **Speed** | ~60s single query | ~5-10 min multi-round |
+| **Best for** | Quick overview, trend check, "what's hot" | Systematic collection, precise metrics, dataset building |
+| **Data quality** | AI-summarized, may miss some posts | Raw DOM data, exact engagement numbers, includes views |
+| **Search operators** | No (natural language only) | Yes (`min_faves:`, `filter:blue_verified`, date ranges, etc.) |
+| **Output** | 5-15 posts per query | 10-15 posts per round, 3-5 rounds |
+| **Views count** | Not available | Available |
+
+### Auto-selection rules
+
+Use **Grok Mode** when:
+- User asks a simple question ("what's trending about X?", "find popular posts about Y")
+- Quick exploration / first look at a topic
+- Single broad query is sufficient
+- User explicitly says "quick" or "fast"
+
+Use **Actionbook Scrape Mode** when:
+- User wants systematic multi-round collection (viral + trending + KOL + hook study)
+- Need precise engagement thresholds (`min_faves:100`, `filter:blue_verified`)
+- Need views count
+- Building a JSONL dataset for later analysis
+- User explicitly says "detailed", "full", or "all rounds"
+
+> When unsure, default to **Grok Mode** — it's faster and sufficient for most requests. Escalate to Actionbook Scrape if Grok results are insufficient or user asks for more.
+
+---
+
 ## Prerequisites
 
 | Dependency | Purpose | Required |
 |------------|---------|----------|
 | Claude Code | Runtime | Yes |
-| Playwright MCP | Browser automation (`npx @playwright/mcp@latest`) | Yes |
-| Logged-in X/Twitter session | Browser must have an active x.com session | Yes |
+| Actionbook CLI | Browser automation (`actionbook` command) | Yes |
+| Actionbook Extension | Chrome extension + bridge for controlling user's browser | Yes |
+| Logged-in X/Twitter session | User's Chrome must have an active x.com session | Yes |
+| X Premium (for Grok) | Grok search requires Premium subscription | Only for Grok Mode |
+
+### Pre-flight Check
+
+Before starting any round, verify the extension bridge is running:
+
+```bash
+actionbook extension ping
+```
+
+If not connected, inform the user:
+> "Actionbook extension bridge is not running. Please run `actionbook extension serve` in a terminal and ensure the Chrome extension is connected."
 
 ---
 
-## Browser Automation Flow
+## Grok Mode (Quick Search)
 
-Use Playwright MCP tools to navigate x.com, perform searches, and extract tweet data.
+Ask Grok on x.com to search X and return structured results. One query, ~60 seconds.
 
-### General Steps (repeat for each search round)
+### Grok Workflow
 
-1. **Navigate** — `browser_navigate` to the x.com search URL
-2. **Wait** — `browser_wait_for` until tweets appear (wait for text like "Like" or a few seconds)
-3. **Extract** — `browser_run_code` to run Playwright JS that scrapes tweet data from the DOM
-4. **Scroll + Extract more** — if fewer than 10 tweets, scroll down and extract again
+#### 1. Navigate to Grok
 
-### Tweet Extraction Script
+```bash
+actionbook --extension browser open "https://x.com/i/grok"
+```
 
-Use `browser_run_code` with this Playwright script to extract tweets:
-
-```javascript
-async (page) => {
-  const extractTweets = () => {
-    const tweets = document.querySelectorAll('article[data-testid="tweet"]');
-    return Array.from(tweets).slice(0, 20).map(t => {
-      // Handle
-      const nameEl = t.querySelector('[data-testid="User-Name"]');
-      const handleLink = nameEl?.querySelector('a[href^="/"][tabindex="-1"]');
-      const handle = handleLink?.getAttribute('href')?.replace('/', '') || null;
-      const displayName = nameEl?.querySelector('a span')?.innerText || null;
-
-      // Text
-      const text = t.querySelector('[data-testid="tweetText"]')?.innerText || '';
-
-      // Timestamp & link
-      const timeEl = t.querySelector('time');
-      const time = timeEl?.getAttribute('datetime') || null;
-      const tweetLink = timeEl?.closest('a')?.getAttribute('href') || null;
-
-      // Engagement: reply, retweet, like counts + views
-      const replyCount = t.querySelector('[data-testid="reply"] span')?.innerText || '0';
-      const retweetCount = t.querySelector('[data-testid="retweet"] span')?.innerText || '0';
-      const likeCount = t.querySelector('[data-testid="like"] span')?.innerText || '0';
-      // Views are in an aria-label on the analytics link
-      const viewsEl = t.querySelector('a[href*="/analytics"]');
-      const viewsLabel = viewsEl?.getAttribute('aria-label') || '';
-      const viewsMatch = viewsLabel.match(/([\d,.]+[KMB]?)\s*view/i);
-      const views = viewsMatch ? viewsMatch[1] : '0';
-
-      return {
-        handle: handle ? '@' + handle : null,
-        display_name: displayName,
-        text: text.substring(0, 200),
-        posted_at: time,
-        url: tweetLink ? 'https://x.com' + tweetLink : null,
-        replies: replyCount,
-        retweets: retweetCount,
-        likes: likeCount,
-        views: views
-      };
-    }).filter(t => t.text && t.handle);
-  };
-
-  // 1. Extract BEFORE scrolling (captures high-engagement first-screen tweets)
-  const initial = await page.evaluate(extractTweets);
-
-  // 2. Scroll down in steps to load more
-  for (let i = 0; i < 3; i++) {
-    await page.evaluate(() => window.scrollBy(0, 1500));
-    await page.waitForTimeout(1500);
-  }
+Wait 4 seconds for page load, then verify textarea exists:
+
+```bash
+actionbook --extension browser eval "document.querySelector('textarea') ? 'ready' : 'not_ready'"
+```
+
+> Use `browser open` (new tab) instead of `browser goto` to avoid "Cannot access chrome:// URL" errors.
 
-  // 3. Extract again after scrolling
-  const afterScroll = await page.evaluate(extractTweets);
+#### 2. Input the Question
+
+Craft a Grok prompt that returns structured data. Template:
+
+```
+Search X for the most popular posts about [TOPIC] in the past [TIME_RANGE]. Show me the top [N] posts with the most engagement (likes + retweets). For each post, include: the author handle, post text, likes count, retweets count, and the post URL.
+```
+
+Set the value via JS (React state-safe):
+
+```bash
+actionbook --extension browser eval "
+  var textarea = document.querySelector('textarea');
+  if (textarea) {
+    var setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
+    setter.call(textarea, 'YOUR GROK PROMPT HERE');
+    textarea.dispatchEvent(new Event('input', { bubbles: true }));
+    'ok'
+  } else { 'no_textarea' }
+"
+```
 
-  // 4. Deduplicate by URL
-  const seen = new Set();
-  const all = [];
-  for (const t of [...initial, ...afterScroll]) {
-    if (t.url && !seen.has(t.url)) {
-      seen.add(t.url);
-      all.push(t);
+#### 3. Send the Question
+
+```bash
+actionbook --extension browser eval "
+  var btns = document.querySelectorAll('button');
+  var sent = false;
+  for (var i = 0; i < btns.length; i++) {
+    var svg = btns[i].querySelector('svg');
+    var rect = btns[i].getBoundingClientRect();
+    if (svg && rect.width > 20 && rect.width < 60 && rect.height > 20 && rect.height < 60 && rect.x > 600) {
+      btns[i].click();
+      sent = true;
+      break;
     }
   }
-  return all;
-}
+  sent ? 'sent' : 'not_found'
+"
 ```
 
-> **Note**: X's DOM structure may change. If the selectors break, use `browser_snapshot` to read the accessibility tree and extract data manually, or use `browser_take_screenshot` to visually inspect the page and adjust selectors.
+If `not_found`, take a screenshot (`actionbook --extension browser screenshot`) and debug visually.
+
+#### 4. Wait for Response
+
+Grok takes 10-60 seconds (longer when searching X). Poll every 8 seconds:
+
+```bash
+actionbook --extension browser eval "document.querySelector('main') ? document.querySelector('main').innerText.length : 0"
+```
+
+Response is ready when length > 500. Timeout after 90 seconds and extract whatever is available.
+
+#### 5. Extract Response
+
+```bash
+actionbook --extension browser eval "document.querySelector('main').innerText"
+```
+
+#### 6. Parse into JSONL Schema
+
+Parse Grok's text response and map each post to the standard JSONL schema. For fields Grok doesn't provide:
+- `views`: set to `"0"` (Grok doesn't return views)
+- `replies`: set to `0` if not provided
+- `posted_at`: set to `null` if not provided
+- `angle` and `key_takeaway`: analyze and fill in yourself
+- `format`: infer from text length and content (`thread` if mentions thread/continues, else `single`)
+
+---
+
+## Actionbook Scrape Mode (Full Collection)
+
+Use Actionbook Extension mode to control the user's Chrome browser, navigate x.com search, and extract tweet data directly from the DOM.
+
+### General Steps (repeat for each search round)
+
+1. **Navigate** — `actionbook --extension browser goto "<search-url>"` to the x.com search URL
+2. **Wait** — `sleep 3` then `actionbook --extension browser wait "article[data-testid='tweet']"` until tweets appear
+3. **Extract** — `actionbook --extension browser eval "<JS>"` to run extraction script
+4. **Scroll + Extract more** — if fewer than 10 tweets, scroll and extract again
+
+### Tweet Extraction Script
+
+Use `actionbook --extension browser eval` with this JS to extract tweets:
+
+```bash
+actionbook --extension browser eval "
+(function() {
+  var tweets = document.querySelectorAll('article[data-testid=\"tweet\"]');
+  return Array.from(tweets).slice(0, 20).map(function(t) {
+    var nameEl = t.querySelector('[data-testid=\"User-Name\"]');
+    var handleLink = nameEl ? nameEl.querySelector('a[href^=\"/\"][tabindex=\"-1\"]') : null;
+    var handle = handleLink ? handleLink.getAttribute('href').replace('/', '') : null;
+    var displayName = nameEl ? (nameEl.querySelector('a span') || {}).innerText || null : null;
+    var textEl = t.querySelector('[data-testid=\"tweetText\"]');
+    var text = textEl ? textEl.innerText : '';
+    var timeEl = t.querySelector('time');
+    var time = timeEl ? timeEl.getAttribute('datetime') : null;
+    var linkEl = timeEl ? timeEl.closest('a') : null;
+    var tweetLink = linkEl ? linkEl.getAttribute('href') : null;
+    var replyCount = (t.querySelector('[data-testid=\"reply\"] span') || {}).innerText || '0';
+    var retweetCount = (t.querySelector('[data-testid=\"retweet\"] span') || {}).innerText || '0';
+    var likeCount = (t.querySelector('[data-testid=\"like\"] span') || {}).innerText || '0';
+    var viewsEl = t.querySelector('a[href*=\"/analytics\"]');
+    var viewsLabel = viewsEl ? viewsEl.getAttribute('aria-label') || '' : '';
+    var viewsMatch = viewsLabel.match(/([\d,.]+[KMB]?)\s*view/i);
+    var views = viewsMatch ? viewsMatch[1] : '0';
+    return {
+      handle: handle ? '@' + handle : null,
+      display_name: displayName,
+      text: text.substring(0, 200),
+      posted_at: time,
+      url: tweetLink ? 'https://x.com' + tweetLink : null,
+      replies: replyCount, retweets: retweetCount, likes: likeCount, views: views
+    };
+  }).filter(function(t) { return t.text && t.handle; });
+})()
+"
+```
+
+### Scrolling to Load More Tweets
+
+```bash
+# Scroll down 1500px, wait, repeat 3 times
+actionbook --extension browser eval "window.scrollBy(0, 1500)"
+sleep 2
+actionbook --extension browser eval "window.scrollBy(0, 1500)"
+sleep 2
+actionbook --extension browser eval "window.scrollBy(0, 1500)"
+sleep 2
+# Then re-run extraction script above and deduplicate by URL
+```
+
+> **Note**: X's DOM structure may change. If selectors break, use `actionbook --extension browser snapshot` to read the accessibility tree, or `actionbook --extension browser screenshot` to visually inspect and adjust selectors.
 
 ---
 
@@ -194,10 +298,12 @@ Use these operators in the search URL `q=` parameter (URL-encoded). Combine free
 
 ---
 
-## Intelligence Gathering Rounds
+## Intelligence Gathering Rounds (Actionbook Scrape Mode)
 
 Run 3 core rounds + optional bonus rounds. All queries include `-filter:replies -filter:nativeretweets` by default to eliminate noise and surface only original content.
 
+> **Grok Mode alternative**: If using Grok Mode, skip these rounds entirely. Instead, craft 1-3 targeted Grok prompts covering the same ground (e.g., "top viral posts about [topic]", "trending [topic] posts in last 24h", "which verified accounts are posting about [topic]").
+
 ### Core Rounds
 
 #### Round 1: Top / Viral Posts
@@ -360,7 +466,7 @@ Based on the N tweets above:
 After collection, display:
 
 ```
-X Intelligence for "[topic]" — [N] tweets collected:
+X Intelligence for "[topic]" — [N] tweets collected (via [Grok / Actionbook Scrape]):
   Top / viral:          X
   Trending (24h):       Y
   KOL / verified:       Z

package/bin/install.js

@@ -19,5 +19,8 @@ console.log(`Installed ${SKILL_NAME} skill to ${SKILL_DIR}/SKILL.md`);
 console.log("");
 console.log("Usage: /x-collect [topic]");
 console.log("");
-console.log("Prerequisite: Playwright MCP must be configured in Claude Code.");
-console.log("  claude mcp add --scope user playwright -- npx @playwright/mcp@latest");
+console.log("Prerequisite: Actionbook CLI and Chrome Extension must be installed.");
+console.log("  1. Install Actionbook CLI: https://actionbook.dev");
+console.log("  2. Run: actionbook extension install");
+console.log("  3. Load unpacked extension in Chrome (chrome://extensions)");
+console.log("  4. Start bridge: actionbook extension serve");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x-collect-skill",
-  "version": "1.0.2",
+  "version": "2.1.0",
   "description": "X/Twitter topic intelligence skill for Claude Code",
   "keywords": [
     "claude-code",
@@ -8,7 +8,7 @@
     "agent-skill",
     "twitter",
     "x-com",
-    "playwright"
+    "actionbook"
   ],
   "homepage": "https://github.com/SamCuipogobongo/x-collect",
   "repository": {