X Article Publisher Skill

The project is organized into skills and scripts. The core logic for X Article publishing resides in the skills/x-article-publisher/ directory:

• SKILL.md: Contains the core instructions for the skill.
• scripts/parse_markdown.py: Handles Markdown parsing.
• scripts/copy_to_clipboard.py: Manages clipboard operations (currently macOS specific).

x-article-publisher-skill/
├── .claude-plugin/
│   └── plugin.json           # Plugin configuration
├── skills/
│   └── x-article-publisher/
│       ├── SKILL.md          # Skill core instructions
│       └── scripts/
│           ├── parse_markdown.py    # Markdown parsing
│           └── copy_to_clipboard.py # Clipboard operations
├── docs/
│   └── GUIDE.md              # This documentation
├── README.md
└── LICENSE

When using the Playwright MCP browser_wait_for tool, be aware that providing both a time and a condition (like textGone) causes a delay because the tool waits for the full time duration before checking the condition.

Best Practices:

• To wait for a condition to disappear: Use only textGone. Let Playwright poll automatically.

  browser_wait_for textGone="正在上传媒体"

• To wait for a fixed duration: Use only time.
• Avoid: Using textGone + time together, as this results in unnecessary idle time.

In v1.1.0, the skill uses a Block-Index strategy for precise image placement instead of unstable text matching.

Mechanism:

1. parse_markdown.py extracts a block_index for each image, representing the Nth block element after which the image should appear (0-indexed).
2. The skill uses a Reverse Insertion Strategy: It inserts images starting from the highest block_index down to the lowest. This ensures that inserting an image does not shift the indices of subsequent target locations.

Example Data Structure:

{
  "content_images": [
    {
      "path": "/path/to/img1.jpg",
      "block_index": 5,
      "after_text": "context text..."
    }
  ],
  "total_blocks": 12
}

{
  "content_images": [
    {
      "path": "/path/to/img1.jpg",
      "block_index": 5,
      "after_text": "上下文文字（仅用于调试）..."
    }
  ],
  "total_blocks": 12
}

You can trigger the publishing workflow using natural language or the specific skill command.

Natural Language

Ask Claude to publish a file directly:

• Publish /path/to/article.md to X
• Help me post this article to X Articles: ~/Documents/my-post.md

Skill Command

Use the explicit command for precision:

/x-article-publisher /path/to/article.md

Note: The skill only saves the article as a draft in the X Articles editor. It never publishes automatically, allowing you to review the content before going live.

To use this skill, ensure you have the following requirements met:

Core Requirements

• Playwright MCP: For browser automation.
• X (Twitter) Account: Must be logged in with a Premium Plus subscription.
• Python: Version 3.9 or higher.

OS-Specific Python Dependencies

Install the necessary Python packages based on your operating system:

macOS:

pip install Pillow pyobjc-framework-Cocoa

Windows:

pip install Pillow pywin32 clip-util

Optional: Mermaid Diagrams

If your Markdown contains Mermaid diagrams, install the Mermaid CLI globally:

npm install -g @mermaid-js/mermaid-cli

Before using the skill, ensure the following requirements are met:

1. X Premium Plus Subscription: You must have access to the X Articles editor at https://x.com/compose/articles.
2. Playwright MCP: The skill requires Playwright MCP for browser automation. Verify installation with:

   cat ~/.claude/settings.json | grep playwright

   If missing, ask Claude Code to 帮我安装 Playwright MCP.
3. Python Dependencies: Install the required Python packages:

   pip install Pillow pyobjc-framework-Cocoa

   Verify the installation with:

   python -c "from AppKit import NSPasteboard; print('OK')"

You can install the skill using two methods: Git Clone (recommended for manual management) or via the Plugin Marketplace.

Method 1: Git Clone

Clone the repository and copy the skill directory to your Claude skills folder:

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

Use the following commands within your environment:

/plugin marketplace add wshuyi/x-article-publisher-skill
/plugin install x-article-publisher@wshuyi/x-article-publisher-skill

Before using the skill, ensure you meet the following requirements:

Core Requirements

• Claude Code: Installed via claude.ai/code.
• Playwright MCP: Required for browser automation.
• X Premium Plus: Required to access the X Articles feature.
• Python 3.9+
• OS: macOS or Windows.

OS-Specific Python Dependencies

Install the necessary Python packages based on your operating system:

macOS:

pip install Pillow pyobjc-framework-Cocoa

Windows:

pip install Pillow pywin32 clip-util

Optional: Mermaid Diagram Support

To support Mermaid diagrams, install the Mermaid CLI globally via npm:

npm install -g @mermaid-js/mermaid-cli

Before using the skill, ensure you meet the following requirements:

• Claude Code: Installed and available.
• Playwright MCP: Required for browser automation.
• X Premium Plus: An active subscription is required to use the X Articles feature.
• Python 3.9+: Required for parsing and clipboard operations.
• Operating System: macOS or Windows (Linux support is in development).

Install OS-Specific Dependencies

macOS:

pip install Pillow pyobjc-framework-Cocoa

Windows:

pip install Pillow pywin32 clip-util

Optional (for Mermaid diagram support):

npm install -g @mermaid-js/mermaid-cli

pip install Pillow pyobjc-framework-Cocoa # macOS
pip install Pillow pywin32 clip-util # Windows