---
name: xskill
description: Read and understand X/Twitter posts, threads, conversations, and search results through the xskill pay-per-use API. Use when the user provides an X/Twitter post URL, post ID, root thread URL, conversation ID, or search query and wants raw data, a summary, TLDR, structured JSON extraction, credit/top-up help, or image OCR/description status.
---

# xskill

Use xskill to fetch X/Twitter content through the user's prepaid xskill account. Never use the official X API.

## Setup

- API base: use `XSKILL_BASE_URL` when provided; otherwise use `https://api.xskill.md`.
- API key: use `XSKILL_API_KEY` when provided, or ask the user for an `xsk_` key.
- Auth header: `Authorization: Bearer <xsk_key>`.
- Never print, log, or include the key in final answers.

## Thread Workflow

1. Use the root conversation ID. For a root post URL such as `https://x.com/<user>/status/<id>`, the status ID is the conversation ID.
2. If the supplied URL is a reply or later tweet in a thread, ask for the root post URL/conversation ID before calling `/v1/thread`; do not spend credits on a known non-root reply ID.
3. Default to understanding the conversation with parsed summary:

```http
GET /v1/thread?id=<conversation_id>&mode=conversation&parse=summary
Authorization: Bearer <xsk_key>
```

4. Use `mode=thread` only when the user asks for the author's self-reply thread rather than all conversation replies.
5. Use `parse=tldr` for a one-sentence answer, `parse=json` for structured claims/entities/topics/links, or omit `parse` when the user asks for raw tweets.
6. Add `vision=true` when the user asks for image OCR, visible text, screenshots, charts, memes, or image descriptions attached to returned tweets.
7. Report the answer first, then mention important metadata only when useful: `data.truncated`, `usage.tweetsRead`, `usage.tweetsReturned`, `usage.vision.imagesAnalyzed`, and customer price from `usage.pricing` / `usage.vision.pricing`.

Example curl:

```sh
curl -sS \
  -H "Authorization: Bearer ${XSKILL_API_KEY}" \
  "${XSKILL_BASE_URL:-https://api.xskill.md}/v1/thread?id=<conversation_id>&mode=conversation&parse=summary"
```

## Post Workflow

Use this when the user asks for one specific post rather than the full conversation:

```http
GET /v1/post?id=<post_id>
Authorization: Bearer <xsk_key>
```

Add `parse=summary`, `parse=tldr`, or `parse=json` when the user asks to understand or extract from the post instead of only fetching raw data.

Add `vision=true` when the user asks for OCR or image descriptions for media attached to the post. Use `data.vision` or media-level `vision` fields for image results.

## Search Workflow

Use this when the user asks to search X/Twitter rather than fetch a known post or conversation:

```http
GET /v1/search?query=<x_search_query>&type=Latest
Authorization: Bearer <xsk_key>
```

Use `type=Top` only when the user asks for top-ranked results. Follow `data.pageInfo.nextCursor` with `cursor=<cursor>` when the user wants more results. Report `usage.tweetsReturned` and customer price from `usage.pricing` when useful.

## Error Handling

- `401 unauthorized`: ask for a valid `xsk_` key.
- `402 insufficient_balance`: explain that prepaid credits are depleted and offer to create a top-up Checkout link.
- `404 post_not_found`: say xskill could not find that post ID.
- `400 invalid_request`: re-check the post ID and query parameters.
- `503 provider_unavailable`, `parser_unavailable`, `vision_unavailable`, or `pricing_unavailable`: say which xskill dependency is unavailable and do not fabricate results.
- If `data.truncated` is true, say the thread may have more replies than returned.

## Top-Up Workflow

Create a Stripe Checkout top-up link only after the user explicitly asks to add credits. Minimum top-up is `1000` cents (`\$10.00`).
Before creating the link, show or mention the Terms of Service (`https://xskill.md/terms`) and Pricing and Refund Policy (`https://xskill.md/refund-policy`).

```http
POST /v1/topups/checkout
Authorization: Bearer <xsk_key>
Content-Type: application/json

{ "amountCents": 1000 }
```

Return only the `data.url` Checkout link and the amount. Do not claim credits are added until the payment completes and the webhook credits the ledger.

## Vision

For image OCR or image description, use `vision=true` on `/v1/thread` or `/v1/post`. Return only OCR/description present in `data.vision` or media-level `vision` fields. Do not invent OCR from images that xskill did not analyze.