1---
2name: baoyu-danger-x-to-markdown
3description: Converts X (Twitter) tweets and articles to markdown with YAML front matter. Uses reverse-engineered API requiring user consent. Use when user mentions "X to markdown", "tweet to markdown", "save tweet", or provides x.com/twitter.com URLs for conversion.
4version: 1.56.1
5metadata:
6  openclaw:
7    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-danger-x-to-markdown
8    requires:
9      anyBins:
10        - bun
11        - npx
12---
13 
14# X to Markdown
15 
16Converts X content to markdown:
17- Tweets/threads → Markdown with YAML front matter
18- X Articles → Full content extraction
19 
20## User Input Tools
21 
22When this skill prompts the user, follow this tool-selection rule (priority order):
23 
241. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
252. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
263. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
27 
28Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
29 
30## Script Directory
31 
32Scripts located in `scripts/` subdirectory.
33 
34**Path Resolution**:
351. `{baseDir}` = this SKILL.md's directory
362. Script path = `{baseDir}/scripts/main.ts`
373. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun
38 
39## Consent Requirement
40 
41**Before any conversion**, check and obtain consent.
42 
43### Consent Flow
44 
45**Step 1**: Check consent file
46 
47```bash
48# macOS
49cat ~/Library/Application\ Support/baoyu-skills/x-to-markdown/consent.json
50 
51# Linux
52cat ~/.local/share/baoyu-skills/x-to-markdown/consent.json
53```
54 
55**Step 2**: If `accepted: true` and `disclaimerVersion: "1.0"` → print warning and proceed:
56```
57Warning: Using reverse-engineered X API. Accepted on: <acceptedAt>
58```
59 
60**Step 3**: If missing or version mismatch → display disclaimer:
61```
62DISCLAIMER
63 
64This tool uses a reverse-engineered X API, NOT official.
65 
66Risks:
67- May break if X changes API
68- No guarantees or support
69- Possible account restrictions
70- Use at your own risk
71 
72Accept terms and continue?
73```
74 
75Use `AskUserQuestion` with options: "Yes, I accept" | "No, I decline"
76 
77**Step 4**: On accept → create consent file:
78```json
79{
80  "version": 1,
81  "accepted": true,
82  "acceptedAt": "<ISO timestamp>",
83  "disclaimerVersion": "1.0"
84}
85```
86 
87**Step 5**: On decline → output "User declined. Exiting." and stop.
88 
89## Preferences (EXTEND.md)
90 
91Check EXTEND.md in priority order — the first one found wins:
92 
93| Priority | Path | Scope |
94|----------|------|-------|
95| 1 | `.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md` | Project |
96| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md` | XDG |
97| 3 | `$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md` | User home |
98 
99| Result | Action |
100|--------|--------|
101| Found | Read, parse, apply settings |
102| Not found | **MUST** run first-time setup (see below) — do NOT silently create defaults |
103 
104**EXTEND.md supports**: Download media by default, default output directory.
105 
106### First-Time Setup (BLOCKING)
107 
108**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.
109 
110Use `AskUserQuestion` with ALL questions in ONE call:
111 
112**Question 1** — header: "Media", question: "How to handle images and videos in tweets?"
113- "Ask each time (Recommended)" — After saving markdown, ask whether to download media
114- "Always download" — Always download media to local imgs/ and videos/ directories
115- "Never download" — Keep original remote URLs in markdown
116 
117**Question 2** — header: "Output", question: "Default output directory?"
118- "x-to-markdown (Recommended)" — Save to ./x-to-markdown/{username}/{tweet-id}.md
119- (User may choose "Other" to type a custom path)
120 
121**Question 3** — header: "Save", question: "Where to save preferences?"
122- "User (Recommended)" — ~/.baoyu-skills/ (all projects)
123- "Project" — .baoyu-skills/ (this project only)
124 
125After user answers, create EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue.
126 
127Full reference: [references/config/first-time-setup.md](references/config/first-time-setup.md)
128 
129### Supported Keys
130 
131| Key | Default | Values | Description |
132|-----|---------|--------|-------------|
133| `download_media` | `ask` | `ask` / `1` / `0` | `ask` = prompt each time, `1` = always download, `0` = never |
134| `default_output_dir` | empty | path or empty | Default output directory (empty = `./x-to-markdown/`) |
135 
136**Value priority**:
1371. CLI arguments (`--download-media`, `-o`)
1382. EXTEND.md
1393. Skill defaults
140 
141## Usage
142 
143```bash
144${BUN_X} {baseDir}/scripts/main.ts <url>
145${BUN_X} {baseDir}/scripts/main.ts <url> -o output.md
146${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
147${BUN_X} {baseDir}/scripts/main.ts <url> --json
148```
149 
150## Options
151 
152| Option | Description |
153|--------|-------------|
154| `<url>` | Tweet or article URL |
155| `-o <path>` | Output path |
156| `--json` | JSON output |
157| `--download-media` | Download image/video assets to local `imgs/` and `videos/`, and rewrite markdown links to local relative paths |
158| `--login` | Refresh cookies only |
159 
160## Supported URLs
161 
162- `https://x.com/<user>/status/<id>`
163- `https://twitter.com/<user>/status/<id>`
164- `https://x.com/i/article/<id>`
165 
166## Output
167 
168```markdown
169---
170url: "https://x.com/user/status/123"
171author: "Name (@user)"
172tweetCount: 3
173coverImage: "https://pbs.twimg.com/media/example.jpg"
174---
175 
176Content...
177```
178 
179**File structure**: `x-to-markdown/{username}/{tweet-id}/{content-slug}.md`
180 
181When `--download-media` is enabled:
182- Images are saved to `imgs/` next to the markdown file
183- Videos are saved to `videos/` next to the markdown file
184- Markdown media links are rewritten to local relative paths
185 
186## Media Download Workflow
187 
188Based on `download_media` setting in EXTEND.md:
189 
190| Setting | Behavior |
191|---------|----------|
192| `1` (always) | Run script with `--download-media` flag |
193| `0` (never) | Run script without `--download-media` flag |
194| `ask` (default) | Follow the ask-each-time flow below |
195 
196### Ask-Each-Time Flow
197 
1981. Run script **without** `--download-media` → markdown saved
1992. Check saved markdown for remote media URLs (`https://` in image/video links)
2003. **If no remote media found** → done, no prompt needed
2014. **If remote media found** → use `AskUserQuestion`:
202   - header: "Media", question: "Download N images/videos to local files?"
203   - "Yes" — Download to local directories
204   - "No" — Keep remote URLs
2055. If user confirms → run script **again** with `--download-media` (overwrites markdown with localized links)
206 
207## Authentication
208 
2091. **Environment variables** (preferred): `X_AUTH_TOKEN`, `X_CT0`
2102. **Chrome login** (fallback): Auto-opens Chrome, caches cookies locally
211 
212## Extension Support
213 
214Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.
215