duotify/githubclawtoolkit/felo-x-search

Felo X Search Skill

When to Use

Trigger this skill when the user wants to:

• Look up X (Twitter) user profiles by username
• Search for X users by keyword
• Get tweets from a specific X user
• Search tweets by keyword or advanced query
• Get replies to specific tweets

Trigger keywords (examples):

• English: twitter, tweet, X user, X search, tweets from, replies to, trending on X
• 简体中文: 推特, 推文, X用户, X搜索, 推文回复
• 日本語: ツイッター, ツイート, Xユーザー, X検索

Explicit commands: /felo-x-search, "search X", "search twitter"

Do NOT use for:

• General web search (use felo-search)
• Webpage extraction (use felo-web-extract)
• Generating slides (use felo-slides)

Setup

1. Get API key

1. Visit felo.ai
2. Open Settings -> API Keys
3. Create and copy your API key

2. Configure environment variable

Linux/macOS:

export FELO_API_KEY="your-api-key-here"

Windows PowerShell:

$env:FELO_API_KEY="your-api-key-here"

How to Execute

Option A: Use the bundled script or packaged CLI

Packaged CLI (after npm install -g felo-ai):

felo x [query] [options]

Script (from repo):

node .agents/skills/felo-x-search/scripts/run_x_search.mjs [query] [options]

Usage Pattern

The x command uses parameter combinations to infer intent — no subcommands needed.

With query (search mode):

With --id (lookup mode):

Options

Option B: Call API with curl

# Search tweets
curl -X POST "https://openapi.felo.ai/v2/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI news", "limit": 20}'
 
# Search users
curl -X POST "https://openapi.felo.ai/v2/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "artificial intelligence"}'
 
# Get user info
curl -X POST "https://openapi.felo.ai/v2/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames": ["elonmusk", "OpenAI"]}'
 
# Get user tweets
curl -X POST "https://openapi.felo.ai/v2/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "elonmusk", "limit": 20}'
 
# Get tweet replies
curl -X POST "https://openapi.felo.ai/v2/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids": ["1234567890"]}'

Output Format

User Info (default, non-JSON)

## @elonmusk (Elon Musk 🔵)
-User ID: `44196397`
-Followers: 100.0M
-Following: 500
-Total Tweets: 30.0K
-Bio: ...
-Location: Mars
-Account Created: 2009-06-02T00:00:00Z
 
---

Tweet (default, non-JSON)

### @elonmusk(Elon Musk ✓)
-Posted: 2026-03-09T12:00:00Z ｜ Tweet ID: `1234567890`
-🔗 [查看原推文](https://x.com/elonmusk/status/1234567890)
 
Tweet content here...
 
Engagement: 5.0K likes ｜ 1.0K retweets ｜ 200 replies
 
---

Link Validation

每次輸出推文連結前，必須執行以下檢核，確保連結正確：

1. 連結格式：推文連結必須為 https://x.com/{username}/status/{tweet_id}，username 與 tweet_id 均來自 API 回傳的資料，禁止自行推測或填入預設值。
2. 資料對應：連結中的 username 必須與該推文的 author.username 欄位一致，tweet_id 必須與 id 欄位一致。
3. 禁止捏造：若 API 未回傳 tweet_id 或 username，則該則推文不得附上連結，改為標注「連結不可用」。
4. 用戶連結：用戶頁面連結格式為 https://x.com/{username}，同樣只能使用 API 回傳的 username。

Error Handling

Common Error Codes

• INVALID_API_KEY — API Key is invalid or revoked
• X_SEARCH_FAILED — X search request failed (check parameters or downstream error)

Missing API Key

If FELO_API_KEY is not set, display setup instructions and stop.

API Reference (summary)

• Base URL: https://openapi.felo.ai. Override with FELO_API_BASE env if needed.
• Auth: Authorization: Bearer YOUR_API_KEY
• Endpoints:
• POST /v2/x/user/info — Batch get user profiles
• POST /v2/x/user/search — Search users
• POST /v2/x/user/tweets — Get user tweets
• POST /v2/x/tweet/search — Search tweets
• POST /v2/x/tweet/replies — Get tweet replies

Important Notes

• ⚠️ 路徑安全：skill 腳本位於 repo root 的 .agents/skills/ 下。若 cwd 不在 repo root，先執行 git rev-parse --show-toplevel 取得路徑再 cd。禁止用 $(...) 語法。
• Always check FELO_API_KEY before calling; if missing, return setup instructions.
• Format output as readable Markdown by default; use --json for raw API response.
• Use pagination cursors (next_cursor) for fetching more results.
• For tweet search, advanced query syntax is supported (same as X advanced search).

References

• Felo X Search API
• Felo Open Platform