rst-to-myst

name	rst-to-myst
description	既存の reStructuredText 製 Sphinx ドキュメントを rst-to-myst で MyST Markdown へ移行するスキル。実質的な RST コンテンツを持つプロジェクトの移行を求められたときに使用する(sphinx-quickstart の雛形だけの場合は対象外)。変換結果を検証してから元ファイルを削除する。
license	MIT
allowed-tools	Bash, Read, Write

パッケージマネージャ検出と一時ツール実行 (ad-hoc)

検出優先順位 (該当した時点で確定):

優先	判定条件	採用
1	uv.lock が存在	uv
2	poetry.lock が存在	poetry
3	Pipfile.lock が存在	pipenv
4	.venv/ のみ存在	plain venv
5	上記すべて該当しない	ユーザー問い合わせ (推奨: uv)

rst-to-myst パッケージは依存に含めず単発実行する (ad-hoc)。PM ごとの実行コマンド:

PM	ad-hoc 実行
uv	uvx --from "rst-to-myst[sphinx]" rst2myst convert <files>
poetry	pipx run --spec "rst-to-myst[sphinx]" rst2myst convert <files> (要 pipx)
pipenv	pipx run --spec "rst-to-myst[sphinx]" rst2myst convert <files> (要 pipx)
plain venv	pipx run --spec "rst-to-myst[sphinx]" rst2myst convert <files> または pip install で venv に追加

pipx 不在時はパッケージを一時的に依存追加 → 実行 → 削除する手順を提示する。

用途と非用途

対象

数ファイル以上の実コンテンツを持つ既存 RST プロジェクトの移行。

非対象

sphinx-quickstart -q が生成した最小 index.rst 単体 — sphinx-init が直接 MyST テンプレートで生成するため、本スキルは呼ばれない。

発火条件

• 「既存の RST プロジェクトを MyST に変換」「Markdown に移行」「.rst を .md に変える」
• docs/ 配下に複数の .rst ファイルが存在し (sphinx-quickstart 生成 index.rst のみではない)、移行希望が示された場合
• sphinx-init MyST 選択時に index.rst 以外の .rst を検出した場合 (sphinx-init からの委譲呼出)

実行フロー (3段階の段階的検証で原本保護)

1. 対象ファイル特定

• 単一ファイル or docs/ 配下全体
• 原本 .rst のサイズを記録 (検証で参照)

2. ad-hoc 変換実行

冒頭の「パッケージマネージャ検出と一時ツール実行」表に従い、検出した PM に対応するコマンドを実行する。

# uv の例
uvx --from "rst-to-myst[sphinx]" rst2myst convert <files>

3. 変換結果の妥当性検証

以下のすべてを満たす場合のみ「変換成功」とみなす:

• (a) 対応する .md ファイルが生成されている (存在確認)
• (b) .md ファイルが空でない、かつサイズが原本 .rst の 30% 以上
• (c) 変換エラー行 (<SYSTEM MESSAGE: ...> 等の rst-to-myst 既知エラーマーカ) を含まない

いずれか不成立の場合:

• 原本 .rst を残す
• 生成された不完全な .md を削除
• 検証失敗の理由を含む例外を送出 (デフォルト値での継続禁止)

4. 原本削除

上記 3 が「変換成功」の場合のみ .rst を削除する。

5. conf.py 更新案内

sphinx-config スキルへ委譲し myst-parser を extensions に追加する。

6. 執筆移行案内

myst-authoring スキルが今後 .md 編集時に自動発火する旨を伝える。

関連スキル

• 委譲先: sphinx-config (myst-parser 追加)
• 後続: myst-authoring (変換後の MyST 執筆)
• 委譲元: sphinx-init (index.rst 以外の .rst 検出時)