baoyu-format-markdown

Markdown フォーマッター

プレーンテキストまたは Markdown を、構造が整った読みやすい Markdown に変換します。元のコンテンツを変更せずに、読者が要点や重要箇所、構成をすばやく把握できるようにすることを目的としています。

基本原則：書式の調整と明らかな誤字の修正のみを行います。コンテンツの追加、削除、書き換えは一切行いません。

ユーザー入力ツール

このスキルがユーザーに質問する場合は、次の優先順位に従ってツールを選択してください。

1. 組み込みのユーザー入力ツールを優先する：現在のエージェントランタイムが提供する AskUserQuestion、request_user_input、clarify、ask_user など、または同等のツールを使用します。
2. 代替手段：そのようなツールがない場合は、番号付きのプレーンテキストメッセージを出力し、各質問に対する選択肢の番号または回答をユーザーに返信してもらいます。
3. まとめて質問する：1 回の呼び出しで複数の質問に対応できる場合は、該当する質問をすべてまとめます。1 回に 1 つの質問しかできない場合は、優先順位に従って 1 つずつ質問します。

以下の AskUserQuestion に関する具体例は参考用です。他のランタイムでは、ローカルの同等ツールに置き換えてください。

スクリプトディレクトリ

スクリプトは scripts/ サブディレクトリにあります。{baseDir} はこの SKILL.md のディレクトリパスです。${BUN_X} ランタイムを解決します：bun がインストールされている場合は bun、npx が利用可能な場合は npx -y bun を使います。どちらも利用できない場合は、bun のインストールを提案します。{baseDir} と ${BUN_X} は実際の値に置き換えてください。

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

設定（EXTEND.md）

優先順位に従って EXTEND.md を確認してください。最初に見つかったものを使用します。

優先度	パス	適用範囲
1	.baoyu-skills/baoyu-format-markdown/EXTEND.md	プロジェクト
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md	ユーザーホーム

見つからない場合はデフォルト設定を使用します。このスキルでは初回セットアップは不要です。

EXTEND.md で設定できる項目：

設定	値	デフォルト	説明
auto_select	true/false	false	タイトルと要約の選択を両方省略し、最適なものを自動選択します
auto_select_title	true/false	false	タイトルの選択のみ省略します
auto_select_summary	true/false	false	要約の選択のみ省略します
その他	—	—	デフォルトの書式設定オプション、タイポグラフィの設定

使い方

ワークフローは 分析（コンテンツを理解する）と 整形（書式を適用する）の 2 つのフェーズで構成されます。Claude がコンテンツの分析と整形（ステップ 1～5）を行い、その後スクリプトを実行してタイポグラフィを修正します（ステップ 6）。

ワークフロー

ステップ 1：読み取りとコンテンツタイプの判定

ユーザーが指定したファイルを読み取り、コンテンツタイプを判定します。

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

Markdown と判定された場合は、AskUserQuestion を使用して質問します：

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

1. Optimize formatting (Recommended)
   - Analyze content, improve headings, bold, lists for readability
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script only
   - Output: {filename}-formatted.md

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

ユーザーの選択に基づいて：

• 最適化：ステップ 2（ワークフロー全体）に進みます
• 元のまま保持：ステップ 5 に進み、ファイルをコピーしてからステップ 6 を実行します
• タイポグラフィのみ：ステップ 6 に進み、元のファイルを直接処理します

ステップ 2：コンテンツを分析する（読者の視点）

コンテンツ全体を注意深く読みます。読者の視点に立ち、重要な情報をすばやく理解して記憶するために役立つことを考えます。

次の観点から分析を作成します。

2.1 ハイライトと重要な知見

• 著者が示す主な主張や結論
• 意外な事実、データ、直感に反する主張
• 印象に残る引用や、よく練られた文章（名言）

2.2 構成の評価

• 論理的な流れは明確ですか？どのような流れですか？
• 見出しがないものの、自然な区切りとなる箇所はありますか？
• 視覚的な区切りを入れると読みやすくなる、長い文章のまとまりはありますか？

2.3 読者にとって重要な情報

• 実践できるアドバイスや要点
• 重要な概念の定義や説明
• 文章中に埋もれているリストや列挙
• 表にすると比較や対比がわかりやすくなる箇所

2.4 書式の問題

• 見出し階層の欠落や不統一
• 複数の話題が混在する段落
• 本来はリストにすべき並列項目が文章で書かれている箇所
• コード、コマンド、技術用語がコードとしてマークされていない箇所
• 明らかな誤字や書式の誤り

分析をファイルに保存：{original-filename}-analysis.md

分析ファイルはステップ 3 の設計図として使用します。次の形式を使用してください。

# Content Analysis: {filename}

## Highlights & Key Insights
- [list findings]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [list heading candidates with brief rationale]

## Reader-Important Information
- [list actionable items, key concepts, buried lists, potential tables]

## Formatting Issues
- [list specific issues with location references]

## Typos Found
- [list any obvious typos with corrections, or "None found"]

ステップ 3：フロントマター、タイトル、要約を確認・作成する

YAML フロントマター（--- ブロック）があるか確認します。ない場合は作成します。

フィールド	処理
title	以下のタイトルの生成を参照してください
slug	ファイルパスから推測するか、タイトルから生成します
summary	1 文で簡潔に要約します（以下の要約の生成を参照してください）
description	より詳しい説明文を作成します（以下の要約の生成を参照してください）
coverImage	同じディレクトリに imgs/cover.png があるか確認し、あれば相対パスを使用します

タイトルの生成

タイトルの有無にかかわらず、auto_select_title が設定されていない限り、タイトル最適化の手順を実行します。

準備 — 全文を読み、次の内容を抽出します。

• 主題（1 文で：「この記事は何について書かれていますか？」）
• 最も印象的な意見や結論
• 読者の悩みや興味を引くきっかけ
• 最も印象に残る比喩や名言

references/title-formulas.md の公式を使用して、候補を作成します。

1. 記事の内容、トーン、構成に基づいて、最も適した2～3 個のフック公式を選びます（参照ファイルの「各公式を選ぶタイミング」を参照してください）。
2. 率直なタイトルを 1～2 個作成します（公式を使わない説明的または断定的なタイトルで、明確かつ正確なもの）。
3. ユーザーが方向性（例：「サスペンスのあるものにする」）を指定した場合は、その方向性を優先します。
4. 合計：4～5 個の候補

AskUserQuestion を使って提示します。

Pick a title:

1. [Hook title A] — (recommended) [formula name]
2. [Hook title B] — [formula name]
3. [Hook title C] — [formula name]
4. [Straightforward title D] — straightforward
5. [Straightforward title E] — straightforward

Enter number, or type a custom title:

最も有力なフックを先頭に置き、(recommended) と付けます。原則と禁止パターンについては references/title-formulas.md を参照してください。

先頭行が H1 の場合は、フロントマターに移して本文から削除します。フロントマターに title がすでにある場合は、そのタイトルを参考情報として含めますが、新しい候補も作成します。既存のタイトルが弱い可能性があるためです。

スキップの動作：auto_select: true または auto_select_title: true の場合は、ユーザーへの質問を省略し、最上位の候補をそのまま使用します。

要約の生成

ユーザーに選択させずに2種類を直接生成し、どちらもフロントマターに保存します。

フィールド	長さ	目的
summary	1文、約50～80文字	簡潔なフック — フィード、ソーシャル共有、SEO メタデータ向け
description	2～3文、約100～200文字	より詳しい背景 — 記事のプレビュー、ニュースレターの紹介文向け

原則：

• トピックだけでなく、読者にとっての中心的な価値を伝えます
• 曖昧な説明よりも、具体的な詳細（数値、成果、具体的な手法）を使います
• summary は印象的で、それだけで意味が通じるものにします。description では補足情報を加えて詳しく説明できます
• フロントマターに summary または description がすでにある場合は、既存のものを残し、不足しているフィールドだけを生成します

禁止するパターン：

• 「この記事では……を紹介します」「この記事では……を解説します」
• 価値を示さず、トピックだけを説明すること
• タイトルを別の言葉で繰り返すこと

タイトルがフロントマターにある場合、重複を避けるため、本文に H1 を含めないでください。

ステップ 4：コンテンツの書式設定

ステップ 2 の分析に基づいて書式を適用します。コンテンツを読みやすくし、重要なポイントを確実に見つけられるようにすることが目的です。

書式設定ツールキット：

要素	使用する場面	書式
見出し	自然なトピックの区切り、セクションの区切り	##、### の階層
太字	重要な結論、重要な用語、中心的な要点	**太字**
箇条書き	並列項目、機能一覧、例	- 項目
番号付きリスト	順序のある手順、順位付き項目、手順	1. 項目
表	比較、構造化データ、選択肢の一覧	Markdown の表
コード	コマンド、ファイルパス、技術用語、変数名	`インライン` またはフェンス付きブロック
引用	注目すべき引用、重要な警告、引用文	> 引用
区切り線	大きなトピックの切り替わり	---

書式設定の原則 — してはいけないこと：

• 文、説明、コメントを追加しないでください
• コンテンツを削除したり、短くしたりしないでください
• 著者の言葉を言い換えたり、書き直したりしないでください
• 編集者の主観を含む見出し（例：「驚くべき発見」）を追加しないでください。中立的で説明的な見出しを使ってください
• 過剰に書式設定しないでください。すべての文を太字にしたり、すべての段落に見出しを付けたりする必要はありません

書式設定の原則 — すること：

• 著者の声、トーン、すべての言葉を保ちます
• 重要な結論や中心的な要点を太字にします — 読者が強調表示するような文が対象です
• 構造が明確な場合に限り、文章中の並列項目をリストにします
• トピックが実際に変わる箇所に見出しを追加します。一般的な見出しよりも、印象的で具体的な見出しを優先します（例：「3 天搞定 vs 传统方案」ではなく「方案对比」）
• 文章中に埋もれた比較や構造化データには表を使います
• 心に残る言葉や重要な警告には引用を使います
• 明らかな誤字を修正します（ステップ 2 の調査結果に基づく）

ステップ 5：書式設定済みファイルの保存

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

既存ファイルをバックアップする：

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

ステップ 6：タイポグラフィスクリプトの実行

出力ファイルに書式設定スクリプトを実行します：

${BUN_X} {baseDir}/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 の強調に関する問題を修正しません

例：

# Default: spacing + emphasis enabled, quotes disabled
${BUN_X} {baseDir}/scripts/main.ts article.md

# Enable all features including quote replacement
${BUN_X} {baseDir}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing

スクリプトが実行する処理（オプションに基づく）：

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

ステップ 7：完了レポート

行ったすべての変更を要約したレポートを表示します。

**Formatting Complete**

**Files:**
- Analysis: {filename}-analysis.md
- Formatted: {filename}-formatted.md

**Content Analysis Summary:**
- Highlights found: X key insights
- Golden quotes: X memorable sentences
- Formatting issues fixed: X items

**Changes Applied:**
- Frontmatter: [added/updated] (title, slug, summary)
- Headings added: X (##: N, ###: N)
- Bold markers added: X
- Lists created: X (from prose → list conversion)
- Tables created: X
- Code markers added: X
- Blockquotes added: X
- Typos fixed: X [list each: "original" → "corrected"]

**Typography Script:**
- CJK spacing: [applied/skipped]
- Emphasis fixes: [applied/skipped]
- Quote replacement: [applied/skipped]

実際の変更内容を反映するようにレポートを調整し、変更がなかったカテゴリは省略します。

注意事項

• 元の文体とトーンを維持します
• コードブロックには正しい言語を指定します（例：python、javascript）
• CJK／英語のスペースの規則に従います
• 分析ファイルは作業用ドキュメントです。特定した内容と整形した内容の一貫性を保つのに役立ちます

拡張機能のサポート

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