Publish X Article

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

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 <markdown_file> [--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

When a table is detected:

# 1. Extract table to temp file
cat > /tmp/table.md << 'TABLE_EOF'
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
TABLE_EOF

# 2. Convert to image via diagramless.xyz API
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table-001.png

# 3. Replace table in markdown with image reference
# ![Table description](/tmp/table-001.png)

2. Mermaid Diagrams → PNG

When a mermaid block is detected:

# 1. Extract mermaid to temp file
cat > /tmp/diagram.mmd << 'MERMAID_EOF'
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
MERMAID_EOF

# 2. Convert to image via diagramless.xyz API
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram-001.png

# 3. Replace mermaid block in markdown with image reference
# ![Diagram description](/tmp/diagram-001.png)

3. Deep Headers (H3+) → Simplified Structure

Goal: Preserve the article's logical structure and readability while working within X Premium's H2-only limitation.

Guidelines for the AI:

When you encounter H3, H4, or deeper headers in a Premium user's article, think about what the author intended:

• If the header introduces a distinct subtopic under a section, convert it to bold text as a paragraph opener. This maintains visual hierarchy without breaking X's formatting.

• If the header is a major section that happens to be H3, consider promoting it to H2 — but only if this doesn't create a flat, meaningless structure. The article should still flow logically.

• If there's a deep hierarchy (H2 → H3 → H4), flatten thoughtfully:

  • Keep H2 as H2
  • Convert H3 to bold paragraph
  • Convert H4 to italic or just merge into the paragraph naturally

• Preserve meaning over structure. A header like ### Why This Matters might become a bold lead-in: **Why does this matter?** followed by the content. Use your judgment.

• Read the content. If an H3 header is just "Example" or "Note", it might work better as a blockquote or inline emphasis rather than a standalone bold line.

The goal is not mechanical conversion — it's creating an article that reads well on X while honoring the author's intent.

Pre-Processing Workflow

Before publishing, read through the article and prepare it for X:

1. Understand the article's structure — Read it first. What are the main sections? How does the author use headers to organize ideas?

2. Handle tables and mermaid diagrams — These need to become images. Extract each one, convert to PNG, and note where they should be inserted.

3. Adapt headers for the subscription tier:

   • For Premium+ users: Keep headers as-is (H3+ supported)
   • For Premium users: Thoughtfully restructure H3+ headers while preserving the article's flow and intent (see guidelines above)

4. Create the modified markdown — Save your adapted version to a temp file, ready for parsing.

The goal is an article that reads naturally on X, not a mechanically transformed document.

Main Workflow

Strategy: "先文后图后分割线" (Text First, Images Second, Dividers Last)

For articles with images and dividers, paste ALL text content first, then insert images and dividers at correct positions using block index.

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