/publish-x-article

name: publish-x-article
description: Publish Markdown articles to X (Twitter) Articles editor with proper formatting. Use when user wants to publish a Markdown file/URL to X Articles, or mentions "publish to X", "post article to Twitter", "X article", or wants help with X Premium article publishing. Handles cover image upload, converts Markdown to rich text, and automatically converts unsupported elements (tables, mermaid diagrams, deep headers) to images.

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](https://github.com/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 <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