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
subdirectory.
Path Resolution:
- = 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
bash
# 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
and
→ print warning and proceed:
Warning: Using reverse-engineered X API. Accepted on: <acceptedAt>
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
with options: "Yes, I accept" | "No, I decline"
Step 4: On accept → create consent file:
json
{
"version": 1,
"accepted": true,
"acceptedAt": "<ISO timestamp>",
"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):
bash
# 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 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
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 |
|---|
| | / / | = prompt each time, = always download, = never |
| empty | path or empty | Default output directory (empty = ) |
Value priority:
- CLI arguments (, )
- EXTEND.md
- Skill defaults
Usage
bash
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 |
| Output path |
| JSON output |
| Download image/video assets to local and , and rewrite markdown links to local relative paths |
| Refresh cookies only |
Supported URLs
https://x.com/<user>/status/<id>
https://twitter.com/<user>/status/<id>
https://x.com/i/article/<id>
Output
markdown
---
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
- Images are saved to next to the markdown file
- Videos are saved to next to the markdown file
- Markdown media links are rewritten to local relative paths
Media Download Workflow
Based on
setting in EXTEND.md:
| Setting | Behavior |
|---|
| (always) | Run script with flag |
| (never) | Run script without flag |
| (default) | Follow the ask-each-time flow below |
Ask-Each-Time Flow
- Run script without → markdown saved
- Check saved markdown for remote media URLs ( in image/video links)
- If no remote media found → done, no prompt needed
- If remote media found → use :
- 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 (overwrites markdown with localized links)
Authentication
- Environment variables (preferred): ,
- Chrome login (fallback): Auto-opens Chrome, caches cookies locally
Extension Support
Custom configurations via EXTEND.md. See Preferences section for paths and supported options.