omni-x（全向 X）

X (Twitter) Data Extractor Skill

Overview

This skill provides AI agents with the ability to extract various types of data from X (Twitter) platform, including user profiles, posts, followers, followings, media content, and search results.

Prerequisites

• Python 3.7+ installed
• Dependencies installed (see references/INSTALLATION.md)

Workflow

Step 1: Initialize the Skill Interface

from scripts import TwitterSkillInterface

# Method 1: Initialize with auth_token (RECOMMENDED for full access)
interface = TwitterSkillInterface(auth_token="your_auth_token_here")

# Method 2: Initialize without token (guest session - limited features)
interface = TwitterSkillInterface()

# Method 3: Set token after initialization
interface = TwitterSkillInterface()
interface.set_auth_token("your_auth_token_here")

Step 2: Discover Available Skills

# Get all available skills and their metadata
skills = interface.get_available_skills()

# Each skill contains:
# - description: What the skill does
# - parameters: Required and optional parameters
# - returns: Expected return format
# - requires_auth: Whether authentication is needed

Step 3: Execute Skills

# Execute a skill with parameters
result = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 10}
)

# Check result
if result["success"]:
    data = result["data"]
    print(f"Retrieved {result['count']} items")
else:
    print(f"Error: {result['error']}")

Step 4: Handle Results

All skills return a standardized response format:

Success Response:

{
    "success": True,
    "data": [...],           # The actual data
    "count": 10,             # Number of items (if applicable)
    "has_next_page": True,   # Pagination info (if applicable)
    "cursor": "...",         # Cursor for next page (if applicable)
    "skill_name": "...",     # Name of executed skill
    "parameters": {...}      # Parameters used
}

Error Response:

{
    "success": False,
    "error": "Error message",
    "skill_name": "...",
    "parameters": {...}
}

Available Skills

1. get_user_profile

Description: Extract detailed user profile information.

Authentication: Not required (works with guest session)

Parameters:

• username (str, required): Twitter username without @ symbol

Example:

result = interface.execute_skill(
    skill_name="get_user_profile",
    parameters={"username": "elonmusk"}
)

Returns: User profile data including name, bio, followers count, following count, etc.

2. get_user_tweets

Description: Extract recent tweets from a specific user.

Authentication: Not required (works with guest session)

Parameters:

• username (str, required): Twitter username without @ symbol
• count (int, optional): Number of tweets to retrieve (default: 10)

Example:

result = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 20}
)

Returns: List of tweets with text, timestamp, engagement metrics, etc.

3. get_user_followers

Description: Extract list of users following the specified account.

Authentication: Required (auth_token needed)

Parameters:

• username (str, required): Twitter username without @ symbol
• count (int, optional): Number of followers to retrieve (default: 20)

Example:

result = interface.execute_skill(
    skill_name="get_user_followers",
    parameters={"username": "elonmusk", "count": 50}
)

Returns: List of follower profiles with pagination support.

4. get_user_followings

Description: Extract list of users that the specified account follows.

Authentication: Required (auth_token needed)

Parameters:

• username (str, required): Twitter username without @ symbol
• count (int, optional): Number of followings to retrieve (default: 20)

Example:

result = interface.execute_skill(
    skill_name="get_user_followings",
    parameters={"username": "elonmusk", "count": 50}
)

Returns: List of following profiles with pagination support.

5. get_user_media

Description: Extract media content (photos/videos) from user's tweets.

Authentication: Required (auth_token needed)

Parameters:

• username (str, required): Twitter username without @ symbol
• count (int, optional): Number of media items to retrieve (default: 10)

Example:

result = interface.execute_skill(
    skill_name="get_user_media",
    parameters={"username": "elonmusk", "count": 15}
)

Returns: List of media items with URLs and metadata.

6. search_tweets

Description: Search for tweets matching a query string.

Authentication: Required (auth_token needed)

Parameters:

• query (str, required): Search query string
• count (int, optional): Number of tweets to retrieve (default: 10)
• search_filter (str, optional): Filter type - "Latest", "Top", "People", "Photos", "Videos" (default: "Top")

Example:

result = interface.execute_skill(
    skill_name="search_tweets",
    parameters={
        "query": "AI technology",
        "count": 20,
        "search_filter": "Latest"
    }
)

Returns: List of tweets matching the search query.

Tool Usage Instructions

For AI Agents

When using this skill, follow these steps:

1. Determine the task: Analyze user request to identify which skill is needed

- Profile info → get_user_profile - Recent tweets → get_user_tweets - Follower analysis → get_user_followers - Following analysis → get_user_followings - Media extraction → get_user_media - Search tweets → search_tweets

1. Check authentication requirements:

- If skill requires auth and no token is set, inform user to provide auth_token - Guest session works for: get_user_profile, get_user_tweets - Auth required for: get_user_followers, get_user_followings, get_user_media, search_tweets

1. Extract parameters from user request:

- Username (remove @ if present) - Count/limit for results - Search filters (for search_tweets)

1. Execute the skill:

   result = interface.execute_skill(skill_name="...", parameters={...})

1. Process and present results:

- Check result["success"] first - If successful, format and present result["data"] - If failed, explain result["error"] to user - Mention pagination if result["has_next_page"] is True

Error Handling

result = interface.execute_skill(skill_name="...", parameters={...})

if not result["success"]:
    error_msg = result["error"]
    
    # Common errors and solutions:
    if "auth" in error_msg.lower() or "login" in error_msg.lower():
        # Inform user that authentication is required
        print("This feature requires authentication. Please provide auth_token.")
    elif "not found" in error_msg.lower():
        # Username doesn't exist
        print(f"User not found. Please check the username.")
    elif "rate limit" in error_msg.lower():
        # Rate limit exceeded
        print("Rate limit exceeded. Please wait before trying again.")
    else:
        # Generic error
        print(f"An error occurred: {error_msg}")

Examples

Example 1: Get User Profile and Recent Tweets

from scripts import TwitterSkillInterface

# Initialize
interface = TwitterSkillInterface()

# Get profile
profile = interface.execute_skill(
    skill_name="get_user_profile",
    parameters={"username": "elonmusk"}
)

if profile["success"]:
    print(f"User: {profile['data']['name']}")
    print(f"Followers: {profile['data']['followers_count']}")

# Get recent tweets
tweets = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 5}
)

if tweets["success"]:
    for tweet in tweets["data"]:
        print(f"Tweet: {tweet['text']}")

Example 2: Search and Analyze Tweets (Requires Auth)

from scripts import TwitterSkillInterface

# Initialize with auth token
interface = TwitterSkillInterface(auth_token="your_auth_token")

# Search for tweets
results = interface.execute_skill(
    skill_name="search_tweets",
    parameters={
        "query": "artificial intelligence",
        "count": 20,
        "search_filter": "Latest"
    }
)

if results["success"]:
    print(f"Found {results['count']} tweets")
    for tweet in results["data"]:
        print(f"- {tweet['text'][:100]}...")

Example 3: Analyze User Network (Requires Auth)

from scripts import TwitterSkillInterface

# Initialize with auth token
interface = TwitterSkillInterface(auth_token="your_auth_token")

username = "elonmusk"

# Get followers
followers = interface.execute_skill(
    skill_name="get_user_followers",
    parameters={"username": username, "count": 100}
)

# Get followings
followings = interface.execute_skill(
    skill_name="get_user_followings",
    parameters={"username": username, "count": 100}
)

if followers["success"] and followings["success"]:
    print(f"Followers: {followers['count']}")
    print(f"Following: {followings['count']}")
    print(f"Ratio: {followers['count'] / followings['count']:.2f}")

Best Practices

1. Always provide auth_token when possible - Many features require authentication
2. Check success field first - Always verify result["success"] before accessing data
3. Handle pagination - Use cursor field for large datasets
4. Respect rate limits - CRITICAL: Implement delays between requests to avoid account restrictions

- Recommended: 1-2 second delay between requests - For bulk operations: 2-3 second delay - Monitor for rate limit errors and back off exponentially if encountered

1. Cache results - Avoid repeated requests for the same data
2. Validate usernames - Remove @ symbol and validate format before calling
3. Use appropriate count values - Start with small counts (10-20) and increase gradually as needed
4. Handle errors gracefully - Provide meaningful feedback to users
5. Comply with Terms of Service - Ensure all usage complies with X (Twitter) Terms of Service
6. Educational/Research Use Only - This tool is intended for educational and research purposes only

Authentication Guide

See references/LOGIN_GUIDE.md for detailed instructions on obtaining and using auth_token.

Quick steps:

1. Log in to Twitter/X in browser
2. Open Developer Tools (F12)
3. Go to Application/Storage → Cookies
4. Find auth_token cookie
5. Copy its value
6. Use it to initialize: TwitterSkillInterface(auth_token="...")

Troubleshooting

Problem: "Guest session has limited access"

• Solution: Provide auth_token for full feature access

Problem: "User not found"

• Solution: Verify username is correct (without @ symbol)

Problem: "Rate limit exceeded"

• Solution: Wait before making more requests, implement delays

Problem: "Authentication required"

• Solution: Provide valid auth_token for this feature

References

• Full API documentation: references/AI_AGENT_GUIDE.md
• Authentication guide: references/LOGIN_GUIDE.md
• Installation instructions: references/INSTALLATION.md
• Example code: agent_example.py

Support

For issues or questions, refer to the documentation in the references/ directory or check the main README.md file.