Home / All Skills / Content & Media Creation / baoyu-danger-x-to-markdown
English (EN)简体中文 (ZH)日本語 (JA)
Content & Media Creation · JimLiu/baoyu-skills

baoyu-danger-x-to-markdown

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.

L5 Restricted · Isolated sandbox & strict auditV2 Human-AuditedReverse APITerms / ComplianceCredential / SessionExecute CommandNetwork AccessWrite FileDual-pass Audit
Author JimLiuGitHub JimLiu/baoyu-skills ↗Stars 25926License MIT（仓库根 LICENSE，Copyright (c) 2026 Jim Liu；GitHub API license.spdx_id=MIT）Commit 1567581c26
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The core mechanism is reverse-engineering X's GraphQL API: it scrapes queryId and featureSwitches from the HTML of x.com pages, then interpolates variables into /i/api/graphql/<queryId>/<Operation> requests.

skills/baoyu-danger-x-to-markdown/scripts/graphql.ts
const url = new URL(`https://x.com/i/api/graphql/${queryInfo.queryId}/TweetResultByRestId`);
Each of the three operations has its own scraping logic and fallback constants: TweetResultByRestId (single tweet), TweetDetail (thread), and ArticleEntityResultByRestId (X Article); when scraping fails, it falls back to FALLBACK_QUERY_ID and FALLBACK_FEATURE_SWITCHES.

Requests carry X's public web bearer token and a fixed User-Agent—serving as a way to impersonate the official web client, which is why it does not require an official API key.

skills/baoyu-danger-x-to-markdown/scripts/constants.ts
export const DEFAULT_BEARER_TOKEN =
The same file hardcodes a Chrome 130 User-Agent (DEFAULT_USER_AGENT); featureSwitches is a constant list containing over a hundred feature switch names (FALLBACK_*_FEATURE_SWITCHES).

Authentication relies on cookies: it checks environment variables X_AUTH_TOKEN / X_CT0 (optionally X_GUEST_TOKEN / X_TWID) first, followed by a local cookie file, and finally reads from Chrome via CDP.

skills/baoyu-danger-x-to-markdown/scripts/cookies.ts
const authToken = process.env.X_AUTH_TOKEN?.trim();
The only strictly required cookies are auth_token and ct0 (X_REQUIRED_COOKIES); cookies matching the x.com domain with path=/ are prioritized, and the loaded source is logged.

Fetched tweets/articles are converted into markdown: threads are linked following TweetDetail conversation structures, Articles use full text from articleEntity, quoted tweets are parsed separately, and output files are generated with YAML front matter.

skills/baoyu-danger-x-to-markdown/SKILL.md
**File structure**: `x-to-markdown/{username}/{tweet-id}/{content-slug}.md`
Front matter includes url, author, tweetCount, and coverImage; thread pages are handled by thread.ts/thread-markdown.ts, quoted tweets by referenced-tweets.ts, and Articles by tweet-article.ts.

Media localization is an optional step: enabling --download-media downloads images/videos to sibling imgs/ and videos/ directories relative to the markdown file, rewriting links to relative local paths.

skills/baoyu-danger-x-to-markdown/scripts/media-localizer.ts
if (hostname.includes("video.twimg.com")) return "video";
Downloads are executed via fetch(toHighResUrl(url)): images from pbs.twimg.com are rewritten to high-resolution URLs with appended format parameters; local storage operations use mkdir + writeFile.

Consent gating is strictly enforced: if consent.json (accepted + disclaimerVersion 1.0) is missing, it must display the disclaimer to the user and obtain explicit consent; it exits immediately if declined.

skills/baoyu-danger-x-to-markdown/SKILL.md
This tool uses a reverse-engineered X API, NOT official.
The consent file path is platform-dependent as defined in SKILL.md (macOS: ~/Library/Application Support, Linux: ~/.local/share under baoyu-skills/x-to-markdown/consent.json).

Initial setup is also mandatory: when EXTEND.md does not exist, an interactive tool prompt must ask for preferences (media processing policy, default output directory, save location); silently writing default values is explicitly forbidden.

skills/baoyu-danger-x-to-markdown/SKILL.md
**CRITICAL**: When EXTEND.md is not found, you **MUST use `AskUserQuestion`** to ask the user for their preferences before creating EXTEND.md.
EXTEND.md only supports two keys: download_media (ask/1/0) and default_output_dir; priority order is CLI > EXTEND.md > default.

Media handling defaults to 'generate markdown first, then ask': it runs once without media download flags, checks if the output still contains remote media URLs, and only prompts whether to download and re-runs to overwrite links if remote media is found.

skills/baoyu-danger-x-to-markdown/SKILL.md
5. If user confirms → run script **again** with `--download-media` (overwrites markdown with localized links)
The script itself only evaluates the --download-media boolean flag; the ask workflow is entirely orchestrated by the agent according to documentation.

2Core Capabilities

01Single tweet / long thread → markdown (TweetResultByRestId + TweetDetail)
02X Article full-text extraction (ArticleEntityResultByRestId)
03YAML front matter output (url/author/tweetCount/coverImage)
04Media localization (imgs/ and videos/ + link rewriting + high-resolution image URL rewriting)
05Three-way cookie retrieval (env → local file → Chrome CDP) and --login refresh
06Consent gating and mandatory interactive first-time setup (consent.json + EXTEND.md 3-question prompt)
07--json structured output and -o specified output paths
08Dynamic scraping of queryId/featureSwitches + fallback constants (resilient to X frontend changes)

3External Dependencies

KindDependency / Endpoint
networkx.com（GraphQL /i/api/graphql/… 与首页 HTML 抓 queryId）
networkpbs.twimg.com（图片媒体下载）
networkvideo.twimg.com（视频媒体下载）
packagebaoyu-chrome-cdp ^0.1.1（npm，CDP 取 cookie）
clibun / npx（${BUN_X} 运行时）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Isolated environment, per-use explicit authorization
For Administrators
Strict authorization, full audit, compliance signoff
Evidence & Triggers (File Paths & Excerpts)
  • SKILL.md / 脚本: Invokes unreleased or reverse-engineered private APIs / spoofs client identifiers
  • SKILL.md / 脚本参数: Involves bypassing automated detection, disabling host sandboxes, or skipping SSL certificate validation
  • SKILL.md / 会话存储: Reads or reuses browser user login states and session cookies
  • 本地凭据 / 浏览器配置: Reads user login cookies/sessions/keyrings: cookies: auth_token, ct0 (required), optionally gt, twid; sources = env (X_AUTH_TOKEN / X_CT0 / X_GUEST)
  • scripts/: Executes local scripts or commands: scripts/main.ts (executed via bun; launches/attaches to Chrome debugging sessions on demand to read cookies)
  • 网络端点: Declares external network access: https://x.com/i/api/graphql/<queryId>/<Operation> (TweetResultByRestId / Twe)
  • 本地工作目录: File read/write and artifact output: x-to-markdown/{username}/{tweet-id}/{content-slug}.md (or path specified by -o)
Audit Notes: (Classified at capability/policy level, not malicious implant). (a) Reverse-engineered API + official client impersonation: Instead of using official APIs, it scrapes queryId and featureSwitches from x.com web pages, directly querying private /i/api/graphql endpoints with a hardcoded web bearer token and fixed Chrome UA (DEFAULT_BEARER_TOKEN / DEFAULT_USER_AGENT in constants.ts). (b) Credential access: To pass authorization, it reads and utilizes account cookies auth_token + ct0 (via env, local cookie files, or baoyu-chrome-cdp using CDP from local Chrome); README explicitly warns 'Account restrictions possible if API usage detected'. (c) Architectural divergence: While baoyu-post-to-x in the same repository uses genuine UI + CDP automation (classified separately), this skill crafts requests to private APIs, which is equivalent to bypassing official interfaces and access controls, resulting in a Red rating. Context: No TLS validation downgrades, no anti-automation evasion like navigator.webdriver patching, no targeted batch scraping, and no arbitrary code execution found; media downloading occurs only when --download-media is specified.

5Second-Pass Verification

  • [ok] 逆向 GraphQL 请求 + 客户端冒充（red 主因） — graphql.ts 从首页 HTML 抓 queryId/featureSwitches，拼 https://x.com/i/api/graphql/${queryId}/Operation；constants.ts 提供 FALLBACK_QUERY_ID 与硬编码 bearer/UA。
  • [ok] 浏览 cookie 读取 — cookies.ts：buildInlineCookiesFromEnv 读 X_AUTH_TOKEN/X_CT0/X_GUEST_TOKEN/X_TWID；loadXCookiesFromFile 读本地文件；loadXCookiesFromCdp 经 CDP 取；hasRequiredXCookies 校验 auth_token 与 ct0。
  • [ok] 媒体下载范围 — media-localizer.ts 仅对 pbs.twimg.com / video.twimg.com 判定类型并 fetch 下载，且只在 --download-media 路径调用（SKILL.md 的三态策略）。
  • [ok] 两道用户门禁 — SKILL.md：consent.json（accepted + disclaimerVersion 1.0）与 EXTEND.md 首次设置（三问，禁止静默默认），后者被单独标为 BLOCKING。
  • [ok] 无 TLS 降级 / 无 stealth 伪装 / 无任意代码执行 — 相关 token 全目录零命中；入口是单个 URL；无 eval/动态 import 远程模块。
  • [ok] 与 baoyu-post-to-x 的路线差异（避免档位观感不一致） — post-to-x 走真实 UI + CDP 自动化（另行定级）；本 skill 走私有 API 伪造请求 → red。差异来源是技术路线，已在 reason 写明。
  • [ok] meta 元数据 — GitHub API：MIT、25926 stars、pushed_at 2026-09-10T15:13:43Z；本地 HEAD 与 pin 1567581c26ec… 一致。

6Verdict & Scenarios

  • Archiving-friendly: outputs a fixed directory structure and YAML front matter, ideal for long-term X content preservation and static site generation.
  • Resilient to frontend changes: dynamically scrapes queryId and featureSwitches alongside fallback constants, offering recovery margins when X updates its frontend.
  • Optional media localization: downloads images and videos to local relative paths with one click, preserving offline archives without broken images.
  • Flexible credential retrieval: supports direct env vars, cookie files, and browser login, making it suitable for both CI and local setups.
  • Strict gating: reverse-engineering disclaimer consent and initial preferences both mandate user interaction, avoiding silent default overrides.
    • Best for: Ideal for personal content archiving and material curation: converting long threads and X Articles into searchable markdown (paired with --download-media for complete offline archives), or as a material ingestion step prior to article writing.
    Not for: Not suitable for corporate compliance environments or high-frequency usage on primary accounts; not suitable for batch scraping requiring official support and stable SLAs (the skill operates on single URLs, not batches); not suitable for scenarios where storing cookies, consent files, or archive files locally is undesirable.
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload baoyu-danger-x-to-markdown.tar.gz
    sha256: bb27420994157cc5…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 1567581c26.