Felo X Search

Search X (Twitter) data using Felo X Search API. Use when users ask about X/Twitter users, tweets, trending topics on X, tweet replies, or when explicit comm...

Security Scan

The skill appears to implement an X/Twitter search client that calls openapi.felo.ai, but its registry metadata does not declare the FELO_API_KEY environment variable the runtime actually requires — this mismatch is a meaningful incoherence you should be aware of before installing.

Purpose & Capability

The name, README, SKILL.md, and bundled script all consistently implement a Felo X (Twitter) search client that calls https://openapi.felo.ai endpoints. However, the registry metadata lists no required environment variables or primary credential while both SKILL.md and the included script clearly require FELO_API_KEY (and optionally FELO_API_BASE). The missing declared credential in metadata is an inconsistency.

Instruction Scope

SKILL.md instructions limit actions to calling Felo Open API endpoints (POST to /v2/x/...), checking FELO_API_KEY, formatting results, and returning Markdown/JSON. The instructions do not ask the agent to read unrelated files, system credentials, or transmit data to unexpected endpoints beyond the documented API base.

Install Mechanism

There is no install spec (instruction-only skill) and the only code is a local Node script. No external download/install from third-party URLs is present in the package. This is low-risk from an install mechanism perspective.

Credentials

Runtime behavior requires FELO_API_KEY (and optionally FELO_API_BASE) per SKILL.md and the script, but the skill's declared requirements list no environment variables or primary credential. That omission is disproportionate because users/platforms won't be prompted to supply or review the needed API key in metadata, and the missing declaration prevents simple auditing/permission checks.

Persistence & Privilege

The skill does not request permanent/always-on presence (always: false) and contains no code that alters other skills or system-wide configuration. Autonomous invocation (disable-model-invocation: false) is normal for skills and not flagged on its own.

What to consider before installing

This skill's code and documentation show it needs a FELO_API_KEY to call openapi.felo.ai, but the package metadata does not declare that required environment variable — that mismatch is the main red flag. Before installing: (1) verify the skill's source (homepage/source fields point to a trusted repo or vendor), (2) confirm that the platform will prompt you to provide FELO_API_KEY (and won't accept an empty value), (3) treat the FELO_API_KEY as a sensitive credential and only give a key with the minimum scope possible, and (4) if you need stronger assurance, ask the publisher to update metadata to explicitly declare FELO_API_KEY and FELO_API_BASE so the skill's required permissions are visible during review. If you do not trust the source or cannot confirm the declared requirements, do not install.

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 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):

Usage	Behavior
felo x "AI news"	Search tweets (default)
felo x -q "AI news"	Same as above
felo x "OpenAI" --user	Search users

With --id (lookup mode):

Usage	Behavior
felo x --id "1234567890"	Get tweet replies (default)
felo x --id "elonmusk" --user	Get user info
felo x --id "elonmusk" --user --tweets	Get user tweets

Options

Option	Description
[query]	Positional arg, search keyword (equivalent to -q)
-q, --query <text>	Search keyword
--id <values>	Tweet IDs or usernames (comma-separated)
--user	Switch to user mode
--tweets	Get user tweets (with --id --user)
-l, --limit <n>	Number of results
--cursor <str>	Pagination cursor
--include-replies	Include replies (with --tweets)
--query-type <type>	Query type filter (tweet search)
--since-time <val>	Start time filter
--until-time <val>	End time filter
-j, --json	Output raw JSON
-t, --timeout <seconds>	Timeout in seconds (default: 30)

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`

Tweet content here...

Engagement: 5.0K likes ｜ 1.0K retweets ｜ 200 replies

---

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

• 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