X Fetcher

A command-line tool for fetching X (Twitter) post content, supporting regular tweets and X Article long-form articles, and automatically saving as Markdown format.

Engineering Source: This Skill is based on the Jane-xiaoer/x-fetcher project.

Features

Fetch regular tweets (text, images, video links)
Fetch X Article long-form articles (full content in Markdown format)
Get interaction data (likes, retweets, views, bookmark counts)
Automatically save as formatted Markdown files
Configurable default download directory

Script Directory

Scripts are located in the

scripts/

subdirectory.

Path Resolution:

```
SKILL_DIR
```
= Directory where this SKILL.md file is located
Script path =
```
${SKILL_DIR}/scripts/main.py
```

Preferences (EXTEND.md)

Use Bash to check if EXTEND.md exists (priority order):

bash

# Check project-level first
test -f .x-fetcher/EXTEND.md && echo "project"

# Then check user-level (cross-platform: $HOME works for macOS/Linux/WSL)
test -f "$HOME/.x-fetcher/EXTEND.md" && echo "user"

┌────────────────────────────────────┬───────────────────┐ │ Path │ Location │ ├────────────────────────────────────┼───────────────────┤ │ .x-fetcher/EXTEND.md │ Project directory │ ├────────────────────────────────────┼───────────────────┤ │ $HOME/.x-fetcher/EXTEND.md │ User home directory │ └────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ Result │ Action │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Found │ Read, parse, and apply settings │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Not found │ Must run initial setup (see below) — Do not silently create defaults │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md Support: Default download directory | Media handling method

Initial Setup (Blocking)

Key: When EXTEND.md is not found, you must use
AskUserQuestion
to ask the user for preferences before creating EXTEND.md. Never create EXTEND.md with default values without asking. This is a blocking operation — do not proceed with any conversion until setup is complete.

Use

AskUserQuestion

in one call to ask all questions:

Question 1 — header: "Download Directory", question: "Default directory path for saving tweets?"

"x-fetcher (Recommended)" — Save to ./x-fetcher/{username}/{tweet-id}.md
(User can select "Other" to enter a custom path)

Question 2 — header: "Save Location", question: "Where to save preferences?"

"User (Recommended)" — ~/.x-fetcher/ (all projects)
"Project" — .x-fetcher/ (this project only)

After the user answers, create EXTEND.md at the selected location, confirm "Preferences saved to [path]", then proceed.

Supported Configuration Keys

Key	Default Value	Optional Values	Description
`default_output_dir`	Empty	Path or empty	Default output directory (empty = `./x-fetcher/` )
`auto_save`	`true`	`true` / `false`	Automatically save Markdown files
`download_media`	`ask`	`ask` / `true` / `false`	Whether to download media files locally ( `ask` = ask every time, `true` = always download, `false` = never download)

Value Priority:

CLI parameters
EXTEND.md
Skill default values

Media Download Notes:

When
```
download_media
```
is set to
```
true
```
, images are saved to the
```
imgs/
```
directory, videos to the
```
videos/
```
directory
Media links in Markdown files are automatically updated to local relative paths
Supported media formats: Images (jpg, png, gif, webp), Videos (mp4, mov, webm)

Usage

bash

python3 ${SKILL_DIR}/scripts/main.py <url>
python3 ${SKILL_DIR}/scripts/main.py <url> --output /path/to/save
python3 ${SKILL_DIR}/scripts/main.py <url> --download-media
python3 ${SKILL_DIR}/scripts/main.py <url> --json

Options

Option	Description
`<url>`	Tweet or article URL
`--output <path>`	Output path (directory or file)
`--download-media`	Download image/video resources to local `imgs/` and `videos/` directories, and rewrite Markdown links to local relative paths
`--json`	Output in JSON format (do not save Markdown)
`--no-save`	Do not automatically save Markdown files

Supported URLs

```
https://x.com/<user>/status/<id>
```
```
https://twitter.com/<user>/status/<id>
```

Output

Regular Tweet

markdown

# Tweet from @username

> Author: **Author Name** (@username)
> Published: 2024-01-01 12:00:00
> Original Link: https://x.com/user/status/123

---

Tweet content...

## Media

![Media 1](https://pbs.twimg.com/media/example.jpg)

---

## Interaction Data

- ❤️ Likes: 1,234
- 🔁 Retweets: 567
- 👀 Views: 89,000
- 💬 Replies: 123

X Article Long-form Article

markdown

# Article Title

> Author: **Author Name** (@username)
> Published: 2024-01-01 12:00:00
> Updated: 2024-01-02 10:30:00
> Original Link: https://x.com/user/status/123

---

![Cover](https://pbs.twimg.com/media/example.jpg)

Full article content (Markdown format)...

---

## Interaction Data

- ❤️ Likes: 206,351
- 🔁 Retweets: 28,631
- 👀 Views: 115,555,283
- 🔖 Bookmarks: 571,495

File Structure:

{output_dir}/{username}/{tweet-id}.md

How It Works

Extract tweet ID from URL
Try fxtwitter API (supports Articles)
Fallback to syndication API
Parse and format output
Automatically save as Markdown file

Limitations

Depends on third-party APIs (fxtwitter), which may fail due to service changes
Cannot fetch content from private accounts
Some media content may not have complete URLs available

Dependencies

Python 3.6+
requests >= 2.25.0

Dependencies are automatically checked on first use, and installation commands will be prompted if not installed.

Extension Support

Custom configurations are supported via EXTEND.md. See the Preferences section for paths and supported options.

x-fetcher

NPX Install

Tags

SKILL.md Content (Chinese)