twitter-reader

Design Community

Repo stars 0
Author updated Aug 24, 2026, 03:33 PM
Author repo claude-code-skills

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Fetch Twitter/X post content including long-form Articles with full images and metadata. Use when Claude needs to retrieve tweet…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Quick Start (Recommended)”, “Example Output”, “Alternative: Jina API (Text-only)”, “Features”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name twitter-reader directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Quick Start (Recommended) / Example Output / Alternative: Jina API (Text-only)” before expanding.

Boundaries And Review

Dependencies: Prepare Vendor-specific API keys before running a full task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Twitter Reader

Fetch Twitter/X post and article content with full media support.

Quick Start (Recommended)

For X Articles with images, use the new fetch_article.py script:

uv run --with pyyaml python scripts/fetch_article.py <article_url> [output_dir]

Example:

uv run --with pyyaml python scripts/fetch_article.py \
  https://x.com/HiTw93/status/2040047268221608281 \
  ./Clippings

This will:

Fetch structured data via twitter-cli (likes, retweets, bookmarks)
Fetch content with images via jina.ai API
Download all images to attachments/YYYY-MM-DD-AUTHOR-TITLE/
Generate complete Markdown with embedded image references
Include YAML frontmatter with metadata

Example Output

Fetching: https://x.com/HiTw93/status/2040047268221608281
--------------------------------------------------
Getting metadata...
Title: 你不知道的大模型训练：原理、路径与新实践
Author: Tw93
Likes: 1648

Getting content and images...
Images: 15

Downloading 15 images...
  ✓ 01-image.jpg
  ✓ 02-image.jpg
  ...

✓ Saved: ./Clippings/2026-04-03-文章标题.md
✓ Images: ./Clippings/attachments/2026-04-03-HiTw93-.../ (15 downloaded)

Alternative: Jina API (Text-only)

For simple text-only fetching without authentication:

# Single tweet
curl "https://r.jina.ai/https://x.com/USER/status/TWEET_ID" \
  -H "Authorization: Bearer ${JINA_API_KEY}"

# Batch fetching
scripts/fetch_tweets.sh url1 url2 url3

Features

Full Article Mode (fetch_article.py)

✅ Structured metadata (author, date, engagement metrics)
✅ Automatic image download (all embedded media)
✅ Complete Markdown with local image references
✅ YAML frontmatter for PKM systems
✅ Handles X Articles (long-form content)

Simple Mode (Jina API)

Text-only content
No authentication required beyond Jina API key
Good for quick text extraction

Prerequisites

For Full Article Mode

uv (Python package manager)
No additional setup (twitter-cli auto-installed)

For Simple Mode (Jina)

export JINA_API_KEY="your_api_key_here"
# Get from https://jina.ai/

Output Structure

output_dir/
├── YYYY-MM-DD-article-title.md       # Main Markdown file
└── attachments/
    └── YYYY-MM-DD-author-title/
        ├── 01-image.jpg
        ├── 02-image.jpg
        └── ...

What Gets Returned

Full Article Mode

YAML Frontmatter: source, author, date, likes, retweets, bookmarks
Markdown Content: Full article text with local image references
Attachments: All downloaded images in dedicated folder

Simple Mode

Title: Post author and content preview
URL Source: Original tweet link
Published Time: GMT timestamp
Markdown Content: Text with remote media URLs

URL Formats Supported

https://x.com/USER/status/ID (posts)
https://x.com/USER/article/ID (long-form articles)
https://twitter.com/USER/status/ID (legacy)

Scripts

fetch_article.py

Full-featured article fetcher with image download:

uv run --with pyyaml python scripts/fetch_article.py <url> [output_dir]

fetch_tweet.py

Simple text-only fetcher using Jina API:

python scripts/fetch_tweet.py <tweet_url> [output_file]

fetch_tweets.sh

Batch fetch multiple tweets (Jina API):

scripts/fetch_tweets.sh <url1> <url2> ...

Migration from Jina API

Old workflow:

curl "https://r.jina.ai/https://x.com/..."
# Manual image extraction and download

New workflow:

uv run --with pyyaml python scripts/fetch_article.py <url>
# Automatic image download, complete Markdown

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Design
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @daymade · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: Required · Vendor-specific
Detected OS requirements: Unspecified
Runtime requirements: Python
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview twitter-reader.preview

# Example Output

Fetching: https://x.com/HiTw93/status/2040047268221608281
--------------------------------------------------
Getting metadata...
Title: 你不知道的大模型训练：原理、路径与新实践
Author: Tw93
Likes: 1648

Getting content and images...
Images: 15

Downloading 15 images...
  ✓ 01-image.jpg
  ✓ 02-image.jpg
  ...

✓ Saved: ./Clippings/2026-04-03-文章标题.md
✓ Images: ./Clippings/attachments/2026-04-03-HiTw93-.../ (15 downloaded)

SKILL.md SKILL.md

# Twitter Reader

Fetch Twitter/X post and article content with full media support.

## Quick Start (Recommended)

For X Articles with images, use the new fetch_article.py script:

```bash
uv run --with pyyaml python scripts/fetch_article.py <article_url> [output_dir]
```

Example:
```bash
uv run --with pyyaml python scripts/fetch_article.py \
  https://x.com/HiTw93/status/2040047268221608281 \
  ./Clippings
```

This will:
- Fetch structured data via `twitter-cli` (likes, retweets, bookmarks)
- Fetch content with images via `jina.ai` API
- Download all images to `attachments/YYYY-MM-DD-AUTHOR-TITLE/`
- Generate complete Markdown with embedded image references
- Include YAML frontmatter with metadata

### Example Output

```
Fetching: https://x.com/HiTw93/status/2040047268221608281
--------------------------------------------------
Getting metadata...
Title: 你不知道的大模型训练：原理、路径与新实践
Author: Tw93
Likes: 1648

Getting content and images...
Images: 15

Downloading 15 images...
  ✓ 01-image.jpg
  ✓ 02-image.jpg
  ...

✓ Saved: ./Clippings/2026-04-03-文章标题.md
✓ Images: ./Clippings/attachments/2026-04-03-HiTw93-.../ (15 downloaded)
```

## Alternative: Jina API (Text-only)

For simple text-only fetching without authentication:

```bash
# Single tweet
curl "https://r.jina.ai/https://x.com/USER/status/TWEET_ID" \
  -H "Authorization: Bearer ${JINA_API_KEY}"

# Batch fetching
scripts/fetch_tweets.sh url1 url2 url3
```

## Features

### Full Article Mode (fetch_article.py)
- ✅ Structured metadata (author, date, engagement metrics)
- ✅ Automatic image download (all embedded media)
- ✅ Complete Markdown with local image references
- ✅ YAML frontmatter for PKM systems
- ✅ Handles X Articles (long-form content)

### Simple Mode (Jina API)
- Text-only content

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Quick Start (Recommended) → Example Output → Alternative: Jina API (Text-only) → Features → Full Article Mode (fetcharticle.py) → Simple Mode (Jina API)
terms    -> YAML Frontmatter · Markdown Content · Attachments · Title · URL Source · Published Time
files/cmd -> twitter-cli · jina.ai · attachments/YYYY-MM-DD-AUTHOR-TITLE/ · https://x.com/USER/status/ID · https://x.com/USER/article/ID · https://twitter.com/USER/status/ID
body sha256 -> e4f2bee4b356