# Publish X Article Publish Markdown content to X (Twitter) Articles editor, preserving formatting with rich text conversion. Automatically handles X Premium limitations by converting unsupported elements to images. ## Credits This skill is inspired by and based on [wshuyi/x-article-publisher-skill](). Thank you to the original author for the foundational work. ## Interactive Setup: Ask Subscription Type **IMPORTANT** : Before processing the article, ask the user about their X subscription type if not already known. ### Prompt the User Before publishing, I need to know your X subscription type to handle formatting correctly: 1. **X Premium** - Basic tier ($8/month) 2. **X Premium+** - Plus tier ($16/month) Which subscription do you have? (Premium / Premium+) For Chinese users: 在发布之前，我需要了解您的 X 订阅类型以正确处理格式： 1. **X Premium** - 基础版 ($8/月) 2. **X Premium+** - 高级版 ($16/月) 您使用的是哪个版本？ (Premium / Premium+) ### Remember the Answer Once the user answers, remember their subscription type for the rest of the session. Don't ask again unless they explicitly want to change it. ## X Subscription Feature Comparison Feature | X Premium | X Premium+ ---|---|--- H1 headers (`#`) | Title only | Title only H2 headers (`##`) | Yes | Yes H3+ headers (`###`, etc.) | **No** | Yes Markdown tables | **No** | Yes Mermaid diagrams | **No** | **No** (not supported by X) Code blocks | Blockquotes | Blockquotes Bold, italic, links | Yes | Yes Lists | Yes | Yes Blockquotes | Yes | Yes Images | Yes | Yes ### Pre-Processing Required by Subscription **X Premium (Basic):** * Convert H3+ headers → H2 or bold * Convert tables → PNG images * Convert mermaid → PNG images **X Premium+ (Plus):** * Keep H3+ headers as-is * Keep tables as-is (rendered natively) * Convert mermaid → PNG images (still not supported) ## Prerequisites * Playwright MCP for browser automation * User logged into X with Premium subscription * Python 3.9+ with dependencies: * macOS: `pip install Pillow pyobjc-framework-Cocoa markdown` * Windows: `pip install Pillow pywin32 clip-util markdown` * diagram-to-image skill (for converting tables/mermaid to PNG via diagramless.xyz API) ## Scripts Located in `~/.claude/skills/publish-x-article/scripts/`: ### parse_markdown.py Parse Markdown and extract structured data: python parse_markdown.py [--output json|html] [--html-only] Returns JSON with: title, cover_image, content_images (with block_index for positioning), html, total_blocks ### copy_to_clipboard.py Copy image or HTML to system clipboard: # Copy image (with optional compression) python copy_to_clipboard.py image /path/to/image.jpg [--quality 80] # Copy HTML for rich text paste python copy_to_clipboard.py html --file /path/to/content.html ### diagram-to-image.mjs (from diagram-to-image skill) Convert Mermaid diagrams and Markdown tables to PNG images via diagramless.xyz API: node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table.png node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram.png --theme ocean ## Pre-Processing: Handle Unsupported Elements **Before** publishing, scan the Markdown for unsupported elements and convert them to images. ### Step 0: Analyze Content for Limitations # Check the markdown file for unsupported elements cat /path/to/article.md Look for: 1. **Deep headers (H3+)** : `###`, `####`, etc. 2. **Markdown tables** : Lines with `|` characters forming table structure 3. **Mermaid code blocks** : ` ```mermaid` ### Converting Unsupported Elements to Images #### 1\. Markdown Tables → PNG 当检测到表时： # 1. 将表提取到临时文件猫 > /tmp/table.md << 'TABLE_EOF' |第 1 栏 |第 2 栏 |第 3 栏 | |----------|----------|----------| |数据1 |数据2 |数据3 | TABLE_EOF # 2.通过diagramless.xyz API转换为图像节点〜/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table-001.png # 3. 用图像引用替换 markdown 中的表格 # ![表说明](/tmp/table-001.png) #### 2\.美人鱼图 → PNG 当检测到美人鱼块时： # 1. 将美人鱼提取到临时文件猫 > /tmp/diagram.mmd << 'MERMAID_EOF' 流程图TD A[开始] --> B[进程] B --> C[结束] 美人鱼_EOF # 2.通过diagramless.xyz API转换为图像节点〜/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram-001.png # 3. 用图像参考替换 markdown 中的美人鱼块 # ![图表说明](/tmp/diagram-001.png) #### 3\.深标题 (H3+) → 简化结构 **目标：** 在 X Premium 的仅限 H2 限制范围内工作时，保留文章的逻辑结构和可读性。 **人工智能指南：** 当您在高级用户的文章中遇到 H3、H4 或更深的标题时，请考虑作者的意图： * **如果标题在某个部分下引入了不同的子主题**，请将其转换为 **粗体文本** 作为段落开头。这可以在不破坏 X 格式的情况下保持视觉层次结构。 * **如果标题是一个主要部分，并且恰好是 H3** ，请考虑将其提升为 H2 — 但前提是这不会创建扁平、无意义的结构。文章仍然应该逻辑流畅。 * **如果有很深的层次结构** (H2 → H3 → H4)，请深思熟虑地扁平化： * 将 H2 保留为 H2 * 将 H3 转换为**粗体段落** * 将 H4 转换为斜体或自然合并到段落中 * **在结构上保留意义。** 像“### Why This Matters”这样的标题可能会成为一个粗体导入：“**Why does this important?**”，后面跟着内容。运用你的判断力。 * **阅读内容。** 如果 H3 标题只是“示例”或“注释”，那么它作为块引用或内联强调可能比独立的粗线效果更好。我们的目标不是机械转换——而是创建一篇在 X 上可读性好的文章，同时尊重作者的意图。 ### 预处理工作流程发布之前，请通读文章并为 X 做好准备： 1. **理解文章的结构** - 首先阅读它。主要有哪些部分？作者如何使用标题来组织想法？ 2. **处理表格和美人鱼图** - 这些需要变成图像。提取每一个，转换为 PNG，并记下它们应插入的位置。 3. **调整订阅层的标头：** * 对于 **Premium+ 用户**：保持标题不变（支持 H3+） * 对于**高级用户**：深思熟虑地重组 H3+ 标题，同时保留文章的流程和意图（请参阅上面的指南） 4. **创建修改后的 markdown** — 将修改后的版本保存到临时文件中，准备进行解析。目标是一篇在 X 上自然阅读的文章，而不是机械转换的文档。 ## 主要工作流程 **策略：“先文后图后分割线”（文本第一，图像第二，分隔符最后）** 对于包含图像和分隔线的文章，请先粘贴所有文本内容，然后使用块索引将图像和分隔线插入到正确的位置。 1. **Pre-process** : Convert tables/mermaid to images, flatten deep headers 2. Parse modified Markdown with Python script → get title, images, dividers (all with block_index), HTML 3. Navigate to X Articles editor 4. Upload cover image (first image) 5. Fill title 6. Copy HTML to clipboard (Python) → Paste with Cmd+V 7. Insert content images at positions specified by block_index 8. **Insert dividers at positions specified by block_index** (via Insert > Divider menu) 9. Save as draft (NEVER auto-publish) ## 高效执行原则 (Efficiency Guidelines) **目标** : 最小化操作之间的等待时间，实现流畅的自动化体验。 ### 1\. 避免不必要的 browser_snapshot 大多数浏览器操作（click, type, press_key 等）都会在返回结果中包含页面状态。 **不要** 在每次操作后单独调用 `browser_snapshot`，直接使用操作返回的页面状态即可。 ❌ 错误做法： browser_click → browser_snapshot → 分析 → browser_click → browser_snapshot → ... ✅ 正确做法： browser_click → 从返回结果中获取页面状态 → browser_click → ... ### 2\. 避免不必要的 browser_wait_for 只在以下情况使用 `browser_wait_for`： * 等待图片上传完成（`textGone="正在上传媒体"`） * 等待页面初始加载（极少数情况） **不要** 使用 `browser_wait_for` 来等待按钮或输入框出现 - 它们在页面加载完成后立即可用。 ### 3\. 并行执行独立操作当两个操作没有依赖关系时，可以在同一个消息中并行调用多个工具： ✅ 可以并行： - 填写标题 (browser_type) + 复制HTML到剪贴板 (Bash) - 解析Markdown生成JSON + 生成HTML文件 ❌ 不能并行（有依赖）： - 必须先点击create才能上传封面图 - 必须先粘贴内容才能插入图片 ### 4\. 连续执行浏览器操作每个浏览器操作返回的页面状态包含所有需要的元素引用。直接使用这些引用进行下一步操作： # 理想流程（每步直接执行，不额外等待）： browser_navigate → 从返回状态找create按钮 → browser_click(create) → 从返回状态找上传按钮 → browser_click(上传) → browser_file_upload → 从返回状态找应用按钮 → browser_click(应用) → 从返回状态找标题框 → browser_type(标题) → 点击编辑器 → browser_press_key(Meta+v) → ... ### 5\. 准备工作前置在开始浏览器操作之前，先完成所有准备工作： 1. 扫描不支持的元素（表格、Mermaid、深层标题） 2. 转换表格/Mermaid 为图片 3. 解析 Markdown 获取 JSON 数据 4. 生成 HTML 文件到 /tmp/ 5. 记录 title、cover_image、content_images 等信息这样浏览器操作阶段可以连续执行，不需要中途停下来处理数据。 ## Step 0: Read and Adapt the Article **First, read the article.** Understand what it's about, how it's structured, and what the author is trying to communicate. ### Preserve the Original **IMPORTANT:** Never modify the user's original file. If adaptations are needed: 1. Save the adapted version as a copy (e.g., `/tmp/article_adapted.md` or alongside the original as `article_for_x.md`) 2. Tell the user what was changed and where both files are: I've adapted your article for X Premium. Here's what changed: - Converted 2 tables to images - Restructured 3 H3 headers to bold text for better flow Original preserved: /path/to/article.md Adapted version: /path/to/article_for_x.md 3. Proceed with the adapted copy for publishing This ensures the user can review the changes and keeps their original work intact. ### Adaptation Based on Subscription ### For Premium Users (Basic Tier) Ask yourself: * Are there tables? → Convert each to a PNG image * Are there mermaid diagrams? → Convert each to a PNG image * Are there H3+ headers? → Restructure them thoughtfully (see header guidelines above) Create a modified version of the markdown that will work within Premium's limitations while preserving readability. ### For Premium+ Users Ask yourself: * Are there mermaid diagrams? → Convert to PNG (still not supported on any tier) * Tables and H3+ headers can stay as-is ### Converting Elements to Images # Tables → PNG (auto-detected as table) node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table-1.md -o /tmp/table-1.png # Mermaid → PNG (auto-detected as mermaid) node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram-1.mmd -o /tmp/diagram-1.png Replace these elements in the markdown with image references, positioning them where the original element was. ## Step 1: Parse Markdown (Python) 使用 parse_markdown.py 提取所有结构化数据： python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /path/to/modified_article.md 输出 JSON： { "title": "文章标题", "cover_image": "/path/to/first-image.jpg", “内容图像”：[ {"path": "/tmp/table-1.png", "block_index": 5, "after_text": "上下文..."}, {“path”：“/tmp/mermaid-1.png”，“block_index”：12，“after_text”：“另一个上下文...”} ], “分隔符”：[ {"block_index": 7, "after_text": "分隔符之前的上下文..."}, {“block_index”：15，“after_text”：“另一个上下文...”} ], "html": "

内容...

部分

...", “总块数”：45 } **关键字段：** * `block_index`：图像/分隔符应插入到该索引处的块元素之后（0索引） * `total_blocks`: HTML 中块元素的总数 * `after_text`：仅供参考/调试，不用于定位 * `dividers`：分隔符位置数组（markdown `---` 必须通过 X 的菜单插入，而不是 HTML `

`）将 HTML 保存到剪贴板的临时文件： python parse_markdown.py modded_article.md --html-only > /tmp/article_html.html ## 步骤 2：打开 X 文章编辑器 browser_navigate：https://x.com/compose/articles **重要**：页面加载后会显示草稿列表，不是编辑器。需要： 1. **等待页面加载完成** : 使用`browser_snapshot`检查页面状态 2. **立即点击“创建”按钮** : 不要等待“添加标题”等编辑器元素，它们只有点击创建后才出现 3. **等待编辑器加载** : 点击创建后，等待编辑器元素出现 # 1. 导航到页面 browser_navigate：https://x.com/compose/articles # 2.获取页面快照，找到创建按钮浏览器快照 # 3. 点击创建按钮（通常参考类似“create”或带有创建标签） browser_click: element="创建按钮", ref= # 4.现在编辑器应该打开了，可以继续上传封面图等操作 **注意** : 不要使用 `browser_wait_for text="添加标题"` 来只有等待页面加载，因为这个文本在点击创建后才出现，会导致超时。如果需要登录，则提示用户手动登录。 ## 步骤 3：上传封面图片 1. 点击“添加照片或视频”按钮 2. 将 browser_file_upload 与封面图像路径一起使用（来自 JSON 输出） 3. 验证上传的图片 ## 第四步：填写标题 * 查找带有“添加标题”占位符的文本框 * 使用 browser_type 输入标题（来自 JSON 输出） ## 步骤 5：粘贴文本内容（Python 剪贴板）使用 Python 将 HTML 复制到系统剪贴板，然后粘贴： # 将 HTML 复制到剪贴板 python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py html --file /tmp/article_html.html 然后在浏览器中： browser_click编辑器文本框 browser_press_key: 元+v 这会保留所有富文本格式（H2、粗体、链接、列表）。 ## 步骤 6：插入内容图像（块索引定位） **关键改进** : 使用 `block_index` 精确定位，而不依赖文字匹配。 ### 定位原理粘贴 HTML 后，编辑器中的内容结构为一系列块元素（段落、标题、引用等）。每张图片的 `block_index` 表示它应该插入在第 N 个块元素之后。 ### 操作步骤 1. **获取所有子元素** : 使用 browser_snapshot 获取编辑器内容，找到 textbox 下的所有子元素 2. **按索引定位** : 根据 `block_index` 点击对应的块元素 3. **粘贴图片** : 复制图片到剪贴板后粘贴对于每个内容图像（来自“content_images”数组）： # 1. 将图像复制到剪贴板（带压缩） python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py image /path/to/img.jpg --quality 85 # 2. 单击 block_index 处的块元素 # 示例：如果 block_index=5，则单击第 6 个块元素（0 索引） browser_click 在编辑器中位于 block_index 位置的元素 # 3. 粘贴图像 browser_press_key: 元+v # 4.等待上传（使用时间较短，完成后立即返回） browser_wait_for textGone="正在上传媒体" time=2 ### 逆向插入 **注意** : 每插入一张图片后，后续图片的实际位置会偏移。建议按`block_index` **从大到小**的顺序插入图片。如果有3张图片，block_index分别为5, 12, 27： 1.先插入block_index=27的图片 2.重新插入block_index=12的图片 3.最后插入block_index=5的图片 ## 步骤 6.5：插入分隔线（通过菜单） **重要** : Markdown 中的 `---` 分割线不能通过 HTML `

` 标签粘贴（X Articles 会忽略它）。必须通过 X Articles 的 Insert 菜单插入。 ### 为什么需要特殊处理 X Articles 有自己的原生分割线元素，只能通过 Insert > Divider 菜单插入。 HTML `

` 标签会被完全忽略。 ### 操作步骤 For each divider (from `dividers` array), in **reverse order of block_index** : # 1. Click the block element at block_index position browser_click on the element at position block_index in the editor # 2. Open Insert menu browser_click on "Insert" button (Add Media button) # 3. Click Divider menu item browser_click on "Divider" menuitem # Divider is inserted at cursor position ### 反向插入和图片一样，按 `block_index` **从大到小** 的顺序插入分割线，避免位置偏移问题。 ### 与图片的插入顺序建议先插入所有图片，再插入所有分割线。两者都按 block_index 从大到小的顺序： 1. 插入所有图片（从最大 block_index 开始） 2. 插入所有分割线（从最大 block_index 开始） ## Step 7: Save Draft 1. Verify content pasted (check word count indicator) 2. Draft auto-saves, or click Save button if needed 3. Click "预览" to verify formatting 4. Report: "Draft saved. Review and publish manually." ## Critical Rules 1. **NEVER publish** \- Only save draft 2. **Pre-process first** \- Convert tables/mermaid/deep headers before parsing 3. **First image = cover** \- Upload first image as cover image 4. **Rich text conversion** \- Always convert Markdown to HTML before pasting 5. **Use clipboard API** \- Paste via clipboard for proper formatting 6. **Block index positioning** \- Use block_index for precise image/divider placement 7. **Reverse order insertion** \- Insert images and dividers from highest to lowest block_index 8. **H1 title handling** \- H1 is used as title only, not included in body 9. **Dividers via menu** \- Markdown `---` must be inserted via Insert > Divider menu (HTML `

` is ignored) ## Supported Formatting (After Pre-Processing) Element | Support | Notes ---|---|--- H2 (`##`) | Native | Section headers Bold (`**`) | Native | Strong emphasis Italic (`*`) | Native | Emphasis Links (`[](url)`) | Native | Hyperlinks Ordered lists | Native | 1\. 2. 3. Unordered lists | Native | \- bullets Blockquotes (`>`) | Native | Quoted text Code blocks | Converted | → Blockquotes Tables | Converted | → PNG images Mermaid | Converted | → PNG images H3+ headers | Converted | → H2 or bold Dividers (`---`) | Menu insert | → Insert > Divider ## Example Flow User: "Publish /path/to/article.md to X" # Step 0: Analyze content # Found: 1 table, 1 mermaid diagram, 2 H3 headers # Step 0.1: Convert table to image node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table-1.md -o /tmp/table-1.png # Step 0.2: Convert mermaid to image node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/mermaid-1.mmd -o /tmp/mermaid-1.png # Step 0.3: Create modified markdown with image refs and flattened headers # Save to /tmp/article_modified.md # Step 1: Parse modified markdown python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /tmp/article_modified.md > /tmp/article.json python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /tmp/article_modified.md --html-only > /tmp/article_html.html 2. Navigate to 3. Click create, upload cover image (browser_file_upload for cover only) 4. Fill title (from JSON: `title`) 5. Copy & paste HTML: python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py html --file /tmp/article_html.html Then: browser_press_key Meta+v 6. For each content image (including converted table/mermaid PNGs), **in reverse order of block_index** : python copy_to_clipboard.py image /path/to/img.jpg --quality 85 * Click block element at `block_index` position * browser_press_key Meta+v * Wait until upload complete 7. Verify in preview 8. "Draft saved. Please review and publish manually." ## Best Practices ### 为什么用 block_index 而非文字匹配？ 1. **精确定位** : 不依赖文字内容，即使多处文字相似也能正确定位 2. **可靠性** : 索引是确定性的，不会因为文字相似而混淆 3. **调试方便** : `after_text` 仍保留用于人工核验 ### 为什么用 Python 而非浏览器内 JavaScript？ 1. **本地处理更可靠** : Python 直接操作系统剪贴板，不受浏览器沙盒限制 2. **图片压缩** : 上传前压缩图片 (--quality 85)，减少上传时间 3. **代码复用** : 脚本固定不变，无需每次重新编写转换逻辑 4. **调试方便** : 脚本可单独测试，问题易定位 ### 等待策略 **关键理解** : `browser_wait_for` 的 `textGone` 参数会在文字消失时**立即返回** ，`time` 只是最大等待时间，不是固定等待时间。 # 正确用法：短 time 值，条件满足立即返回 browser_wait_for textGone="正在上传媒体" time=2 # 错误用法：固定长时间等待 browser_wait_for time=5 # 无条件等待5秒，浪费时间 ### 封面图 vs 内容图 * **封面图** : 使用 browser_file_upload（因为有专门的上传按钮） * **内容图** : 使用 Python 剪贴板 + 粘贴（更高效） ## Troubleshooting ### Table not rendering correctly * Ensure Pillow is installed: `pip install pillow` * Check table markdown syntax is valid ### Mermaid conversion fails * Check that diagramless.xyz is reachable * Check mermaid syntax is valid * Try with explicit type: `--type mermaid` ### Deep headers still showing * Manually flatten `###` → `##` or `**bold**` * Re-run pre-processing ### Image upload timeout * Compress images with `--quality 70` * Use shorter `browser_wait_for time=2`

发布X文章

包含技能