x-article-publisher

X Article Publisher

Publish Markdown content to X (Twitter) Articles editor, preserving formatting with rich text conversion.

Prerequisites

• X Premium Plus subscription
• Python 3.9+ with dependencies: pip install Pillow pyobjc-framework-Cocoa patchright

🎉 First-time use: authenticate once, say goodbye to repeated logins

X Article Publisher now supports persistent authentication, so there is no need to manually log in every time!

🔧 Initialize authentication (only once)

Before first use, run the authentication setup:

cd ~/.claude/skills/x-article-publisher/scripts
python auth_manager.py setup

Process:

1. ✅ The browser window automatically opens the X login page
2. 🔐 Manually log in to your X account (Premium+ subscription required)
3. ✅ Complete 2FA verification (if enabled)
4. 🏠 Automatically redirect to the Home timeline after successful login
5. 💾 Authentication state is automatically saved (valid for 7 days)

📋 Authentication management commands

# 检查认证状态
python auth_manager.py status

# 验证认证是否有效
python auth_manager.py validate

# 清除认证数据（需重新登录）
python auth_manager.py clear

# 重新认证（清除 + 设置）
python auth_manager.py reauth

🚀 Automated workflow

After authentication setup is complete, the skill automatically performs the following during execution:

1. ✅ Check authentication status
2. 🔓 If authenticated, directly use the saved browser state (no login required)
3. ⚠️ If not authenticated, prompt to run auth_manager.py setup

Note: Authentication data is stored in ~/.claude/skills/x-article-publisher/data/browser_state/, which has been excluded via .gitignore and will not be committed to Git.

---

Scripts

Located in ~/.claude/skills/x-article-publisher/scripts/:

publish_article.py (main script - one-click publishing)

Recommended - automatically completes all publishing steps:

# 基本用法（默认显示浏览器）
python publish_article.py --file article.md

# 隐藏浏览器（后台运行）
python publish_article.py --file article.md --headless

# 自定义标题
python publish_article.py --file article.md --title "自定义标题"

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

Workflow (simplified version)

Prerequisite: Authentication setup has been completed (python auth_manager.py setup）

🚀 One-click publishing (recommended)

Run publish_article.py directly to automatically complete all steps:

cd ~/.claude/skills/x-article-publisher/scripts
python publish_article.py --file /path/to/article.md

The script will automatically:

1. ✅ Check authentication status
2. 📄 Parse the Markdown file
3. 🌐 Launch the authenticated browser
4. 📍 Navigate to the X Articles editor
5. 🔘 Click the create button
6. 🖼️ Upload the cover image (if any)
7. 📝 Fill in the title
8. 📋 Paste the HTML content
9. ✅ Save the draft (will not publish automatically）

Manual workflow (advanced users)

For finer control, execute in steps:

1. Parse Markdown: python parse_markdown.py article.md
2. Manually operate the browser to publish

---

🧠 Intelligent enhancement features

Intelligent title generation

When the article has no H1 title,parse_markdown.py will return needs_title_generation: true。

Claude should automatically:

1. Read the article content and understand the core ideas
2. Generate a title that attracts clicks (15-25 characters is ideal)
3. Use the --title "生成的标题" parameter to publish

Characteristics of a good title:

• Include numbers or specific details ("3 methods", "90% of people don't know")
• Stimulate curiosity ("Why...", "How to...", "The truth about...")
• Be directly relevant to readers
• Avoid clickbait, but be attractive

Example:

# 解析文章
python parse_markdown.py article.md

# 如果 needs_title_generation: true，Claude 生成标题后：
python publish_article.py --file article.md --title "AI时代，普通人的3个生存法则"

Intelligent cover image generation

When the article has no cover image,parse_markdown.py will return needs_cover_generation: true。

Claude should automatically:

1. Read the article and extract the core concepts (1-3 keywords)
2. Call gemini-image-generator or jimeng-image-generator skill generates cover image
3. Cover image style suggestions:
   • Simple and elegant, avoid complex details
   • Can be a visualization of abstract concepts
   • Or a text poster with core keywords
4. Insert the generated image path at the beginning of the article as the cover

Cover image generation prompt template:

为一篇关于「{文章主题}」的文章生成封面图。
风格：简洁、现代、科技感
元素：{1-3个核心视觉元素}
文字：可选，如果加文字只放{1-3个关键词}
尺寸：16:9 横版

Workflow example:

# 1. 解析文章
python parse_markdown.py article.md
# 输出: needs_cover_generation: true

# 2. Claude 调用生图 skill 生成封面（假设保存到 /tmp/cover.png）

# 3. 将封面图插入文章开头，或手动上传

Note: Cover image upload currently requires manual operation in the browser; the script will open the editor and wait for user action.

---

Technical details

parse_markdown.py output format

{
  "title": "Article Title",
  "title_source": "h1",           // "h1", "h2", "first_line", or "none"
  "needs_title_generation": false, // true if no H1 title
  "cover_image": "/path/to/first-image.jpg",
  "needs_cover_generation": false, // true if no cover image
  "content_images": [
    {"path": "/path/to/img2.jpg", "block_index": 5}
  ],
  "html": "<p>Content...</p><h2>Section</h2>...",
  "total_blocks": 45
}

Field descriptions:

• title_source: Title source
  • h1: From H1 heading (most ideal)
  • h2: From the first H2 heading
  • first_line: From the first line of text
  • none: Unable to extract title
• needs_title_generation: Whether Claude needs to generate a better title
• needs_cover_generation: Whether Claude needs to generate a cover image

Critical Rules

1. NEVER auto-publish - Only save as draft
2. NO automatic cover images - User adds cover manually, never insert first image as cover
3. Clean placeholders - Remove all remaining @@@IMG_X@@@ markers after image insertion
4. H1 title handling - H1 is used as title only, not included in body

Supported Formatting

• H2 headers (## )
• Blockquotes (> )
• Code blocks (converted to blockquotes)
• Bold text (**)
• Hyperlinks (text)
• Ordered/Unordered lists
• Paragraphs

Example

User: "Publish /path/to/article.md to X"

cd ~/.claude/skills/x-article-publisher/scripts
python publish_article.py --file /path/to/article.md

Output:

📄 解析文件：/path/to/article.md
  📝 标题：文章标题
  🖼️  封面图：/path/to/cover.jpg
  📷 内容图：2 张

🌐 启动浏览器...
  📍 导航到 X Articles...
  🔘 点击 create 按钮...
  📝 填写标题...
  📋 粘贴内容...

✅ 草稿已创建！
  💡 请在浏览器中检查并手动发布
  🖥️  浏览器保持打开，请检查草稿并手动发布
  ⏎  完成后按回车键关闭浏览器...

Technical experience reference: For browser automation debugging techniques, see skill-development-guide