A Claude Code skill that automates publishing Markdown articles to X (Twitter) Articles, eliminating the tedious manual formatting and image upload process. With one command, it converts Markdown to rich HTML, uploads images with precise positioning, and saves a draft ready for review.
The Problem
Publishing to X Articles from Markdown is traditionally painful:
- Format Loss: Copy-paste destroys all Markdown formatting
- Manual Formatting: 15-20 minutes to set H2, bold, links manually
- Tedious Image Upload: 5+ clicks per image
- Position Errors: Difficult to remember where each image should go
The Solution
This skill automates the entire workflow:
Markdown File → Python Parsing → Structured Data → Playwright MCP → X Articles Editor → Draft Saved
Key Features
Rich Text Paste
Convert Markdown to HTML and paste via clipboard - all formatting preserved automatically
Block-Index Positioning (v1.1.0)
- Precise image placement using element indices, not fragile text matching
- Each image has a
block_indexindicating exactly which block element it follows - Deterministic and reliable positioning
Reverse Insertion
Insert images from highest to lowest index to avoid position shifts during insertion
Smart Wait Strategy
Conditions return immediately when met, eliminating wasted wait time
Safe by Design
Only saves as draft, never publishes automatically - maintain full editorial control
Requirements
| Requirement | Details |
|---|---|
| Claude Code | claude.ai/code |
| Playwright MCP | Browser automation via MCP |
| X Premium Plus | Required for Articles feature |
| Python 3.9+ | With Pillow and pyobjc-framework-Cocoa |
| macOS | Currently macOS only (PRs welcome for Windows/Linux) |
Installation
Method 1: Git Clone (Recommended)
git clone https://github.com/wshuyi/x-article-publisher-skill.git
cp -r x-article-publisher-skill/skills/x-article-publisher ~/.claude/skills/
Method 2: Plugin Marketplace
/plugin marketplace add wshuyi/x-article-publisher-skill
/plugin install x-article-publisher@wshuyi/x-article-publisher-skill
Usage
Natural Language
Publish /path/to/article.md to X
Help me post this article to X Articles: ~/Documents/my-post.md
Skill Command
/x-article-publisher /path/to/article.md
Workflow
The skill executes 7 automated steps:
-
Parse Markdown
- Extract title, cover image, content images with block_index
- Convert to HTML, count total blocks
-
Open X Articles editor
- Navigate to x.com/compose/articles
-
Upload cover image
- First image automatically becomes article cover
-
Fill title
- H1 used as title (not included in body)
-
Paste article content
- Rich text via clipboard
- All formatting preserved
-
Insert content images (reverse order)
- Sort by block_index descending
- Click block element at index → Paste image
- Wait for upload (returns immediately when done)
-
Save draft
- ✅ Review and publish manually
Supported Markdown
| Syntax | Result |
|---|---|
# H1 | Article title (extracted, not in body) |
## H2 | Section headers |
**bold** | Bold text |
*italic* | Italic text |
[text](url) | Hyperlinks |
> quote | Blockquotes |
- item | Unordered lists |
1. item | Ordered lists |
 | Images (first = cover) |
Performance
| Task | Manual | With This Skill | Improvement |
|---|---|---|---|
| Format conversion | 15-20 min | 0 (automatic) | 100% saved |
| Cover image | 1-2 min | 10 sec | 10x faster |
| 5 content images | 5-10 min | 1 min | 5-10x faster |
| Total | 20-30 min | 2-3 min | 10x faster |
Example
Input: article.md
# 5 AI Tools Worth Watching in 2024
AI tools exploded in 2024. Here are 5 worth your attention.
## 1. Claude: Best Conversational AI
*Claude* by Anthropic excels at long-context understanding.
> Claude's context window reaches 200K tokens.
> 
## 2. Midjourney: AI Art Leader
[Midjourney](https://midjourney.com) is most popular AI art tool.
Parsed Output
{
"title": "5 AI Tools Worth Watching in 2024",
"cover_image": "./images/cover.jpg",
"content_images": [
{"path": "./images/claude-demo.png", "block_index": 4},
{"path": "./images/midjourney.jpg", "block_index": 6}
],
"total_blocks": 7
}
Insertion Order
Images inserted in reverse: block_index=6 first, then block_index=4.
Result
- Cover:
cover.jpguploaded - Title: "5 AI Tools Worth Watching in 2024"
- Content: Rich text with H2, bold, quotes, links
- Images: Inserted at precise positions via block index
- Status: Draft saved (ready for manual review)
FAQ
Q: Why Premium Plus? A: X Articles is exclusive to Premium Plus subscribers.
Q: Windows/Linux support? A: Currently macOS only. PRs welcome for cross-platform clipboard support.
Q: Image upload failed? A: Check: valid path, supported format (jpg/png/gif/webp), stable network.
Q: Can I publish to multiple accounts? A: Not automatically. Switch accounts in browser manually before running.
Q: Why insert images in reverse order? A: Each inserted image shifts subsequent block indices. Inserting from highest to lowest ensures earlier indices remain valid.
Q: What if text matching was used before?
A: v1.1 replaces text matching with block_index. The after_text field is kept for debugging but not used for positioning.
Q: Why does wait return immediately sometimes?
A: browser_wait_for textGone="..." returns as soon as the text disappears. The time parameter is just a maximum, not a fixed delay.
Recent Updates
v1.1.0 (December 2025)
- Block-index positioning: Replace text matching with precise element indices
- Reverse insertion order: Prevent index shifts when inserting multiple images
- Optimized wait strategy: Return immediately when upload completes
- H1 title handling: H1 extracted as title, not included in body HTML
Documentation
- Detailed Usage Guide — Complete documentation with examples
Technical Details
The skill uses:
- Python: Markdown parsing and HTML conversion
- Playwright MCP: Browser automation for X Articles editor
- Clipboard API: Rich text transfer
- Block-index system: Deterministic image positioning
Contributing
- Issues: Report bugs or request features
- PRs: Welcome! Especially for Windows/Linux support
License
MIT License — see LICENSE