x-research

X Research

Read-only access to X (Twitter) through xurl. Use this when you need to know what people are saying on X about a topic, read a specific thread, check someone's recent posts, or read long-form X Articles.

When to Use

• Researching what people on X are saying about a topic (an API, a tool, a trend)
• Reading a specific thread or conversation for context
• Checking a profile's recent posts (e.g., what has @someone been saying about Rust?)
• Reading long-form X Articles
• Gathering community sentiment before making a decision

When NOT to Use

• General web research — use the research skill instead (curl + DuckDuckGo)
• Posting, liking, following, DMing — this skill is read-only, always
• Bulk historical scraping — the API has rate limits and this isn't an archival tool
• Real-time monitoring or streaming — one-shot queries only
• Anything that modifies state on X — never, under any circumstances

Prerequisites

Two auth modes are supported. Detect which one applies first, then use the x_get helper for every request — never call xurl GET or curl directly inline, or CI mode will silently fail (xurl has no ~/.xurl on a runner).

# Auth mode detection — run this once at the top of the session:
if [ -n "$X_BEARER_TOKEN" ]; then
    AUTH_MODE=ci
elif command -v xurl &>/dev/null && [ -d "$HOME/.xurl" ]; then
    AUTH_MODE=local
else
    have_xurl=$(command -v xurl >/dev/null 2>&1 && echo yes || echo no)
    have_xurl_dir=$([ -d "$HOME/.xurl" ] && echo yes || echo no)
    have_token=$([ -n "$X_BEARER_TOKEN" ] && echo yes || echo no)
    echo "x-research: auth not configured; skill unavailable this session" >&2
    echo "  X_BEARER_TOKEN set: $have_token" >&2
    echo "  xurl on PATH:       $have_xurl" >&2
    echo "  ~/.xurl exists:     $have_xurl_dir" >&2
    exit 1
fi

CI mode (AUTH_MODE=ci) — $X_BEARER_TOKEN is set (provisioned by the CI workflow as a repo secret). Calls go through curl with an Authorization: Bearer header. Tokens come from the X developer portal as App-only Bearer tokens, which are read-only (cannot post, like, DM, or act as a user). Don't paste a user OAuth2 access token into this secret — x_get won't validate token type, but a user token would expose write capability the skill is not designed to use.