tuzi-format-markdown

Markdown フォーマッター

プレーンテキストまたは Markdown ファイルを、適切なフロントマター、書式、タイポグラフィを備えた整った Markdown に変換します。

スクリプトディレクトリ

スクリプトは scripts/ サブディレクトリにあります。${SKILL_DIR} は、この SKILL.md のディレクトリパスに置き換えてください。

スクリプト	用途
scripts/main.ts	CLI オプションを備えたメインエントリーポイント（CJK の強調表示に remark-cjk-friendly を使用）
scripts/quotes.ts	ASCII の引用符を全角引用符に置き換えます
scripts/autocorrect.ts	autocorrect を使って CJK と英語の間にスペースを追加します

設定（EXTEND.md）

Bash を使って、次の優先順位で EXTEND.md の有無を確認します。

# Check project-level first
test -f .tuzi-skills/tuzi-format-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────────────┬───────────────────┐ │ パス │ 場所 │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ .tuzi-skills/tuzi-format-markdown/EXTEND.md │ プロジェクトディレクトリ │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md │ ユーザーホーム │ └──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ 結果 │ アクション │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 見つかった │ 読み取り、解析し、設定を適用します │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 見つからない │ デフォルト設定を使用します │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md で設定できる項目：デフォルトの書式設定オプション | 要約の長さの設定

使い方

Claude がコンテンツを分析して書式を整え（ステップ 1～6）、その後スクリプトを実行してタイポグラフィを修正します（ステップ 7）。

ワークフロー

ステップ 1：ソースファイルを読み込む

ユーザーが指定した Markdown またはプレーンテキストのファイルを読み込みます。

ステップ 1.5：コンテンツの種類を判定して確認する

コンテンツの種類の判定：

指標	分類
--- YAML フロントマターがある	Markdown
#、##、### の見出しがある	Markdown
**太字**、*斜体* がある	Markdown
- または 1. のリストがある	Markdown
``` コードブロックがある	Markdown
> の引用がある	Markdown
上記のいずれもない	プレーンテキスト

判断の流れ：

┌─────────────────┬────────────────────────────────────────────────┐ │ コンテンツの種類 │ アクション │ ├─────────────────┼────────────────────────────────────────────────┤ │ プレーンテキスト │ ステップ 2 に進む（Markdown に書式を整える） │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ AskUserQuestion を使って最適化するか確認する │ └─────────────────┴────────────────────────────────────────────────┘

Markdown が検出された場合、ユーザーに尋ねます：

Detected existing markdown formatting. What would you like to do?

1. Optimize formatting (Recommended)
   - Add/improve frontmatter, headings, bold, lists
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

3. Typography fixes only
   - Run typography script on original file in-place
   - No copy created, modifies original file directly

ユーザーの選択に応じて：

• 最適化：ステップ 2～8 に進みます（全ワークフロー）
• 元のままにする：ステップ 2～5 をスキップし、ファイルをコピー → ステップ 6～8 に進みます（コピーに対してスクリプトを実行）
• タイポグラフィのみ：ステップ 2～6 をスキップし、元のファイルに対してステップ 7 を直接実行します

ステップ 2：コンテンツ構造を分析する

以下を特定します：

• 既存のタイトル（H1 #）
• 段落の区切り
• 太字にするのに適したキーワード
• リストに変換できる並列的な内容
• コードスニペット
• 引用

Step 3: フロントマターの確認／作成

YAML フロントマター（--- ブロック）を確認します。存在しない場合は作成します。

メタフィールドの処理：

フィールド	処理
title	Step 4 を参照
slug	ファイルパスから推測します（例：posts/2026/01/10/vibe-coding/ → vibe-coding）。またはタイトルから生成します
summary	読み手を惹きつける概要を100～150文字で生成します
coverImage	同じディレクトリに imgs/cover.png があるか確認します。存在する場合は相対パスを使用します（featureImage も使用できます）

Step 4: タイトルの処理

ロジック：

1. フロントマターに title がすでにある場合 → それを使用し、本文に H1 を置きません
2. 1行目が H1 の場合 → フロントマターの title に移し、本文から H1 を削除します
3. どちらにも当てはまらない場合 → タイトル候補を生成します

タイトル生成の流れ：

1. 内容に基づいてタイトル候補を3つ生成します
2. AskUserQuestion ツールを使用します：

Select a title:

1. [Title A] (Recommended)
2. [Title B]
3. [Title C]

3. 数秒以内に選択されない場合は、推奨候補（選択肢1）を使用します

タイトルの原則：

• 簡潔にし、最大20文字にします
• 中心となるメッセージを捉えます
• 読み手の関心を引き、読みたいと思わせます
• 内容に忠実にし、クリックベイトを避けます

重要： タイトルをフロントマターに記載したら、重複を避けるため、本文に H1 を置かないでください。

Step 5: 書式の処理

書式ルール：

要素	書式
タイトル	#、##、### の階層を使用します
重要なポイント	**太字** を使用します
並列項目	順不同リストの - または番号付きリストの 1. に変換します
コード／コマンド	`inline` または ```block``` を使用します
引用／格言	> の引用ブロックを使用します
区切り	適切な箇所で --- を使用します

書式設定の原則：

• 元の内容と見解を保ちます
• 書式のみを追加し、テキストは変更しません
• 書式設定は読みやすさを高めるために行います
• 過剰な書式設定は避けます

Step 6: 書式設定済みファイルの保存

{original-filename}-formatted.md として保存します

例：

• final.md → final-formatted.md
• draft-v1.md → draft-v1-formatted.md

ユーザーが「元の書式を維持」を選択した場合（Step 1.5）：

• 元のファイルを変更せずに {filename}-formatted.md にコピーします
• Step 7 に進み、タイポグラフィの修正のみを行います

既存ファイルのバックアップ：

{filename}-formatted.md がすでに存在する場合は、上書きする前にバックアップします：

# Check if formatted file exists
if [ -f "{filename}-formatted.md" ]; then
  # Backup with timestamp
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi

例：

• final-formatted.md が存在する場合 → final-formatted.backup-20260128-143052.md にバックアップします

Step 7: テキスト書式設定スクリプトの実行

保存後、書式設定スクリプトを必ず実行します：

npx -y bun ${SKILL_DIR}/scripts/main.ts {output-file-path} [options]

スクリプトのオプション：

オプション	短縮形	説明	デフォルト
--quotes	-q	ASCII 引用符を全角引用符 "..." に置換します	false
--no-quotes		引用符を置換しません
--spacing	-s	autocorrect を使用して CJK／英語間のスペースを追加します	true
--no-spacing		CJK／英語間のスペースを追加しません
--emphasis	-e	CJK の強調に関する句読点の問題を修正します	true
--no-emphasis		CJK の強調に関する問題を修正しません
--help	-h	ヘルプメッセージを表示します

例：

# Default: spacing + emphasis enabled, quotes disabled
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# Enable all features including quote replacement
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing

# Disable all processing except frontmatter formatting
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis

スクリプトの処理内容（オプションに応じて実行）：

1. CJK の強調／太字に関する句読点の問題を修正します（デフォルト：有効）
2. autocorrect を使用して CJK／英語混在テキストのスペースを追加します（デフォルト：有効）
3. ASCII 引用符 "..." を全角引用符 "..." に置換します（デフォルト：無効）
4. フロントマターの YAML を整形します（常に有効）

Step 8: 結果の表示

**Formatting complete**

File: posts/2026/01/09/example/final-formatted.md

Changes:
- Added title: [title content]
- Added X bold markers
- Added X lists
- Added X code blocks

書式設定の例

変更前：

This is plain text. First point is efficiency improvement. Second point is cost reduction. Third point is experience optimization. Use npm install to install dependencies.

変更後：

---
title: Three Core Advantages
slug: three-core-advantages
summary: Discover the three key benefits that drive success in modern projects.
---

This is plain text.

**Main advantages:**
- Efficiency improvement
- Cost reduction
- Experience optimization

Use `npm install` to install dependencies.

注意事項

• 元の文体とトーンを維持します
• コードブロックには適切な言語を指定します（例：python、javascript）
• CJK／英語間のスペースの基準を守ります
• 元の内容にない情報を追加しません

拡張機能のサポート

EXTEND.md を使用してカスタム設定ができます。パスとサポート対象のオプションについては、Preferences セクションを参照してください。