publish-x-article

X 記事を公開する

Markdown コンテンツを X（Twitter）の記事エディターに公開し、リッチテキスト変換によって書式を保持します。X Premium の制限によりサポートされない要素は、自動的に画像に変換します。

クレジット

このスキルは、wshuyi/x-article-publisher-skill に着想を得て、その内容を基にしています。基盤となる成果を提供してくださった原作者に感謝します。

対話形式のセットアップ：サブスクリプションの種類を確認する

重要：記事を処理する前に、まだ確認できていない場合は、ユーザーに X のサブスクリプションの種類を尋ねてください。

ユーザーへのプロンプト

Before publishing, I need to know your X subscription type to handle formatting correctly:

1. **X Premium** - Basic tier ($8/month)
2. **X Premium+** - Plus tier ($16/month)

Which subscription do you have? (Premium / Premium+)

中国語を使用するユーザーの場合：

在发布之前，我需要了解您的 X 订阅类型以正确处理格式：

1. **X Premium** - 基础版 ($8/月)
2. **X Premium+** - 高级版 ($16/月)

您使用的是哪个版本？(Premium / Premium+)

回答を記憶する

ユーザーが回答したら、そのセッション中はサブスクリプションの種類を記憶しておきます。ユーザーから変更したいという明確な希望がない限り、再度尋ねないでください。

X サブスクリプションの機能比較

機能	X Premium	X Premium+
H1 ヘッダー（#）	タイトルのみ	タイトルのみ
H2 ヘッダー（##）	対応	対応
H3 以上のヘッダー（### など）	非対応	対応
Markdown テーブル	非対応	対応
Mermaid 図	非対応	非対応（X はサポートしていません）
コードブロック	引用ブロック	引用ブロック
太字、斜体、リンク	対応	対応
リスト	対応	対応
引用ブロック	対応	対応
画像	対応	対応

サブスクリプションに応じて必要な事前処理

X Premium（ベーシック）：

• H3 以上のヘッダー → H2 または太字に変換
• テーブル → PNG 画像に変換
• Mermaid → PNG 画像に変換

X Premium+（プラス）：

• H3 以上のヘッダーはそのまま使用
• テーブルはそのまま使用（ネイティブ表示）
• Mermaid → PNG 画像に変換（引き続き非対応）

前提条件

• ブラウザー自動化用の Playwright MCP
• ユーザーが Premium サブスクリプションで X にログインしていること
• 依存関係を含む Python 3.9 以降：
  • macOS：pip install Pillow pyobjc-framework-Cocoa markdown
  • Windows：pip install Pillow pywin32 clip-util markdown
• diagram-to-image スキル（diagramless.xyz API 経由でテーブル／Mermaid を PNG に変換するため）

スクリプト

~/.claude/skills/publish-x-article/scripts/ にあります：

parse_markdown.py

Markdown を解析して構造化データを抽出します：

python parse_markdown.py <markdown_file> [--output json|html] [--html-only]

title、cover_image、content_images（配置位置を示す block_index 付き）、html、total_blocks を含む JSON を返します。

copy_to_clipboard.py

画像または HTML をシステムのクリップボードにコピーします：

# 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

diagram-to-image.mjs（diagram-to-image スキル由来）

diagramless.xyz API 経由で Mermaid 図と Markdown テーブルを PNG 画像に変換します：

node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table.png
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram.png --theme ocean

事前処理：サポートされない要素への対応

公開する前に、Markdown 内のサポートされない要素を確認し、画像に変換してください。

ステップ 0：コンテンツの制限を確認する

# Check the markdown file for unsupported elements
cat /path/to/article.md

以下を確認します：

1. 深い階層のヘッダー（H3 以上）：###、#### など
2. Markdown テーブル：テーブル構造を形成する | を含む行
3. Mermaid コードブロック： ```mermaid

サポートされない要素を画像に変換する

1. Markdown テーブル → PNG

テーブルが検出された場合：

# 1. Extract table to temp file
cat > /tmp/table.md << 'TABLE_EOF'
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
TABLE_EOF

# 2. Convert to image via diagramless.xyz API
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o /tmp/table-001.png

# 3. Replace table in markdown with image reference
# ![Table description](/tmp/table-001.png)

2. Mermaid 図 → PNG

Mermaid ブロックが検出された場合：

# 1. Extract mermaid to temp file
cat > /tmp/diagram.mmd << 'MERMAID_EOF'
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
MERMAID_EOF

# 2. Convert to image via diagramless.xyz API
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o /tmp/diagram-001.png

# 3. Replace mermaid block in markdown with image reference
# ![Diagram description](/tmp/diagram-001.png)

3. 深い階層の見出し（H3 以上）→ シンプルな構成

目標： X Premium の H2 のみという制限に対応しながら、記事の論理的な構成と読みやすさを保ちます。

AI 向けガイドライン：

Premium ユーザーの記事に H3、H4、またはそれより深い階層の見出しがある場合は、著者の意図を考慮してください。

• 見出しがセクション内の独立したサブトピックを示している場合は、段落の冒頭に置く太字のテキストに変換します。これにより、X の書式設定を損なうことなく、視覚的な階層を保てます。

• H3 であっても主要なセクションである場合は、H2 への昇格を検討します。ただし、構成が平坦で意味のないものにならない場合に限ります。記事の流れは論理的に保つ必要があります。

• 深い階層がある場合（H2 → H3 → H4）は、適切に整理します。

  • H2 は H2 のままにします
  • H3 は太字の段落に変換します
  • H4 は斜体にするか、段落に自然に統合します

• 構成よりも意味を優先します。 ### Why This Matters のような見出しは、太字の導入文 **なぜ重要なのでしょうか？** にして、その後に本文を続ける方法があります。適切に判断してください。

• 内容を読み取ります。 H3 の見出しが「例」や「注記」だけの場合は、独立した太字の行ではなく、引用やインラインの強調表現にしたほうが適切なことがあります。

機械的に変換することが目的ではありません。著者の意図を尊重しながら、X で読みやすい記事に仕上げることが目的です。

前処理のワークフロー

公開する前に記事を読み、X 向けに準備します。

1. 記事の構成を把握する — まず記事を読みます。主なセクションは何か、著者は見出しを使ってどのように考えを整理しているかを確認します。

2. 表と mermaid 図を処理する — これらは画像にする必要があります。それぞれを抽出して PNG に変換し、挿入する位置を記録します。

3. サブスクリプションのプランに合わせて見出しを調整する：

   • Premium+ ユーザーの場合：見出しはそのままにします（H3 以上に対応）
   • Premium ユーザーの場合：記事の流れと意図を保ちながら、H3 以上の見出しを適切に再構成します（上記のガイドラインを参照）

4. 変更後の Markdown を作成する — 調整したバージョンを一時ファイルに保存し、解析に備えます。

目的は、機械的に変換された文書ではなく、X で自然に読める記事を作ることです。

メインワークフロー

方針：「先にテキスト、次に画像、最後に区切り線」

画像や区切り線を含む記事では、まずテキストをすべて貼り付けてから、ブロックインデックスを使って適切な位置に画像と区切り線を挿入します。

1. 前処理：表や mermaid を画像に変換し、深い階層の見出しを整理する
2. Python スクリプトで変更後の Markdown を解析し、タイトル、画像、区切り線（すべて block_index 付き）、HTML を取得する
3. X Articles エディターに移動する
4. カバー画像（最初の画像）をアップロードする
5. タイトルを入力する
6. HTML をクリップボードにコピーする（Python）→ Cmd+V で貼り付ける
7. block_index で指定された位置にコンテンツ画像を挿入する
8. block_index で指定された位置に区切り線を挿入する（［挿入］>［区切り線］メニューから）
9. 下書きとして保存する（自動公開は絶対にしない）

効率的な実行原則

目標：操作間の待ち時間を最小限に抑え、スムーズな自動化を実現します。

1. 不要な browser_snapshot を避ける

ほとんどのブラウザー操作（click、type、press_key など）では、返される結果にページの状態が含まれています。各操作の後に個別に browser_snapshot を呼び出す必要はありません。操作の戻り値に含まれるページ状態をそのまま使ってください。

❌ 错误做法：
browser_click → browser_snapshot → 分析 → browser_click → browser_snapshot → ...

✅ 正确做法：
browser_click → 从返回结果中获取页面状态 → browser_click → ...

2. 不要な browser_wait_for を避ける

browser_wait_for は、次の場合にのみ使用してください。

• 画像のアップロード完了を待つ場合（textGone="正在上传媒体"）
• ページの初期読み込みを待つ場合（ごくまれ）

ボタンや入力欄が表示されるのを待つために browser_wait_for を使用しないでください。ページの読み込みが完了すれば、すぐに使用できます。

3. 独立した操作を並行して実行する

2 つの操作に依存関係がない場合は、同じメッセージ内で複数のツールを並行して呼び出せます。

✅ 可以并行：
- 填写标题 (browser_type) + 复制HTML到剪贴板 (Bash)
- 解析Markdown生成JSON + 生成HTML文件

❌ 不能并行（有依赖）：
- 必须先点击create才能上传封面图
- 必须先粘贴内容才能插入图片

4. ブラウザー操作を連続して実行する

各ブラウザー操作から返されるページ状態には、必要な要素の参照がすべて含まれています。これらの参照をそのまま使って次の操作を実行してください。

# 理想流程（每步直接执行，不额外等待）：
browser_navigate → 从返回状态找create按钮 → browser_click(create)
→ 从返回状态找上传按钮 → browser_click(上传) → browser_file_upload
→ 从返回状态找应用按钮 → browser_click(应用)
→ 从返回状态找标题框 → browser_type(标题)
→ 点击编辑器 → browser_press_key(Meta+v)
→ ...

5. 準備作業を先に済ませる

ブラウザー操作を始める前に、準備をすべて完了させてください。

1. サポートされていない要素（表、Mermaid、深い階層の見出し）を確認する
2. 表や Mermaid を画像に変換する
3. Markdown を解析して JSON データを取得する
4. HTML ファイルを /tmp/ に生成する
5. title、cover_image、content_images などの情報を記録する

こうしておけば、ブラウザー操作の段階を中断せずに連続して実行でき、途中でデータを処理する必要がありません。

ステップ 0：記事を読んで調整する

まず記事を読んでください。 内容と構成を把握し、著者が何を伝えようとしているかを理解します。

元のファイルを保持する

重要： ユーザーの元のファイルは絶対に変更しないでください。調整が必要な場合は、次の手順に従ってください。

1. 調整したバージョンをコピーとして保存します（例：/tmp/article_adapted.md、または元のファイルと同じ場所に article_for_x.md として保存します）。
2. 変更した内容と両方のファイルの保存場所をユーザーに伝えます。

   I've adapted your article for X Premium. Here's what changed:
   - Converted 2 tables to images
   - Restructured 3 H3 headers to bold text for better flow
   
   Original preserved: /path/to/article.md
   Adapted version: /path/to/article_for_x.md
   

3. 公開には調整したコピーを使用します。

これにより、ユーザーは変更を確認でき、元のファイルもそのまま保持できます。

サブスクリプションに応じた調整

Premium ユーザー（Basic Tier）の場合

次の点を確認してください。

• 表はありますか？ → それぞれを PNG 画像に変換します
• mermaid 図はありますか？ → それぞれを PNG 画像に変換します
• H3 以上の見出しはありますか？ → 適切に構成し直します（上記の見出しガイドラインを参照）

読みやすさを維持しながら、Premium の制限内で使えるように Markdown の修正版を作成します。

Premium+ ユーザーの場合

次の点を確認してください。

• mermaid 図はありますか？ → PNG に変換します（どの Tier でもまだサポートされていません）
• 表と H3 以上の見出しは、そのまま使用できます

要素を画像に変換する

# Tables → PNG (auto-detected as table)
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table-1.md -o /tmp/table-1.png

# Mermaid → PNG (auto-detected as mermaid)
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram-1.mmd -o /tmp/diagram-1.png

Markdown 内のこれらの要素を画像参照に置き換え、元の要素があった位置に配置します。

Step 1：Markdown を解析する（Python）

parse_markdown.py を使用して、構造化データをすべて抽出します。

python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /path/to/modified_article.md

出力 JSON：

{
  "title": "Article Title",
  "cover_image": "/path/to/first-image.jpg",
  "content_images": [
    {"path": "/tmp/table-1.png", "block_index": 5, "after_text": "context..."},
    {"path": "/tmp/mermaid-1.png", "block_index": 12, "after_text": "another context..."}
  ],
  "dividers": [
    {"block_index": 7, "after_text": "context before divider..."},
    {"block_index": 15, "after_text": "another context..."}
  ],
  "html": "<p>Content...</p><h2>Section</h2>...",
  "total_blocks": 45
}

主なフィールド：

• block_index：画像または区切り線を、このインデックス（0 始まり）のブロック要素の後に挿入します
• total_blocks：HTML 内のブロック要素の合計数
• after_text：参照／デバッグ用にのみ保持され、配置には使用しません
• dividers：区切り線の位置の配列（Markdown の --- は X のメニューから挿入する必要があり、HTML の <hr> では挿入できません）

クリップボード用に HTML を一時ファイルに保存します。

python parse_markdown.py modified_article.md --html-only > /tmp/article_html.html

Step 2：X Articles エディターを開く

browser_navigate: https://x.com/compose/articles

重要： ページの読み込み後に表示されるのは下書き一覧であり、エディターではありません。次の手順が必要です。

1. ページの読み込み完了を待つ：browser_snapshot を使用してページの状態を確認します
2. すぐに "create" ボタンをクリックする："添加标题" などのエディター要素が表示されるのを待たないでください。これらの要素は create をクリックした後にのみ表示されます
3. エディターの読み込みを待つ：create をクリックした後、エディター要素が表示されるまで待ちます

# 1. 导航到页面
browser_navigate: https://x.com/compose/articles

# 2. 获取页面快照，找到 create 按钮
browser_snapshot

# 3. 点击 create 按钮（通常 ref 类似 "create" 或带有 create 标签）
browser_click: element="create button", ref=<create_button_ref>

# 4. 现在编辑器应该打开了，可以继续上传封面图等操作

注意： ページの読み込みを待つために browser_wait_for text="添加标题" を使用しないでください。このテキストは create をクリックした後にのみ表示されるため、タイムアウトが発生します。

ログインが必要な場合は、手動でログインするようユーザーに促します。

Step 3：カバー画像をアップロードする

1. "添加照片或视频" ボタンをクリックします
2. カバー画像のパス（JSON 出力に記載）を指定して browser_file_upload を使用します
3. 画像がアップロードされたことを確認します

Step 4：タイトルを入力する

• placeholder が "添加标题" の textbox を探します
• browser_type を使用してタイトル（JSON 出力に記載）を入力します

Step 5：テキストコンテンツを貼り付ける（Python クリップボード）

Python を使用して HTML をシステムクリップボードにコピーし、貼り付けます。

# Copy HTML to clipboard
python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py html --file /tmp/article_html.html

次に、ブラウザーで次の操作を行います。

browser_click on editor textbox
browser_press_key: Meta+v

これにより、リッチテキストの書式（H2、太字、リンク、リスト）がすべて保持されます。

Step 6：コンテンツ画像を挿入する（ブロックインデックスで配置）

主な改善点： テキストの一致に頼らず、block_index を使って正確な位置を指定します。

配置の仕組み

HTML を貼り付けると、エディター内のコンテンツは段落、見出し、引用などの一連のブロック要素として構成されます。各画像の block_index は、その画像を何番目のブロック要素の後に挿入するかを示します。

操作手順

1. すべてのブロック要素を取得する：browser_snapshot を使用してエディターのコンテンツを取得し、textbox の下にあるすべての子要素を探します
2. インデックスで位置を指定する：block_index に基づいて、対応するブロック要素をクリックします
3. 画像を貼り付ける：画像をクリップボードにコピーしてから貼り付けます

コンテンツ画像（content_images 配列から）ごとに、次の操作を行います。

# 1. Copy image to clipboard (with compression)
python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py image /path/to/img.jpg --quality 85

# 2. Click the block element at block_index
# Example: if block_index=5, click the 6th block element (0-indexed)
browser_click on the element at position block_index in the editor

# 3. Paste image
browser_press_key: Meta+v

# 4. Wait for upload (use short time, returns immediately when done)
browser_wait_for textGone="正在上传媒体" time=2

逆順で挿入する

注意： 画像を挿入するたびに、後続の画像の実際の位置がずれます。位置のずれを避けるため、画像は block_index の大きい順に挿入することをおすすめします。

画像が 3 枚あり、block_index がそれぞれ 5、12、27 の場合：

1. 最初に block_index=27 の画像を挿入します
2. 次に block_index=12 の画像を挿入します
3. 最後に block_index=5 の画像を挿入します

Step 6.5：区切り線を挿入する（メニューから）

重要： Markdown の --- 区切り線は、HTML の <hr> タグを貼り付けても挿入できません（X Articles では無視されます）。X Articles の Insert メニューから挿入する必要があります。

特別な処理が必要な理由

X Articles には独自のネイティブ区切り線要素があり、Insert > Divider メニューからのみ挿入できます。HTML の <hr> タグは完全に無視されます。

操作手順

区切り線（dividers 配列から）ごとに、block_index の大きい順に次の操作を行います。

# 1. Click the block element at block_index position
browser_click on the element at position block_index in the editor

# 2. Open Insert menu
browser_click on "Insert" button (Add Media button)

# 3. Click Divider menu item
browser_click on "Divider" menuitem

# Divider is inserted at cursor position

逆順で挿入する

画像と同様に、位置のずれを避けるため、区切り線も block_index の大きい順に挿入します。

画像との挿入順序

先にすべての画像を挿入し、その後にすべての区切り線を挿入することをおすすめします。どちらも block_index の大きい順に処理します。

1. すべての画像を挿入します（最大の block_index から開始）
2. すべての区切り線を挿入します（最大の block_index から開始）

Step 7：下書きを保存する

1. コンテンツが貼り付けられたことを確認します（単語数インジケーターを確認）
2. 下書きは自動保存されます。必要に応じて Save ボタンをクリックします
3. "预览" をクリックして書式を確認します
4. 次のように報告します：「下書きが保存されました。内容を確認し、手動で公開してください。」

重要なルール

1. 絶対に公開しない - 下書きとしてのみ保存する
2. 最初に前処理する - 解析前にテーブル／mermaid／深い見出しを変換する
3. 最初の画像をカバー画像にする - 最初の画像をカバー画像としてアップロードする
4. リッチテキスト変換 - 貼り付ける前に、必ず Markdown を HTML に変換する
5. クリップボード API を使う - 書式を適切に保つため、クリップボード経由で貼り付ける
6. ブロックインデックスで位置を指定する - 画像や区切り線を正確に配置するには block_index を使う
7. 逆順で挿入する - 画像と区切り線は、block_index の大きい順に挿入する
8. H1 タイトルの扱い - H1 はタイトルとしてのみ使用し、本文には含めない
9. メニューから区切り線を挿入する - Markdown の --- は「Insert > Divider」メニューから挿入する（HTML の <hr> は無視される）

サポートされる書式（前処理後）

要素	サポート	備考
H2（##）	ネイティブ	セクション見出し
太字（**）	ネイティブ	強調
斜体（*）	ネイティブ	強調
リンク（[](url)）	ネイティブ	ハイパーリンク
順序付きリスト	ネイティブ	1. 2. 3.
順序なしリスト	ネイティブ	- 箇条書き
引用（>）	ネイティブ	引用テキスト
コードブロック	変換	→ 引用
テーブル	変換	→ PNG 画像
Mermaid	変換	→ PNG 画像
H3 以降の見出し	変換	→ H2 または太字
区切り線（---）	メニューから挿入	→ Insert > Divider

実行例

ユーザー：「/path/to/article.md を X に公開して」

# Step 0: Analyze content
# Found: 1 table, 1 mermaid diagram, 2 H3 headers

# Step 0.1: Convert table to image
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table-1.md -o /tmp/table-1.png

# Step 0.2: Convert mermaid to image
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/mermaid-1.mmd -o /tmp/mermaid-1.png

# Step 0.3: Create modified markdown with image refs and flattened headers
# Save to /tmp/article_modified.md

# Step 1: Parse modified markdown
python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /tmp/article_modified.md > /tmp/article.json
python ~/.claude/skills/publish-x-article/scripts/parse_markdown.py /tmp/article_modified.md --html-only > /tmp/article_html.html

2. https://x.com/compose/articles に移動する
3. 作成をクリックし、カバー画像をアップロードする（カバー画像には browser_file_upload のみを使用）
4. タイトルを入力する（JSON の title から取得）
5. HTML をコピーして貼り付ける：

   python ~/.claude/skills/publish-x-article/scripts/copy_to_clipboard.py html --file /tmp/article_html.html
   

   続けて：browser_press_key Meta+v
6. 各コンテンツ画像（変換したテーブル／mermaid の PNG を含む）について、block_index の逆順で：

   python copy_to_clipboard.py image /path/to/img.jpg --quality 85
   

   • block_index の位置にあるブロック要素をクリックする
   • browser_press_key Meta+v
   • アップロードが完了するまで待つ
7. プレビューで確認する
8. 「下書きを保存しました。確認して、手動で公開してください。」

ベストプラクティス

文字列の照合ではなく block_index を使う理由

1. 正確な位置指定：テキストの内容に依存せず、似たテキストが複数箇所にあっても正しく位置を特定できます
2. 信頼性：インデックスは確定的なため、テキストが似ていることで混同されることはありません
3. デバッグが簡単：after_text は手動での確認用に引き続き保持されます

ブラウザー内の JavaScript ではなく Python を使う理由

1. ローカルでの処理のほうが信頼性が高い：Python はシステムのクリップボードを直接操作でき、ブラウザーのサンドボックスによる制限を受けません
2. 画像の圧縮：アップロード前に画像を圧縮（--quality 85）し、アップロード時間を短縮します
3. コードの再利用：スクリプトは固定されているため、変換ロジックを毎回書き直す必要はありません
4. デバッグが簡単：スクリプトを単独でテストできるため、問題を特定しやすくなります

待機方法

重要なポイント：browser_wait_for の textGone パラメーターは、テキストが消えると直ちに返ります。time は最大待機時間であり、固定の待機時間ではありません。

# 正确用法：短 time 值，条件满足立即返回
browser_wait_for textGone="正在上传媒体" time=2

# 错误用法：固定长时间等待
browser_wait_for time=5  # 无条件等待5秒，浪费时间

カバー画像とコンテンツ画像

• カバー画像：browser_file_upload を使います（専用のアップロードボタンがあるため）
• コンテンツ画像：Python のクリップボードと貼り付けを使います（より効率的）

トラブルシューティング

テーブルが正しく表示されない

• Pillow がインストールされていることを確認する：pip install pillow
• テーブルの Markdown 構文が正しいことを確認する

Mermaid の変換に失敗する

• diagramless.xyz にアクセスできることを確認する
• mermaid の構文が正しいことを確認する
• 明示的なタイプを指定して試す：--type mermaid

深い見出しがそのまま表示される

• ### → ## または **bold** に手動で変換する
• 前処理を再実行する

画像のアップロードがタイムアウトする

• --quality 70 を指定して画像を圧縮する
• browser_wait_for time=2 のように短く設定する