X to Markdown
Converts X content to markdown:
Tweets/threads → Markdown with YAML front matter
X Articles → Full content extraction
Script Directory
Scripts located in
scripts/
subdirectory.
Path Resolution
:
SKILL_DIR
= this SKILL.md's directory
Script path =
${SKILL_DIR}/scripts/main.ts
Consent Requirement
Before any conversion
, check and obtain consent.
Consent Flow
Step 1: Check consent file

macOS

cat ~/Library/Application \ Support/tuzi-skills/x-to-markdown/consent.json

Linux

cat

~/.local/share/tuzi-skills/x-to-markdown/consent.json

Step 2

If

accepted: true

and

disclaimerVersion: "1.0"

→ print warning and proceed:

Warning: Using reverse-engineered X API. Accepted on:

Step 3

If missing or version mismatch → display disclaimer:

DISCLAIMER

This tool uses a reverse-engineered X API, NOT official.

Risks:

- May break if X changes API

- No guarantees or support

- Possible account restrictions

- Use at your own risk

Accept terms and continue?

Use

AskUserQuestion

with options: "Yes, I accept" | "No, I decline"

Step 4

On accept → create consent file:
{
"version"
:
1
,
"accepted"
:
true
,
"acceptedAt"
:
""
,
"disclaimerVersion"
:
"1.0"
}
Step 5: On decline → output "User declined. Exiting." and stop. Preferences (EXTEND.md) Use Bash to check EXTEND.md existence (priority order):

Check project-level first

test -f .tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md && echo "project"

Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)

test

-f

"

$HOME

/.tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md"

&&

echo

"user"

┌────────────────────────────────────────────────────────────┬───────────────────┐

│ Path │ Location │

├────────────────────────────────────────────────────────────┼───────────────────┤

│ .tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md │ Project directory │

│ $HOME/.tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md │ User home │

└────────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐

│ Result │ Action │

├───────────┼───────────────────────────────────────────────────────────────────────────┤

│ Found │ Read, parse, apply settings │

│ Not found │

MUST

run first-time setup (see below) — do NOT silently create defaults │

└───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md Supports

Download media by default | Default output directory
First-Time Setup (BLOCKING)
CRITICAL: When EXTEND.md is not found, you MUST use AskUserQuestion to ask the user for their preferences before creating EXTEND.md. NEVER create EXTEND.md with defaults without asking. This is a BLOCKING operation — do NOT proceed with any conversion until setup is complete. Use AskUserQuestion with ALL questions in ONE call: Question 1 — header: "Media", question: "How to handle images and videos in tweets?" "Ask each time (Recommended)" — After saving markdown, ask whether to download media "Always download" — Always download media to local imgs/ and videos/ directories "Never download" — Keep original remote URLs in markdown Question 2 — header: "Output", question: "Default output directory?" "x-to-markdown (Recommended)" — Save to ./x-to-markdown/{username}/{tweet-id}.md (User may choose "Other" to type a custom path) Question 3 — header: "Save", question: "Where to save preferences?" "User (Recommended)" — ~/.tuzi-skills/ (all projects) "Project" — .tuzi-skills/ (this project only) After user answers, create EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue. Full reference: references/config/first-time-setup.md Supported Keys Key Default Values Description download_media ask ask / 1 / 0 ask = prompt each time, 1 = always download, 0 = never default_output_dir empty path or empty Default output directory (empty = ./x-to-markdown/ ) Value priority : CLI arguments ( --download-media , -o ) EXTEND.md Skill defaults Usage npx -y bun ${SKILL_DIR} /scripts/main.ts < url

npx -y bun ${SKILL_DIR} /scripts/main.ts < url

-o output.md npx -y bun ${SKILL_DIR} /scripts/main.ts < url

--download-media npx -y bun ${SKILL_DIR} /scripts/main.ts < url

--json Options Option Description Tweet or article URL -o Output path --json JSON output --download-media Download image/video assets to local imgs/ and videos/ , and rewrite markdown links to local relative paths --login Refresh cookies only Supported URLs https://x.com//status/ https://twitter.com//status/ https://x.com/i/article/ Output

url : "https://x.com/user/status/123" author : "Name (@user)" tweetCount : 3 coverImage : "https://pbs.twimg.com/media/example.jpg"

Content... File structure : x-to-markdown/{username}/{tweet-id}/{content-slug}.md When --download-media is enabled: Images are saved to imgs/ next to the markdown file Videos are saved to videos/ next to the markdown file Markdown media links are rewritten to local relative paths Media Download Workflow Based on download_media setting in EXTEND.md: Setting Behavior 1 (always) Run script with --download-media flag 0 (never) Run script without --download-media flag ask (default) Follow the ask-each-time flow below Ask-Each-Time Flow Run script without --download-media → markdown saved Check saved markdown for remote media URLs ( https:// in image/video links) If no remote media found → done, no prompt needed If remote media found → use AskUserQuestion : header: "Media", question: "Download N images/videos to local files?" "Yes" — Download to local directories "No" — Keep remote URLs If user confirms → run script again with --download-media (overwrites markdown with localized links) Authentication Environment variables (preferred): X_AUTH_TOKEN , X_CT0 Chrome login (fallback): Auto-opens Chrome, caches cookies locally Extension Support Custom configurations via EXTEND.md. See Preferences section for paths and supported options.

安装

macOS

Linux

Check project-level first

Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)