Skip to content
Back to search

x-article-publisher-skill

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wshuyi-x-article-publisher-skill/badge.svg)](/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)

  1. # X Article Publisher Skill
  2. [English](README.md) | [中文](README_CN.md)
  3. > Publish Markdown articles to X (Twitter) Articles with one command. Say goodbye to tedious rich text editing.
  4. **v1.2.0** — Now with divider support, table-to-image, Mermaid support, and cross-platform clipboard
  5. ---
  6. ## The Problem
  7. If you're used to writing in Markdown, publishing to X Articles is a **painful process**:
  8. | Pain Point | Description |
  9. |------------|-------------|
  10. | **Format Loss** | Copy from Markdown editor → Paste to X → All formatting gone |
  11. | **Manual Formatting** | Set each H2, bold, link manually — 15-20 min per article |
  12. | **Tedious Image Upload** | 5 clicks per image: Add media → Media → Add photo → Select → Wait |
  13. | **Position Errors** | Hard to remember where each image should go |
  14. ### Time Comparison
  15. | Task | Manual | With This Skill |
  16. |------|--------|-----------------|
  17. | Format conversion | 15-20 min | 0 (automatic) |
  18. | Cover image | 1-2 min | 10 sec |
  19. | 5 content images | 5-10 min | 1 min |
  20. | **Total** | **20-30 min** | **2-3 min** |
  21. **10x efficiency improvement**
  22. ---
  23. ## The Solution
  24. This skill automates the entire publishing workflow:
  25. ```
  26. Markdown File
  27. ↓ Python parsing
  28. Structured Data (title, images with block_index, HTML)
  29. ↓ Playwright MCP
  30. X Articles Editor (browser automation)
  31. ↓
  32. Draft Saved (never auto-publishes)
  33. ```
  34. ### Key Features
  35. - **Rich Text Paste**: Convert Markdown to HTML, paste via clipboard — all formatting preserved
  36. - **Block-Index Positioning** (v1.1): Precise image placement using element indices, not text matching
  37. - **Reverse Insertion**: Insert images from highest to lowest index to avoid position shifts
  38. - **Smart Wait Strategy**: Conditions return immediately when met, no wasted wait time
  39. - **Safe by Design**: Only saves as draft, never publishes automatically
  40. ---
  41. ## What's New in v1.1.0
  42. | Feature | Before | After |
  43. |---------|--------|-------|
  44. | Image positioning | Text matching (fragile) | Block index (precise) |
  45. | Insertion order | Sequential | Reverse (high→low) |
  46. | Wait behavior | Fixed delay | Immediate return on condition |
  47. ### Why Block-Index?
  48. Previously, images were positioned by matching surrounding text — this failed when:
  49. - Multiple paragraphs had similar content
  50. - Text was too short to be unique
  51. Now, each image has a `block_index` indicating exactly which block element it follows. This is deterministic and reliable.
  52. ---
  53. ## Requirements
  54. | Requirement | Details |
  55. |-------------|---------|
  56. | Claude Code | [claude.ai/code](https://claude.ai/code) |
  57. | Playwright MCP | Browser automation |
  58. | X Premium Plus | Required for Articles feature |
  59. | Python 3.9+ | With dependencies below |
  60. | OS | macOS or Windows |
  61. ```bash
  62. # macOS
  63. pip install Pillow pyobjc-framework-Cocoa
  64. # Windows
  65. pip install Pillow pywin32 clip-util
  66. # For Mermaid diagrams (optional)
  67. npm install -g @mermaid-js/mermaid-cli
  68. ```
  69. ---
  70. ## Installation
  71. ### Method 1: Git Clone (Recommended)
  72. ```bash
  73. git clone https://github.com/wshuyi/x-article-publisher-skill.git
  74. cp -r x-article-publisher-skill/skills/x-article-publisher ~/.claude/skills/
  75. ```
  76. ### Method 2: Plugin Marketplace
  77. ```
  78. /plugin marketplace add wshuyi/x-article-publisher-skill
  79. /plugin install x-article-publisher@wshuyi/x-article-publisher-skill
  80. ```
  81. ---
  82. ## Usage
  83. ### Natural Language
  84. ```
  85. Publish /path/to/article.md to X
  86. ```
  87. ```
  88. Help me post this article to X Articles: ~/Documents/my-post.md
  89. ```
  90. ### Skill Command
  91. ```
  92. /x-article-publisher /path/to/article.md
  93. ```
  94. ---
  95. ## Workflow Steps
  96. ```
  97. [1/7] Parse Markdown...
  98. → Extract title, cover image, content images with block_index
  99. → Convert to HTML, count total blocks
  100. [2/7] Open X Articles editor...
  101. → Navigate to x.com/compose/articles
  102. [3/7] Upload cover image...
  103. → First image becomes cover
  104. [4/7] Fill title...
  105. → H1 used as title (not included in body)
  106. [5/7] Paste article content...
  107. → Rich text via clipboard
  108. → All formatting preserved
  109. [6/7] Insert content images (reverse order)...
  110. → Sort by block_index descending
  111. → Click block element at index → Paste image
  112. → Wait for upload (returns immediately when done)
  113. [7/7] Save draft...
  114. → ✅ Review and publish manually
  115. ```
  116. ---
  117. ## Supported Markdown
  118. | Syntax | Result | Notes |
  119. |--------|--------|-------|
  120. | `# H1` | Article title | Extracted, not in body |
  121. | `## H2` | Section headers | Native support |
  122. | `**bold**` | **Bold text** | Native support |
  123. | `*italic*` | *Italic text* | Native support |
  124. | `[text](url)` | Hyperlinks | Native support |
  125. | `> quote` | Blockquotes | Native support |
  126. | `- item` | Unordered lists | Native support |
  127. | `1. item` | Ordered lists | Native support |
  128. | `![](img.jpg)` | Images | First = cover |
  129. | `---` | Dividers | Via Insert menu (v1.2) |
  130. | Tables | PNG images | Via table_to_image.py (v1.2) |
  131. | Mermaid | PNG images | Via mmdc CLI (v1.2) |
  132. ---
  133. ## Example
  134. ### Input: `article.md`
  135. ```markdown
  136. # 5 AI Tools Worth Watching in 2024
  137. ![cover](./images/cover.jpg)
  138. AI tools exploded in 2024. Here are 5 worth your attention.
  139. ## 1. Claude: Best Conversational AI
  140. **Claude** by Anthropic excels at long-context understanding.
  141. > Claude's context window reaches 200K tokens.
  142. ![claude-demo](./images/claude-demo.png)
  143. ## 2. Midjourney: AI Art Leader
  144. [Midjourney](https://midjourney.com) is the most popular AI art tool.
  145. ![midjourney](./images/midjourney.jpg)
  146. ```
  147. ### Parsed Output (JSON)
  148. ```json
  149. {
  150. "title": "5 AI Tools Worth Watching in 2024",
  151. "cover_image": "./images/cover.jpg",
  152. "content_images": [
  153. {"path": "./images/claude-demo.png", "block_index": 4},
  154. {"path": "./images/midjourney.jpg", "block_index": 6}
  155. ],
  156. "total_blocks": 7
  157. }
  158. ```
  159. ### Insertion Order
  160. Images inserted in reverse: `block_index=6` first, then `block_index=4`.
  161. ### Result
  162. - Cover: `cover.jpg` uploaded
  163. - Title: "5 AI Tools Worth Watching in 2024"
  164. - Content: Rich text with H2, bold, quotes, links
  165. - Images: Inserted at precise positions via block index
  166. - Status: **Draft saved** (ready for manual review)
  167. ---
  168. ## Project Structure
  169. ```
  170. x-article-publisher-skill/
  171. ├── .claude-plugin/
  172. │ └── plugin.json # Plugin config
  173. ├── skills/
  174. │ └── x-article-publisher/
  175. │ ├── SKILL.md # Skill instructions
  176. │ └── scripts/
  177. │ ├── parse_markdown.py # Extracts block_index + dividers
  178. │ ├── copy_to_clipboard.py # Cross-platform clipboard
  179. │ └── table_to_image.py # Markdown table → PNG (v1.2)
  180. ├── docs/
  181. │ └── GUIDE.md # Detailed guide
  182. ├── README.md # This file
  183. ├── README_CN.md # Chinese version
  184. └── LICENSE
  185. ```
  186. ---
  187. ## FAQ
  188. **Q: Why Premium Plus?**
  189. A: X Articles is exclusive to Premium Plus subscribers.
  190. **Q: Windows/Linux support?**
  191. A: Windows is now supported (v1.2). Linux support is still in progress — PRs welcome!
  192. **Q: Image upload failed?**
  193. A: Check: valid path, supported format (jpg/png/gif/webp), stable network.
  194. **Q: Can I publish to multiple accounts?**
  195. A: Not automatically. Switch accounts in browser manually before running.
  196. **Q: Why insert images in reverse order?**
  197. A: Each inserted image shifts subsequent block indices. Inserting from highest to lowest ensures earlier indices remain valid.
  198. **Q: What if text matching was used before?**
  199. A: v1.1 replaces text matching with `block_index`. The `after_text` field is kept for debugging but not used for positioning.
  200. **Q: Why does wait return immediately sometimes?**
  201. A: `browser_wait_for textGone="..."` returns as soon as the text disappears. The `time` parameter is just a maximum, not a fixed delay.
  202. ---
  203. ## Documentation
  204. - [Detailed Usage Guide](docs/GUIDE.md) — Complete documentation with examples
  205. ---
  206. ## Changelog
  207. ### v1.2.0 (2025-01)
  208. - **Divider support**: Detect `---` in Markdown, insert via X Articles menu
  209. - **Table to image**: New `table_to_image.py` script converts Markdown tables to PNG
  210. - **Mermaid support**: Documentation for using `mmdc` to convert diagrams
  211. - **YAML frontmatter**: Automatically skip frontmatter in Markdown files
  212. - **Windows support**: Cross-platform clipboard operations (pywin32 + clip-util)
  213. ### v1.1.0 (2025-12)
  214. - **Block-index positioning**: Replace text matching with precise element indices
  215. - **Reverse insertion order**: Prevent index shifts when inserting multiple images
  216. - **Optimized wait strategy**: Return immediately when upload completes
  217. - **H1 title handling**: H1 extracted as title, not included in body HTML
  218. ### v1.0.0 (2025-12)
  219. - Initial release
  220. - Rich text paste via clipboard
  221. - Cover + content image support
  222. - Draft-only publishing
  223. ---
  224. ## License
  225. MIT License - see [LICENSE](LICENSE)
  226. ## Author
  227. [wshuyi](https://github.com/wshuyi)
  228. ---
  229. ## Acknowledgments
  230. v1.2.0 features were inspired by and adapted from:
  231. - **[sugarforever/01coder-agent-skills](https://github.com/sugarforever/01coder-agent-skills)** — The `publish-x-article` skill contributed ideas for:
  232. - Divider detection and menu-based insertion
  233. - Table-to-image conversion script
  234. - Mermaid diagram support documentation
  235. - YAML frontmatter handling
  236. - Windows clipboard implementation
  237. Thank you to the community for building upon and improving this skill!
  238. ---
  239. ## Contributing
  240. - **Issues**: Report bugs or request features
  241. - **PRs**: Welcome! Especially for Windows/Linux support

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.