X Article Publisher Skill: Automate Markdown to X Articles
X Article Publisher Skill – Turn Markdown into X Articles in Seconds
If you write your blog posts in Markdown, you’ve probably tried copying the raw text into X (formerly Twitter) Articles and struggled with formatting loss, manual image uploads, and unpredictable placement. The X Article Publisher Skill provides a single‑click solution that automates the entire workflow:
- Parses your Markdown to extract the title, cover image, and all embedded images.
- Converts the Markdown into clean HTML while preserving headings, links, tables, and Mermaid diagrams.
- Uses Playwright (via the Claude Code framework) to open the X Articles editor.
- Pastes the rich‑text content.
- Inserts images at the exact block index specified by the Markdown, preventing position drift.
- Saves the article as a draft—no accidental publication.
The result is a perfectly formatted draft ready for review, with all images in place – all in < 3 minutes.
Why You Need This Tool
Content creators who love Markdown face three main pain points when posting to X Articles:
- Format Loss – Pasting plain Markdown discards headers, lists, and styling.
- Time‑Consuming Image Uploads – Each image requires navigating media menus.
- Unreliable Image Placement – Manual dragging or text‑based positioning often misplaces content.
The skill addresses each issue: - Rich‑Text Paste via clipboard ensures all Markdown semantics survive the transition. - Automatic Image Uploads with smart wait detection upload quickly without manual clicks. - Block‑Index Positioning guarantees images appear where you expect, even in complex documents.
Efficiency Boost
A side‑by‑side comparison shows typical savings:
| Task | Manual | With Skill |
|---|---|---|
| Format conversion | 15‑20 min | 0 min |
| Cover image upload | 1‑2 min | < 10 sec |
| Multiple content images | 5‑10 min | 1 min |
| Total | 20‑30 min | 2‑3 min |
That’s at least a 10‑fold increase in productivity.
Getting Started
Prerequisites
| Requirement | Notes |
|---|---|
| Claude Code | Install at https://claude.ai/code |
| Playwright MCP | Browser automation driver |
| X Premium Plus | Articles feature is exclusive to Premium Plus |
| Python 3.9+ | For the helper scripts |
| OS | macOS or Windows (Linux support is in progress) |
| Clip Utilities | pip install Pillow pywin32 clip-util for Windows or pip install Pillow pyobjc-framework-Cocoa for macOS |
| Mermaid CLI | Optional, for diagram conversion (npm install -g @mermaid-js/mermaid-cli) |
Installation
# Method 1: Clone and copy to Claude skills directory
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: Install via the Claude plugin marketplace
/plugin marketplace add wshuyi/x-article-publisher-skill
/plugin install x-article-publisher@wshuyi/x-article-publisher-skill
Usage
The skill can be invoked with natural language or a direct command.
- Natural Language (via the Claude chatbot):
Help me post this article to X Articles: ~/Documents/my-post.md - Direct Skill Call (from a terminal):
/x-article-publisher /path/to/article.md
The workflow is:
1. Parse your Markdown and extract metadata.
2. Open the X Articles editor at x.com/compose/articles.
3. Upload the cover image and paste the body content.
4. Insert content images using the block‑index strategy.
5. Save draft for later review.
Feature Highlights
| Feature | Version | Benefit |
|---|---|---|
| Divider Support | v1.2.0 | Recognizes --- and inserts an X Articles divider via the Insert menu. |
| Table‑to‑Image | v1.2.0 | Converts Markdown tables to PNGs for perfect visual fidelity. |
| Mermaid Support | v1.2.0 | Uses mmdc to render diagrams as images. |
| Block‑Index Positioning | v1.1.0 | Precisely targets image placement without fragile text matching. |
| Reverse Insertion Order | v1.1.0 | Avoids index shift issues when inserting multiple images. |
| Automatic Wait Strategy | v1.1.0 | Returns immediately once uploads finish, saving idle time. |
| Safe Publishing | Every Release | Draft‑only mode prevents accidental public posts. |
Contribution Guide
The project is actively maintained and welcomes pull requests. Key areas for contributors:
- Add Linux support (clipboard and Playwright configuration).
- Expand image format support beyond JPG/PNG/GIF/WebP.
- Improve error handling, e.g., for missing image paths.
- Enhance documentation with more use‑cases and advanced examples.
You can submit issues or PRs via the GitHub repository.
Conclusion
The X Article Publisher Skill is a game‑changer for anyone who writes in Markdown and publishes to X Articles. With automatic formatting, precise image placement, and a quick draft workflow, it removes the drag‑and‑drop frustration that plagues manual publishing. Whether you’re a solo blogger, a copywriter, or a digital marketing team, this tool cuts your article‑production cycle down by an order of magnitude while keeping your edits safe and ready for final review.
Try it out today, fork it, and contribute your improvements—open source thrives on collaboration!