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:
{baseDir} = this SKILL.md's directory
- Script path =
{baseDir}/scripts/main.ts
- Resolve
${BUN_X} runtime: if bun installed β bun; if npx available β npx -y bun; else suggest installing bun
Consent Requirement
Before any conversion, check and obtain consent.
Consent Flow
Step 1: Check consent file
cat ~/Library/Application\ Support/baoyu-skills/x-to-markdown/consent.json
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)
Check EXTEND.md existence (priority order):
test -f .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md" && echo "user"
if (Test-Path .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md") { "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
${BUN_X} {baseDir}/scripts/main.ts <url>
${BUN_X} {baseDir}/scripts/main.ts <url> -o output.md
${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
${BUN_X} {baseDir}/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
https://x.com/<user>/status/<id>
https://twitter.com/<user>/status/<id>
https://x.com/i/article/<id>
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.