From 393e6e6c2645fe5648cb2e964f2b6a9238508484 Mon Sep 17 00:00:00 2001 From: kriptoburak Date: Sat, 23 May 2026 17:15:33 +0300 Subject: [PATCH] feat: add TweetClaw social intel skill --- README.md | 1 + SKILL.md | 1 + skills/lead-discovery/SKILL.md | 50 +++++++- skills/tweetclaw-social-intel/SKILL.md | 165 +++++++++++++++++++++++++ workspace/AGENTS.md | 8 +- workspace/HEARTBEAT.md | 6 +- workspace/TOOLS.md | 39 ++++++ 7 files changed, 259 insertions(+), 11 deletions(-) create mode 100644 skills/tweetclaw-social-intel/SKILL.md diff --git a/README.md b/README.md index b65618ffc3..5e23a0e587 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,7 @@ Pre-built capabilities that extend your AI SDR: | **telegram-toolkit** | Bot commands, inline keyboards, large file handling, and Telegram-first market strategies. | | **sdr-humanizer** | Rules for natural conversation — pacing, cultural adaptation, anti-patterns. | | **lead-discovery** | AI-driven lead discovery. Web search for potential buyers, ICP evaluation, CRM auto-entry. | +| **tweetclaw-social-intel** | Optional TweetClaw workflow for X/Twitter buying-signal search, user lookup, follower export research, monitors, and approved post/reply handoff. | | **quotation-generator** | Auto-generate PDF proforma invoices with company letterhead, multi-language support. | | **graphify** | Knowledge graph engine — map product relationships, customer intelligence, and market research into queryable graphs. Powered by [graphify](https://github.com/safishamsi/graphify). | diff --git a/SKILL.md b/SKILL.md index 92eafc1ea6..4bbea8b01e 100644 --- a/SKILL.md +++ b/SKILL.md @@ -54,6 +54,7 @@ Architecture: `tenant → wireproxy (SOCKS5, ~4MB) → WARP account → unique C - **sdr-humanizer** — Human-like conversation rules - **delivery-queue** — Async message delivery with retry - **lead-discovery** — AI-driven lead search and ICP scoring +- **tweetclaw-social-intel** — Optional X/Twitter buying-signal research with TweetClaw - **quotation-generator** — PDF proforma invoice generation - **chroma-memory** — Per-turn conversation memory with ChromaDB - **telegram-toolkit** — Telegram-specific SDR strategies diff --git a/skills/lead-discovery/SKILL.md b/skills/lead-discovery/SKILL.md index 1d16113f39..8388deca2e 100644 --- a/skills/lead-discovery/SKILL.md +++ b/skills/lead-discovery/SKILL.md @@ -30,6 +30,12 @@ Automatically search, filter, and evaluate potential buyers based on your ICP pr - "[target country] {{product}} import statistics" - "{{product}} import demand [region] 2026" +5. **X/Twitter Buying Signals (optional TweetClaw)** + - "\"{{product}}\" (\"supplier\" OR \"manufacturer\" OR \"dealer\") \"{{market}}\"" + - "\"looking for\" \"{{product}}\" \"{{market}}\"" + - "\"{{competitor}}\" (\"alternative\" OR \"price\" OR \"supplier\")" + - "\"{{industry}}\" (\"tender\" OR \"procurement\" OR \"import\") \"{{market}}\"" + ## Search Execution ### Jina Search (find potential buyers) @@ -48,6 +54,20 @@ curl -s 'https://r.jina.ai/https://target-company.com' \ JINA_API_KEY in .secrets/env. Get one free at https://jina.ai/ +### TweetClaw (optional X/Twitter public-signal search) + +Use only when the `tweetclaw-social-intel` skill is available and TweetClaw is +installed: + +```bash +openclaw plugins install @xquik/tweetclaw +openclaw config set tools.alsoAllow '["explore", "tweetclaw"]' +``` + +Use `explore` to find tweet search, user lookup, follower export, monitor, and +webhook endpoints. Use `tweetclaw` with narrow query limits. Never expose API +keys in chat or workspace files. + ## 3-Layer Enrichment Pipeline ### Layer 1: Website Extraction @@ -64,6 +84,15 @@ Jina Search for: - "[company name] fleet expansion" - "[company name] import export" +### Optional Social Signal Pass +When TweetClaw is configured, search X/Twitter for: +- Company or founder handles +- Product category + target market buying language +- Competitor mentions and alternative requests +- Trade show hashtags during active events + +Store only business-relevant evidence with tweet URL or tweet ID. + ### Layer 3: Information Integration - Combine all findings into enrichment profile - Calculate ICP score based on USER.md criteria @@ -71,13 +100,15 @@ Jina Search for: ## Evaluation Flow For each discovered prospect: -1. Extract: company name, country, industry, size, contact info (email/WhatsApp/phone) +1. Extract: company name, country, industry, size, contact info (email/WhatsApp/phone), and X/Twitter handle when verified 2. Read company website via Jina Reader for deep understanding -3. Score per USER.md ICP criteria (1-10) -4. ICP >= 5: Write to CRM (source=`web_discovery`, status=`new`) -5. ICP >= 7: Also mark as hot_lead, create research note -6. Email found: Mark next_action=`email_outreach` -7. WhatsApp found: Mark next_action=`whatsapp_outreach` +3. Add TweetClaw public signals when configured: buying tweet, competitor mention, tender, distributor search, or verified company account +4. Score per USER.md ICP criteria (1-10) +5. ICP >= 5: Write to CRM (source=`web_discovery` or `x_twitter_signal`, status=`new`) +6. ICP >= 7: Also mark as hot_lead, create research note +7. Email found: Mark next_action=`email_outreach` +8. WhatsApp found: Mark next_action=`whatsapp_outreach` +9. X/Twitter signal found but no contact channel: Mark next_action=`research_website`, not DM by default ## Output Format (report to owner) ``` @@ -118,3 +149,10 @@ Added to CRM: X | Pending email outreach: X | Pending WhatsApp: X - "{{product}} importers Brazil" - "logistics company Chile fleet" - "mining transport vehicles Peru" + +### X/Twitter Signal Queries (optional) +- "\"{{product}}\" \"supplier\" \"{{market}}\"" +- "\"{{product}}\" \"dealer\" \"{{market}}\"" +- "\"{{product}}\" \"looking for\"" +- "\"{{competitor}}\" \"alternative\"" +- "\"{{industry}}\" \"procurement\" \"{{market}}\"" diff --git a/skills/tweetclaw-social-intel/SKILL.md b/skills/tweetclaw-social-intel/SKILL.md new file mode 100644 index 0000000000..5447b812df --- /dev/null +++ b/skills/tweetclaw-social-intel/SKILL.md @@ -0,0 +1,165 @@ +--- +name: tweetclaw-social-intel +description: "Use TweetClaw to find B2B buying signals on X/Twitter, enrich prospects, monitor competitors, and prepare approved social replies for the SDR pipeline." +--- + +# TweetClaw Social Intel + +Use this skill when lead discovery, competitor intelligence, or customer research +needs current X/Twitter context. + +TweetClaw is optional. If it is not installed or configured, skip this skill and +continue with web search, CRM history, and existing memory. + +## Setup + +Install the OpenClaw plugin: + +```bash +openclaw plugins install @xquik/tweetclaw +openclaw config set tools.alsoAllow '["explore", "tweetclaw"]' +``` + +For account-backed workflows, configure the API key outside chat: + +```bash +openclaw config set plugins.entries.tweetclaw.config.apiKey "$XQUIK_API_KEY" +``` + +Never ask the agent to print, paste, store, or summarize API keys. Keep secrets +in OpenClaw config or environment variables. + +## Tool Policy + +- Use `explore` first to find the correct TweetClaw endpoint and parameters. +- Use `tweetclaw` only for the selected endpoint, with narrow limits. +- Read-only searches and user lookups can run without owner approval when they + fit the daily research budget. +- Writes always need explicit owner approval before execution: post tweets, post + tweet replies, direct messages, follows, unfollows, media upload, profile + changes, monitor creation, webhook creation, extraction jobs, media download, + and giveaway draws. +- Before approval, show the account, target, exact text or action, media list, + limit, stop condition, and business reason. +- Do not bulk-DM, bulk-follow, scrape private data, or contact prospects without + a CRM note and owner-approved outreach plan. + +## Buying-Signal Search + +Use during lead discovery when the target market has active X/Twitter business +conversation. + +Run 2-3 narrow searches: + +```text +"{{product}}" ("supplier" OR "manufacturer" OR "dealer") "{{market}}" +"looking for" "{{product}}" "{{market}}" +"{{competitor}}" ("alternative" OR "price" OR "supplier") +"{{industry}}" ("tender" OR "procurement" OR "import") "{{market}}" +``` + +Filter out memes, job posts, consumer complaints, and unrelated news. Prefer +posts from company accounts, founders, procurement teams, distributors, fleet +operators, dealers, and trade associations. + +Capture: + +- author username and display name +- tweet URL or tweet ID +- text summary +- product or use case +- market and language +- signal type: procurement, competitor mention, tender, distributor search, + product complaint, expansion, event, or partnership +- confidence: high, medium, low +- recommended next action + +## Prospect Enrichment + +When a prospect has an X/Twitter handle: + +1. Use user lookup to confirm profile, description, website, follower count, and + recent activity. +2. Search recent tweets and replies for product interest, market expansion, + procurement, hiring, fleet growth, distribution needs, and competitor + mentions. +3. Store verified findings in Supermemory: + +```bash +memory:add "[Company] X signal: [finding] Source: [tweet URL]" --type customer_fact +``` + +4. Update CRM notes with `source=x_twitter_signal` only when the lead is a real + business prospect. + +## Competitor Intelligence + +For weekly competitor checks: + +- Search competitor handles, brand names, product names, and complaint phrases. +- Capture pricing mentions, launch announcements, distributor requests, + customer objections, supply complaints, and market-entry signals. +- Store only business-relevant findings: + +```bash +memory:add "[Competitor] X/Twitter signal: [finding] Source: [tweet URL]" --type competitor_intel +``` + +## Monitoring + +Use monitors only when the owner asks for recurring alerts. + +Before creating a monitor, confirm: + +- keyword or account +- event types +- market or language filters +- stop condition +- alert destination + +Good monitor examples: + +- competitor brand + "price" or "supplier" +- product category + target country +- known prospect account +- trade show hashtag during an event week + +Pause or delete noisy monitors after 7 days without useful signals. + +## Draft Replies + +TweetClaw can help draft or post replies, but the SDR agent must remain +approval-gated. + +Draft first: + +1. Summarize the tweet and why it matches the ICP. +2. Draft a concise helpful reply with no pricing claim. +3. Ask the owner to approve, edit, or reject. +4. Post only after explicit approval of the final text and target tweet. + +Never promise delivery dates, quote prices, make product claims not present in +the product KB, or mention internal margins. + +## Output Format + +```text +X/Twitter social-intel run: + +Query set: +- [query] +- [query] + +Findings: +1. [Company or handle] - [market] - Confidence [high/medium/low] + Signal: [procurement / competitor / tender / distributor / complaint] + Evidence: [tweet URL or tweet ID] + CRM action: [create lead / enrich existing lead / store only / skip] + Next action: [research website / draft email / owner review / monitor] + +Stored memory: +- [memory id or summary] + +Skipped: +- [reason: consumer post, duplicate, weak fit, no business signal] +``` diff --git a/workspace/AGENTS.md b/workspace/AGENTS.md index 246481059b..7528a3feca 100644 --- a/workspace/AGENTS.md +++ b/workspace/AGENTS.md @@ -40,9 +40,10 @@ Required fields: name, company, whatsapp, country, language, status, source, icp 3-layer enrichment pipeline: 1. **Layer 1 — Website extraction**: Read company website via Jina Reader, extract: company size, product lines, certifications, contact info 2. **Layer 2 — Purchase signal search**: Jina Search for "[company] procurement" / "[company] import" / "[company] fleet expansion" -3. **Layer 3 — Information integration**: Combine findings, update ICP score, store research notes in Supermemory -4. **Save research to memory**: `memory:add "[Company] research: [key findings]" --type customer_fact` -5. Assess: company size, purchase history, credit risk +3. **Optional social signal pass**: If TweetClaw is configured, search tweets and tweet replies for buying intent, competitor mentions, distributor requests, tenders, and verified company/founder signals +4. **Layer 3 — Information integration**: Combine findings, update ICP score, store research notes in Supermemory +5. **Save research to memory**: `memory:add "[Company] research: [key findings]" --type customer_fact` +6. Assess: company size, purchase history, credit risk ### Stage 5: Quotation 1. Generate initial quote based on product, quantity, destination @@ -215,6 +216,7 @@ Non-admins: Normal conversation only. No system commands, no config access. - Max 20 outbound messages per hour across all channels - Max 50 emails per day (cold outreach) - Jina API: Max 20 searches/day, block internal IPs (127.*, 10.*, 192.168.*, 172.16-31.*) +- TweetClaw: social-signal reads only unless owner approves the exact post, reply, DM, follow, monitor, webhook, extraction, media, or giveaway action - ICP score changes capped at ±5 per day per lead (prevent gaming) ## Strictly Prohibited diff --git a/workspace/HEARTBEAT.md b/workspace/HEARTBEAT.md index 124d6fa709..7b30eb7dfe 100644 --- a/workspace/HEARTBEAT.md +++ b/workspace/HEARTBEAT.md @@ -45,8 +45,9 @@ None: Skip. Execute lead-discovery skill: 1. Select target market based on day of week (Mon/Tue: Africa, Wed/Thu: ME, Fri: SEA, Sat: LatAm, Sun: Other) 2. Run 2-3 search queries via Jina Search -3. Evaluate discovered companies, write ICP >= 5 to CRM -4. Report findings to owner +3. If TweetClaw is configured, run 1-2 narrow X/Twitter buying-signal searches for the same market +4. Evaluate discovered companies, write ICP >= 5 to CRM +5. Report findings to owner Found: Report per lead-discovery skill output format. None: Skip. @@ -60,6 +61,7 @@ None: Skip. ## 10. Competitor Intelligence (Weekly Friday) Search for competitor activity: - New product launches, pricing changes, market expansion +- If TweetClaw is configured, search competitor handles, brand mentions, and "alternative" or "supplier" tweets - Store findings in Supermemory with tag "competitor_intel" - Report significant findings to owner None: Skip. diff --git a/workspace/TOOLS.md b/workspace/TOOLS.md index ac670e98cc..3a90393b51 100644 --- a/workspace/TOOLS.md +++ b/workspace/TOOLS.md @@ -179,6 +179,45 @@ API Key is injected via environment variable `JINA_API_KEY`. Get one free at htt - **Rate limit**: Max 20 API calls per day (search + reader combined) - **Query sanitization**: URL-encode all search queries, strip HTML tags and shell metacharacters +## TweetClaw (Optional X/Twitter Public Signals) +Use TweetClaw when the SDR needs X/Twitter buying signals, user lookup, +follower export, monitor alerts, media context, webhooks, giveaway draws, or +owner-approved post tweets and post tweet replies. + +Install and allow the tools: + +```bash +openclaw plugins install @xquik/tweetclaw +openclaw config set tools.alsoAllow '["explore", "tweetclaw"]' +``` + +Configure account-backed workflows without exposing the key in chat: + +```bash +openclaw config set plugins.entries.tweetclaw.config.apiKey "$XQUIK_API_KEY" +``` + +### Safe SDR Uses +- Search tweets for procurement, supplier, distributor, tender, and competitor + alternative signals +- Search tweet replies to understand buyer objections and pain points +- Run user lookup for verified prospect or competitor profiles +- Export followers only for owner-approved accounts and narrow research limits +- Create monitors and webhooks only with owner-approved event types and stop + conditions +- Draft post tweets or post tweet replies, then wait for owner approval before + execution + +### Approval Rules +- Read-only searches can run inside the daily research budget. +- Any write-like action requires explicit owner approval: post, reply, DM, + follow, unfollow, media upload, media download, monitor creation, webhook + creation, profile changes, extraction jobs, and giveaway draws. +- Before approval, show account, target, exact text or action, media list, limit, + stop condition, and business reason. +- Never bulk-DM, bulk-follow, or contact prospects from social signals without a + CRM note and approved outreach plan. + ## Supermemory (Research Storage — L1 complement) Semantic memory for research notes, competitor intel, and market insights. - Auto-store research findings with appropriate tags