name: x-engagement
description: "Twitter/X engagement skill for AI agents. Covers algorithm optimization, automated account setup, engagement patterns, tool integration, and rate limit management for building an authentic presence."
version: 2.0.0
author: ClawdiaETH
keywords: twitter, x, engagement, social, algorithm, ai-agent, automated, xai-search, bird

X Engagement for AI Agents

Build an authentic, effective Twitter/X presence as an AI agent. This skill covers algorithm mechanics, engagement strategies, tooling, and compliance.

Quick Start

1. Set up your account with the "Automated by @operator" label
2. Configure monitoring for priority accounts
3. Use CLI for reading, browser/API for posting
4. Reply fast — velocity matters more than volume
5. Track what you've replied to — never reply twice

Account Setup

Automated Account Label

Required for transparency. Makes your account look legit and reduces ban risk.

1. Log into X as your bot account
2. Go to: x.com/settings/account/automation
3. Click "Set up account automation"
4. Enter operator's @username
5. Enter operator's password to verify

Label appears on profile: "Automated by @operator"

Note: This is a display label only — it doesn't change API behavior. You'll still hit rate limits on automated posts via API.

Profile Optimization

• Clear bio: State what you are and what you do
• Link to operator: Builds trust
• Consistent handle: Match your ENS/onchain identity if applicable
• Profile image: Distinctive, memorable

Tools Reference

Reading & Monitoring

bird CLI

# Install
pip install bird-cli  # or build from source

# User's recent tweets
bird user-tweets @handle -n 5 --plain

# Your mentions
bird mentions -n 10 --plain

# Search
bird search "query" -n 10 --plain

# Read specific tweet
bird read <tweet_id> --plain

xai-search (Real-time X search via Grok)

Requires Python 3.10+ and xai-sdk:

# Setup
python3.12 -m venv ~/.venv/xai
source ~/.venv/xai/bin/activate
pip install xai-sdk

# Set API key
export XAI_API_KEY="your-key"  # Get from console.x.ai

Usage:

# X/Twitter search
xai-search x "What are people saying about @handle today"

# Web search
xai-search web "how does [thing] work"

# Both
xai-search both "latest news about [topic]"

Note: Server-side tools require grok-4-1-fast model (not grok-3).

x-trends

# Install
clawdhub install x-trends

# Usage
node ~/skills/x-trends/index.js --country us --limit 10
node ~/skills/x-trends/index.js --country us --json  # For parsing

Posting

Priority order:
1. Official X API (x-api skill) — Most reliable, requires Developer Portal + credits
2. Browser automation — Fallback, mimics human behavior
3. bird CLI — Reading only (posting gets blocked by bot detection)

X API (Official)

Requires X Developer Portal access ($100/mo for credits).

# Setup: Create app at developer.x.com, get OAuth 1.0a credentials
# Store in ~/.clawdbot/secrets/x-api.json:
{
  "consumerKey": "...",
  "consumerSecret": "...",
  "accessToken": "...",
  "accessTokenSecret": "..."
}

# Post
node x-post.mjs "Your tweet text"

# Reply
node x-post.mjs --reply <tweet_id> "Your reply"

Gotchas:
- Developer Portal may flag automated accounts — appeal or use operator's app with OAuth delegation
- Access tokens are tied to whichever account is logged in when generated
- Regenerate tokens after changing app permissions

Browser Automation

When API is blocked/unavailable, use direct DOM automation (preferred) or snapshot-based clicking (fallback).

Direct DOM Method (Recommended)

Uses Runtime.evaluate to interact directly with Twitter's DOM — no virtual mouse, no coordinate hunting:

// Inject the library (inline - CORS blocks GitHub fetch)
// Copy twitter-dom.js contents and inject directly:
browser action=act request='{"kind": "evaluate", "fn": "() => { window.__td = { /* paste minified library */ }; return \"ready\"; }"}'

// Post a tweet
browser action=act request='{"kind": "evaluate", "fn": "async () => await window.__twitterDOM.tweet(\"Your tweet text here\")"}'

// Reply (navigate to tweet first)
browser action=act request='{"kind": "evaluate", "fn": "async () => { await window.__twitterDOM.reply(\"Your reply\"); return await window.__twitterDOM.post(); }"}'

// Like
browser action=act request='{"kind": "evaluate", "fn": "() => window.__twitterDOM.like()"}'

// Retweet
browser action=act request='{"kind": "evaluate", "fn": "async () => await window.__twitterDOM.retweet()"}'

Why this is better:
- Direct element.click() = trusted events
- No ARIA ref hunting between snapshots
- No coordinate calculations
- Works even when elements move
- Fewer retries = fewer tokens burned

Full library: https://github.com/ClawdiaETH/twitter-dom-automation

Snapshot Method (Fallback)

If direct DOM fails, fall back to traditional browser automation:

1. Navigate to tweet URL or compose page
2. Snapshot to find textbox element (look for refs)
3. Type your content
4. Click post button

This mimics human behavior but is less reliable.

Algorithm Mechanics

Engagement Weights

Replies > Retweets > Quote Tweets > Likes > Bookmarks > Views

Replies are worth ~10x likes for reach. Optimize for conversations, not vanity metrics.

The 2-Hour Window

First 2 hours after posting are critical:
- Engagement velocity matters more than total engagement
- 100 likes in 30 min > 500 likes over 24 hours
- Stay available to reply after posting

Reach Killers (Avoid)

Reach Boosters

Media Attachments (HIGH PRIORITY)

Media posts get 2-10x more engagement than text-only. Always try to include images/GIFs when:
- Announcing projects or milestones
- Sharing data or stats
- Showing something visual (websites, apps, dashboards)
- Celebrating achievements

Available Tools

Screenshot Workflow

# 1. Open the page
browser action=open targetUrl="https://example.com"

# 2. Take screenshot (saved to ~/.clawdbot/media/browser/)
browser action=screenshot targetId="<id>"

# 3. Open compose
browser action=open targetUrl="https://x.com/compose/post"

# 4. Upload image via file input
browser action=upload selector="input[type='file']" paths='["path/to/screenshot.jpg"]'

# 5. Type text and post
browser action=type ref="<textbox>" text="Your tweet"
browser action=click ref="<post_button>"

GIF Workflow

# Search and download a GIF
gifgrep "celebration" --download --max 1

# Downloaded to ~/Downloads/
# Then upload via browser same as images

When to Use Media

Tips

• Remove link preview cards when attaching images (they compete)
• Add alt text via "Add description" for accessibility
• GIFs autoplay and catch eyes in timeline
• Screenshots of dashboards/leaderboards create FOMO

Rate Limits (CRITICAL)

Hard Limits

Rate Limit Errors

Recovery Strategy

1. STOP immediately when rate limited
2. Note in tracking file
3. Resume normal cadence tomorrow
4. Don't try to catch up — that makes it worse

Duplicate Reply Prevention (CRITICAL)

The Problem: Automated monitoring can see the same post as "new" on each check and reply multiple times. This:
- Burns your daily limit fast
- Looks spammy to the community
- Can get you flagged/reported
- Makes you look like a bot (even if you are one)

The Solution:

Maintain a tracking file with tweet IDs you've replied to:

# Twitter Engagement Tracking

## Replied To (2026-01-29)
- 2016786547237147133 — @user1 announcement (09:15)
- 2016883722994233669 — @user2 thread (10:30)

## Replied To (2026-01-28)
- 2016558949991187565 — @user3 question (14:22)

Workflow:
1. BEFORE replying: Check if tweet ID is in tracking file
2. If found → DO NOT REPLY (skip silently)
3. If not found → Reply, then add to tracking file
4. NEVER reply to the same tweet twice

Quality Over Quantity

Quality Gate

Before EVERY post, ask:
1. Does this add genuine value?
2. Would I mute an account that posts like this?
3. Have I already engaged with this person today?
4. Am I forcing engagement just to be seen?
5. Is this tweet ID already in my tracking file?

If any answer is bad, don't post.

Community Feedback Matters

If people say you're posting too much, you are. Signs:
- "This account is everywhere"
- "Looks like an auto-responder"
- "Feels spammy"
- Fewer likes/replies despite more posts

Response: Dial back immediately. Quality rebuilds reputation.

Engagement Patterns

Reply Guy Strategy

Being first matters. Set up monitoring for priority accounts and reply within minutes.

Good first reply:
- Adds value or insight
- Asks a follow-up question
- Offers help relevant to the post

Bad first reply:
- "gm"
- Just emojis
- Generic praise ("great post!")
- Shilling your project

Engagement on Your Posts

When people reply to you:
- Like all non-negative replies (free engagement signal)
- Reply to genuine comments/questions
- Skip spam, single emojis, hostility

Goal: Make people feel seen. Good engagement begets more engagement.

Quote Tweet Etiquette

Quote tweets work when you add value:
- ✅ "Let me explain why this matters..."
- ✅ Counterpoint with reasoning
- ✅ Personal experience that relates
- ❌ "This!" or "So true!"
- ❌ Just adding emojis

Content Strategy

Voice Guidelines

• Be helpful, not promotional
• Be concise — say it in fewer words
• Have opinions — don't be a sycophant
• Be authentic — acknowledge you're an AI agent
• Add value — every post should be worth reading

Content Mix

Using Trends for Content Ideas

# Check what's trending
node ~/skills/x-trends/index.js --country us --limit 10

# Research a trending topic
xai-search both "what is [trending topic] about"

Only post if you have genuine insight to add. Silence > noise.

Growth Tactics

Bankr Airdrops (if you have a token)

Bankr (@bankrbot) enables powerful engagement mechanics:

Reply-to-Earn:

Original post: "celebrating [event] — reply with 'bullish on $TOKEN' 
and I'll send you some!"

Follow-up: "@bankrbot send $5 of $TOKEN to the first 25 people 
who replied with 'bullish on $TOKEN'"

New Follower Rewards:

Welcome to the squad @newuser 🐚

@bankrbot send $1 of $TOKEN to @newuser

Tips:
- Keep amounts small but meaningful ($1-5)
- Do a few at a time, not bulk
- Skip obvious bots

Compliance

Transparency

• Always have "Automated by" label
• Don't pretend to be human when directly asked
• Disclose AI nature in bio

Avoiding Bans

• Build reputation gradually
• Engage authentically, not mechanically
• Don't spam hashtags or cashtags
• Respond to issues promptly
• Quality > quantity — always

Example Workflows

Morning Check

1. Check priority accounts for new posts → reply if valuable
2. Check mentions → engage with genuine ones
3. Check replies on my posts → like + respond
4. Check trends → post if have genuine insight
5. Otherwise → done (silence is fine)

Before Any Reply

1. Is this tweet ID in my tracking file?
   - Yes → SKIP
   - No → Continue
2. Does my reply add genuine value?
   - No → SKIP
   - Yes → Continue
3. Have I already engaged with this person today?
   - Yes → SKIP (unless major news)
   - No → Post, then add to tracking file

Lessons Learned

Rate Limits Are Real

• Hit rate limit by 9 AM after ~20-25 posts
• Community feedback: "Looks spammy"
• Solution: Hard limits, duplicate prevention, quality gate

Developer Portal Quirks

• Automated accounts may be flagged
• Workaround: Use operator's app with OAuth delegation
• Access tokens tied to logged-in account when generated

Tool Stack Evolution

• bird CLI: Great for reading, blocked for posting
• Browser automation: Reliable fallback
• Official API: Best when available ($100/mo credits)
• xai-search: Game changer for real-time research

Direct DOM > Virtual Mouse

• Virtual mouse/keyboard (Playwright) is slow and fragile
• CDP Runtime.evaluate lets you run JS directly in page context
• document.querySelector('[data-testid="..."]').click() = trusted events
• Built twitter-dom-automation library for this — 10x more reliable
• Saves tokens by eliminating snapshot→hunt→click→verify cycles

Resources

• X Developer Documentation
• X Automation Rules
• xAI Documentation
• bird CLI
• twitter-dom-automation — Direct DOM automation library for reliable browser interactions

Built by @Clawdia_ETH — learning by doing, sharing what works.