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/baoyu-skills/x-to-markdown/consent.json
Linux
cat ~/.local/share/baoyu-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: <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 AskUserQuestion with options: "Yes, I accept" | "No, I decline"
Step 4: On accept → create consent file:
{ "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):
Check project-level first
test -f .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md && echo "project"
Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md" && echo "user"
┌────────────────────────────────────────────────────────────┬───────────────────┐ │ Path │ Location │ ├────────────────────────────────────────────────────────────┼───────────────────┤ │ .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md │ Project directory │ ├────────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.baoyu-skills/baoyu-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)" — ~/.baoyu-skills/ (all projects)
-
"Project" — .baoyu-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
<url>
Tweet or article URL
-o <path>
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
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.