Back to search
x-article-publisher-skill
SkillWorks with Claude CodeGitHub
Claude Code skill for publishing Markdown articles to X (Twitter) Articles
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/wshuyi-x-article-publisher-skill)HTML
<a href="/listings/wshuyi-x-article-publisher-skill"><img src="/api/listings/wshuyi-x-article-publisher-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 346 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # X Article Publisher Skill
- [English](README.md) | [中文](README_CN.md)
- > Publish Markdown articles to X (Twitter) Articles with one command. Say goodbye to tedious rich text editing.
- **v1.2.0** — Now with divider support, table-to-image, Mermaid support, and cross-platform clipboard
- ---
- ## The Problem
- If you're used to writing in Markdown, publishing to X Articles is a **painful process**:
- | Pain Point | Description |
- |------------|-------------|
- | **Format Loss** | Copy from Markdown editor → Paste to X → All formatting gone |
- | **Manual Formatting** | Set each H2, bold, link manually — 15-20 min per article |
- | **Tedious Image Upload** | 5 clicks per image: Add media → Media → Add photo → Select → Wait |
- | **Position Errors** | Hard to remember where each image should go |
- ### Time Comparison
- | Task | Manual | With This Skill |
- |------|--------|-----------------|
- | Format conversion | 15-20 min | 0 (automatic) |
- | Cover image | 1-2 min | 10 sec |
- | 5 content images | 5-10 min | 1 min |
- | **Total** | **20-30 min** | **2-3 min** |
- **10x efficiency improvement**
- ---
- ## The Solution
- This skill automates the entire publishing workflow:
- ```
- Markdown File
- ↓ Python parsing
- Structured Data (title, images with block_index, HTML)
- ↓ Playwright MCP
- X Articles Editor (browser automation)
- ↓
- Draft Saved (never auto-publishes)
- ```
- ### Key Features
- - **Rich Text Paste**: Convert Markdown to HTML, paste via clipboard — all formatting preserved
- - **Block-Index Positioning** (v1.1): Precise image placement using element indices, not text matching
- - **Reverse Insertion**: Insert images from highest to lowest index to avoid position shifts
- - **Smart Wait Strategy**: Conditions return immediately when met, no wasted wait time
- - **Safe by Design**: Only saves as draft, never publishes automatically
- ---
- ## What's New in v1.1.0
- | Feature | Before | After |
- |---------|--------|-------|
- | Image positioning | Text matching (fragile) | Block index (precise) |
- | Insertion order | Sequential | Reverse (high→low) |
- | Wait behavior | Fixed delay | Immediate return on condition |
- ### Why Block-Index?
- Previously, images were positioned by matching surrounding text — this failed when:
- - Multiple paragraphs had similar content
- - Text was too short to be unique
- Now, each image has a `block_index` indicating exactly which block element it follows. This is deterministic and reliable.
- ---
- ## Requirements
- | Requirement | Details |
- |-------------|---------|
- | Claude Code | [claude.ai/code](https://claude.ai/code) |
- | Playwright MCP | Browser automation |
- | X Premium Plus | Required for Articles feature |
- | Python 3.9+ | With dependencies below |
- | OS | macOS or Windows |
- ```bash
- # macOS
- pip install Pillow pyobjc-framework-Cocoa
- # Windows
- pip install Pillow pywin32 clip-util
- # For Mermaid diagrams (optional)
- npm install -g @mermaid-js/mermaid-cli
- ```
- ---
- ## Installation
- ### Method 1: Git Clone (Recommended)
- ```bash
- 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 Steps
- ```
- [1/7] Parse Markdown...
- → Extract title, cover image, content images with block_index
- → Convert to HTML, count total blocks
- [2/7] Open X Articles editor...
- → Navigate to x.com/compose/articles
- [3/7] Upload cover image...
- → First image becomes cover
- [4/7] Fill title...
- → H1 used as title (not included in body)
- [5/7] Paste article content...
- → Rich text via clipboard
- → All formatting preserved
- [6/7] Insert content images (reverse order)...
- → Sort by block_index descending
- → Click block element at index → Paste image
- → Wait for upload (returns immediately when done)
- [7/7] Save draft...
- → ✅ Review and publish manually
- ```
- ---
- ## Supported Markdown
- | Syntax | Result | Notes |
- |--------|--------|-------|
- | `# H1` | Article title | Extracted, not in body |
- | `## H2` | Section headers | Native support |
- | `**bold**` | **Bold text** | Native support |
- | `*italic*` | *Italic text* | Native support |
- | `[text](url)` | Hyperlinks | Native support |
- | `> quote` | Blockquotes | Native support |
- | `- item` | Unordered lists | Native support |
- | `1. item` | Ordered lists | Native support |
- | `` | Images | First = cover |
- | `---` | Dividers | Via Insert menu (v1.2) |
- | Tables | PNG images | Via table_to_image.py (v1.2) |
- | Mermaid | PNG images | Via mmdc CLI (v1.2) |
- ---
- ## Example
- ### Input: `article.md`
- ```markdown
- # 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 the most popular AI art tool.
- 
- ```
- ### Parsed Output (JSON)
- ```json
- {
- "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.jpg` uploaded
- - 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)
- ---
- ## Project Structure
- ```
- x-article-publisher-skill/
- ├── .claude-plugin/
- │ └── plugin.json # Plugin config
- ├── skills/
- │ └── x-article-publisher/
- │ ├── SKILL.md # Skill instructions
- │ └── scripts/
- │ ├── parse_markdown.py # Extracts block_index + dividers
- │ ├── copy_to_clipboard.py # Cross-platform clipboard
- │ └── table_to_image.py # Markdown table → PNG (v1.2)
- ├── docs/
- │ └── GUIDE.md # Detailed guide
- ├── README.md # This file
- ├── README_CN.md # Chinese version
- └── LICENSE
- ```
- ---
- ## FAQ
- **Q: Why Premium Plus?**
- A: X Articles is exclusive to Premium Plus subscribers.
- **Q: Windows/Linux support?**
- A: Windows is now supported (v1.2). Linux support is still in progress — PRs welcome!
- **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.
- ---
- ## Documentation
- - [Detailed Usage Guide](docs/GUIDE.md) — Complete documentation with examples
- ---
- ## Changelog
- ### v1.2.0 (2025-01)
- - **Divider support**: Detect `---` in Markdown, insert via X Articles menu
- - **Table to image**: New `table_to_image.py` script converts Markdown tables to PNG
- - **Mermaid support**: Documentation for using `mmdc` to convert diagrams
- - **YAML frontmatter**: Automatically skip frontmatter in Markdown files
- - **Windows support**: Cross-platform clipboard operations (pywin32 + clip-util)
- ### v1.1.0 (2025-12)
- - **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
- ### v1.0.0 (2025-12)
- - Initial release
- - Rich text paste via clipboard
- - Cover + content image support
- - Draft-only publishing
- ---
- ## License
- MIT License - see [LICENSE](LICENSE)
- ## Author
- [wshuyi](https://github.com/wshuyi)
- ---
- ## Acknowledgments
- v1.2.0 features were inspired by and adapted from:
- - **[sugarforever/01coder-agent-skills](https://github.com/sugarforever/01coder-agent-skills)** — The `publish-x-article` skill contributed ideas for:
- - Divider detection and menu-based insertion
- - Table-to-image conversion script
- - Mermaid diagram support documentation
- - YAML frontmatter handling
- - Windows clipboard implementation
- Thank you to the community for building upon and improving this skill!
- ---
- ## Contributing
- - **Issues**: Report bugs or request features
- - **PRs**: Welcome! Especially for Windows/Linux support
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.