{"skill":{"slug":"twitterapi-research-skill","displayName":"TwitterApi Research","summary":"General-purpose X/Twitter research agent. Searches X for real-time perspectives, dev discussions, product feedback, cultural takes, breaking news, and expert...","description":"---\nname: x-research\ndescription: >\n  General-purpose X/Twitter research agent. Searches X for real-time perspectives,\n  dev discussions, product feedback, cultural takes, breaking news, and expert opinions.\n  Works like a web research agent but uses X as the source.\n  Use when: (1) user says \"x research\", \"search x for\", \"search twitter for\",\n  \"what are people saying about\", \"what's twitter saying\", \"check x for\", \"x search\",\n  \"/x-research\", (2) user is working on something where recent X discourse would provide\n  useful context (new library releases, API changes, product launches, cultural events,\n  industry drama), (3) user wants to find what devs/experts/community thinks about a topic.\n  NOT for: posting tweets or account management. Uses twitterapi.io (third-party API) for full-archive search — not limited to 7 days.\n---\n\n# X Research\n\nGeneral-purpose agentic research over X/Twitter. Decompose any research question into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize into a sourced briefing.\n\nFor twitterapi.io API details (endpoints, operators, response format): read `references/x-api.md`.\n\n## CLI Tool\n\nAll commands run from this skill directory:\n\n```bash\ncd ~/clawd/skills/x-research\nsource ~/.config/env/global.env  # needs TWITTERAPI_IO_KEY\n```\n\n### Search\n\n```bash\nbun run x-search.ts search \"<query>\" [options]\n```\n\n**Options:**\n- `--sort likes|impressions|retweets|recent` — sort order (default: likes)\n- `--since 1h|3h|12h|1d|7d` — time filter (default: last 7 days). Also accepts minutes (`30m`) or ISO timestamps.\n- `--min-likes N` — filter by minimum likes\n- `--min-impressions N` — filter by minimum impressions\n- `--pages N` — pages to fetch, 1-25 (default: 5, ~20 tweets/page)\n- `--limit N` — max results to display (default: 15)\n- `--quick` — quick mode: 1 page, max 10 results, auto noise filter (`-is:retweet -is:reply`), 1hr cache, cost summary\n- `--from <username>` — shorthand for `from:username` in query\n- `--quality` — filter low-engagement tweets (≥10 likes, post-hoc)\n- `--no-replies` — exclude replies\n- `--save` — save results to `~/clawd/drafts/x-research-{slug}-{date}.md`\n- `--json` — raw JSON output\n- `--markdown` — markdown output for research docs\n\nAuto-adds `-is:retweet` unless query already includes it. All searches display estimated API cost.\n\n**Note:** twitterapi.io search covers full archive (not limited to 7 days). Time filtering uses `since:` operator in the query.\n\n**Examples:**\n```bash\nbun run x-search.ts search \"BNKR\" --sort likes --limit 10\nbun run x-search.ts search \"from:frankdegods\" --sort recent\nbun run x-search.ts search \"(opus 4.6 OR claude) trading\" --pages 2 --save\nbun run x-search.ts search \"$BNKR (revenue OR fees)\" --min-likes 5\nbun run x-search.ts search \"BNKR\" --quick\nbun run x-search.ts search \"BNKR\" --from voidcider --quick\nbun run x-search.ts search \"AI agents\" --quality --quick\n```\n\n### Profile\n\n```bash\nbun run x-search.ts profile <username> [--count N] [--replies] [--json]\n```\n\nFetches recent tweets from a specific user (excludes replies by default).\n\n### Thread\n\n```bash\nbun run x-search.ts thread <tweet_id> [--pages N]\n```\n\nFetches full conversation thread by root tweet ID.\n\n### Single Tweet\n\n```bash\nbun run x-search.ts tweet <tweet_id> [--json]\n```\n\n### Watchlist\n\n```bash\nbun run x-search.ts watchlist                       # Show all\nbun run x-search.ts watchlist add <user> [note]     # Add account\nbun run x-search.ts watchlist remove <user>          # Remove account\nbun run x-search.ts watchlist check                  # Check recent from all\n```\n\nWatchlist stored in `data/watchlist.json`. Use for heartbeat integration — check if key accounts posted anything important.\n\n### Cache\n\n```bash\nbun run x-search.ts cache clear    # Clear all cached results\n```\n\n15-minute TTL. Avoids re-fetching identical queries.\n\n## Research Loop (Agentic)\n\nWhen doing deep research (not just a quick search), follow this loop:\n\n### 1. Decompose the Question into Queries\n\nTurn the research question into 3-5 keyword queries using X search operators:\n\n- **Core query**: Direct keywords for the topic\n- **Expert voices**: `from:` specific known experts\n- **Pain points**: Keywords like `(broken OR bug OR issue OR migration)`\n- **Positive signal**: Keywords like `(shipped OR love OR fast OR benchmark)`\n- **Links**: `url:github.com` or `url:` specific domains\n- **Noise reduction**: `-is:retweet` (auto-added), add `-is:reply` if needed\n- **Crypto spam**: Add `-airdrop -giveaway -whitelist` if crypto topics flooding\n\n### 2. Search and Extract\n\nRun each query via CLI. After each, assess:\n- Signal or noise? Adjust operators.\n- Key voices worth searching `from:` specifically?\n- Threads worth following via `thread` command?\n- Linked resources worth deep-diving with `web_fetch`?\n\n### 3. Follow Threads\n\nWhen a tweet has high engagement or is a thread starter:\n```bash\nbun run x-search.ts thread <tweet_id>\n```\n\n### 4. Deep-Dive Linked Content\n\nWhen tweets link to GitHub repos, blog posts, or docs, fetch with `web_fetch`. Prioritize links that:\n- Multiple tweets reference\n- Come from high-engagement tweets\n- Point to technical resources directly relevant to the question\n\n### 5. Synthesize\n\nGroup findings by theme, not by query:\n\n```\n### [Theme/Finding Title]\n\n[1-2 sentence summary]\n\n- @username: \"[key quote]\" (NL, NI) [Tweet](url)\n- @username2: \"[another perspective]\" (NL, NI) [Tweet](url)\n\nResources shared:\n- [Resource title](url) — [what it is]\n```\n\n### 6. Save\n\nUse `--save` flag or save manually to `~/clawd/drafts/x-research-{topic-slug}-{YYYY-MM-DD}.md`.\n\n## Refinement Heuristics\n\n- **Too much noise?** Add `-is:reply`, use `--sort likes`, narrow keywords\n- **Too few results?** Broaden with `OR`, remove restrictive operators\n- **Crypto spam?** Add `-$ -airdrop -giveaway -whitelist`\n- **Expert takes only?** Use `from:` or `--min-likes 50`\n- **Substance over hot takes?** Search with `has:links`\n\n## Heartbeat Integration\n\nOn heartbeat, can run `watchlist check` to see if key accounts posted anything notable. Flag to Frank only if genuinely interesting/actionable — don't report routine tweets.\n\n## File Structure\n\n```\nskills/x-research/\n├── SKILL.md           (this file)\n├── x-search.ts        (CLI entry point)\n├── lib/\n│   ├── api.ts         (twitterapi.io wrapper: search, thread, profile, tweet)\n│   ├── cache.ts       (file-based cache, 15min TTL)\n│   └── format.ts      (Telegram + markdown formatters)\n├── data/\n│   ├── watchlist.json  (accounts to monitor)\n│   └── cache/          (auto-managed)\n└── references/\n    └── x-api.md        (twitterapi.io endpoint reference)\n```\n","tags":{"latest":"0.1.0"},"stats":{"comments":0,"downloads":638,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1772053461215,"updatedAt":1778491644319},"latestVersion":{"version":"0.1.0","createdAt":1772053461215,"changelog":"- Initial release of the general-purpose X/Twitter research agent using twitterapi.io for full-archive, real-time searches.\n- Supports targeted CLI commands for search, profile lookup, thread/conversation fetching, tweet details, and account watchlist management.\n- Features robust search refinements: operator-based queries, sorting, time filtering, minimum likes/impressions, and engagement-based noise reduction.\n- Enables saving, markdown/JSON output formats, and local result caching (15-minute TTL).\n- Outlines best-practice research workflows: question decomposition, thread following, linked content investigation, synthesis, and saving.\n- Includes heartbeat/watchlist functionality to monitor and flag notable tweets from key accounts.","license":null},"metadata":null,"owner":{"handle":"blascokoa","userId":"s1744ch29ebnns209xpv81686h884kne","displayName":"Blasco","image":"https://avatars.githubusercontent.com/u/37955180?v=4"},"moderation":null}