book-converter

Book Converter Skill

EPUB 書籍を、AI による品質改善を加えた、プロフェッショナルな書式の Markdown 書籍に変換します。

概要

このスキルは、次の手順で EPUB ファイルを高品質な Markdown ドキュメントに変換します。

1. pandoc を使って EPUB から生の Markdown を抽出します
2. 構造化されたプロジェクトディレクトリを作成します
3. AI 主導で書式の修正を計画し、実行します
4. 章ごとに書式を整えた出力を生成します
5. 目次付きの結合済み書籍ファイルを生成します

クイックスタート

ユーザーが EPUB ファイルのパスを指定します。

/Users/username/Downloads/Book.Name.2024.epub

変換ワークフローを実行します。

python3 scripts/convert_book.py "/path/to/book.epub"

これにより、変換プロセス全体が開始されます。

ワークフロー

重要：メインのコンテキストが汚染されないよう、すべての書式設定作業にサブエージェントを使用してください。

フェーズ 1：セットアップと抽出（メインエージェント）

変換スクリプトを実行します。

python3 scripts/convert_book.py "/path/to/book.epub"

このスクリプトは次の処理を行います。

1. EPUB ファイルが存在することを確認します
2. プロジェクト構成を作成します。
   • books/book-name/ - メインディレクトリ
   • books/book-name/raw/ - pandoc の出力
   • books/book-name/chapters/ - 書式を整えた章
   • books/book-name/images/ - 抽出した画像
3. pandoc を実行して Markdown を抽出します
4. 書式基準をプロジェクトディレクトリにコピーします

出力：books/book-name/raw/book-parsed.md に生の Markdown が保存されます

フェーズ 2：分析と計画（スクリプト＋サブエージェント）

ステップ 1：構造分析スクリプトを実行します（メインエージェント）。

python3 books/book-name/analyze_structure.py books/book-name

このスクリプトは次の処理を行います。

• すべての見出しを行番号付きで抽出します
• サンプリングによって書式の問題を検出します
• 章の境界を提案します
• STRUCTURE_ANALYSIS.md レポートを作成します（35k 行以上ではなく、約 5～10 KB）

ステップ 2：general サブエージェントを起動して、マッピングファイルを作成します。

Task(
  subagent_type="general",
  description="Create chapter map and formatting plan",
  prompt="""Create CHAPTER_MAP.md and FORMATTING_PLAN.md:

1. Read books/book-name/STRUCTURE_ANALYSIS.md (concise report with headers and issues)
2. Read books/book-name/references/chapter-map-template.md for format
3. Read books/book-name/references/formatting-plan-template.md for format
4. Create books/book-name/CHAPTER_MAP.md:
   - Use suggested chapter boundaries from analysis
   - Verify line ranges make sense
   - Create proper slugged filenames
5. Create books/book-name/FORMATTING_PLAN.md:
   - Document issues found in analysis
   - Add severity and priority
   - Note book-specific patterns
6. Update books/book-name/progress.md to mark Phase 2 complete

Return: Summary of chapters found and major issues identified."""
)

出力：CHAPTER_MAP.md、FORMATTING_PLAN.md、および更新された progress.md

フェーズ 3：章の書式設定（サブエージェントを使用）

各章について、個別に general サブエージェントを起動します。

# Example for Chapter 1
Task(
  subagent_type="general",
  description="Format Chapter 1",
  prompt="""Format Chapter 1 following the chapter formatting workflow.

**Critical Instructions:**
1. Read and follow ALL steps in books/book-name/references/chapter-workflow.md
2. Apply formatting rules from books/book-name/references/formatting-standards.md
3. Use books/book-name/CHAPTER_MAP.md to find line ranges for Chapter 1
4. Read books/book-name/FORMATTING_PLAN.md for known issues to watch for

**Workflow Summary (see chapter-workflow.md for complete details):**

Step 1: Read Standards and Chapter Map
- Read references/formatting-standards.md
- Read CHAPTER_MAP.md for your chapter's line ranges
- Read FORMATTING_PLAN.md for known issues

Step 2: Extract Chapter Content
- Extract Chapter 1 from raw/book-parsed.md using line ranges

Step 3: Identify Issues follow the standards
- Headers using bold instead of #
- Shattered code blocks
- Split paragraphs
- Missing code language identifiers
- Emphasis artifacts [word]
- Corrupted footnotes
- Missing image alt text
- Broken links

Step 4: Apply Formatting Fixes
- Follow the three-pass approach in chapter-workflow.md:
  * First pass: Structure (headers, code blocks)
  * Second pass: Content (paragraphs, emphasis)
  * Third pass: Details (footnotes, images, links)

Step 5: Create Output File
- Write to books/book-name/chapters/chapter-01-title.md
- Use structure from chapter-workflow.md

Step 6: Update Progress
- Update books/book-name/progress.md with completion status
- Document fixes applied

**Quality Checklist (from chapter-workflow.md):**
- [ ] All headers use proper # syntax
- [ ] All code blocks have language identifiers
- [ ] No shattered code blocks remain
- [ ] Text flows naturally without mid-sentence breaks
- [ ] All footnotes have [^N] format with definitions
- [ ] Images have descriptive alt text

Return: Confirmation with summary of fixes applied."""
)

重要：

• 効率化のため、サブエージェントは並行するバッチ（1 回につき 3～5 個）で起動してください
• 各サブエージェントは chapter-workflow.md と formatting-standards.md を読む必要があります
• 一貫した品質を確保するため、体系的なワークフローに従ってください

出力：books/book-name/chapters/ に書式を整えた章が保存されます

フェーズ 4：書籍の組み立て（メインエージェント）

merge_book.py スクリプトはすでにプロジェクトディレクトリにコピーされています。実行するだけです。

python3 books/book-name/merge_book.py books/book-name

このスクリプトは次の処理を行います。

1. CHAPTER_MAP.md を読み込み、章の順序を確認します
2. chapters/ から書式を整えたすべての章を読み込みます
3. 目次用に見出しを抽出します
4. 画像パスを修正します（最終的な保存場所を基準にします）
5. すべての章を順番に結合します
6. 詳細な目次を生成します
7. books/book-name-book.md に出力します

出力：書式を整えた書籍全体が含まれる books/book-name-book.md

注：結合スクリプトは再利用できます。書籍ごとに作成する必要はありません。

重要：章の書式設定要件

フェーズ 3 のすべてのサブエージェントは、必ず次のことを行ってください。

1. 最初に chapter-workflow.md を読む - 完全な手順が段階ごとに記載されています
2. formatting-standards.md を読む - すべての書式ルールが記載されています（678 行）
3. ワークフローに体系的に従う - 手順を省略しないでください
4. 3 パス方式を使用する：
   • 1 回目：構造を修正（見出し、コードブロック）
   • 2 回目：内容を修正（段落、強調）
   • 3 回目：詳細を修正（脚注、画像、リンク）
5. 品質チェックリストを完了する - 終了前にすべての項目を確認してください

これが重要な理由：

• すべての章で一貫した品質を確保できます
• よくあるミス（問題の見落とし、スタイルの不統一）を防げます
• Clean Code Collection（35k 行以上）で実証済みのプロセスです
• 各章の書式設定は 1 回だけ行うため、徹底する必要があります

ワークフローのドキュメントに手順がすべて記載されています。記載内容に従ってください。

サブエージェントの使用原則

メインコンテキストで書籍の内容を処理しないでください。 必ずサブエージェントを使用して、次の作業を行ってください。

1. メインコンテキストをクリーンに保つ：書籍の内容は膨大で、コンテキストを圧迫します
2. 並列処理を可能にする：複数の章を同時にフォーマットできます
3. フォーマット作業を分離する：各章には新しいコンテキストを使用します
4. トークン制限を回避する：未加工のコンテンツはコンテキストウィンドウを超える場合があります

サブエージェントの選択：書籍処理のすべてのタスクで、必ず subagent_type="general" を使用してください。

進捗管理

books/book-name/progress.md を作成し、管理してください。

# Book Name - Conversion Progress

## Phase 1: Setup ✓
- [x] EPUB extracted
- [x] Project structure created

## Phase 2: Planning ✓
- [x] Chapter map created (15 chapters identified)
- [x] Formatting plan documented

## Phase 3: Chapter Formatting (5/15 complete)
- [x] Front Matter
- [x] Chapter 1: Introduction
- [x] Chapter 2: Getting Started
- [x] Chapter 3: Advanced Topics
- [x] Chapter 4: Best Practices
- [ ] Chapter 5: Performance
- [ ] ...

## Phase 4: Assembly
- [ ] Merge script created
- [ ] Final book generated

サブエージェントが完了するたびに更新してください。

品質基準

フォーマット済みの出力は、すべて次の基準を満たす必要があります。

• 見出し：太字ではなく、適切な # 構文を使用する
• コードブロック：言語識別子を付け、分断されたブロックを結合する
• 文章の流れ：分割された文を自然な段落につなげる
• 強調：[brackets] ではなく、*italic* と **bold** を使用する
• 脚注：定義を付けた標準の [^1] 形式を使用する
• 画像：汎用的なファイル名ではなく、内容を説明する代替テキストを付ける
• リンク：PDF 変換による不要な要素を取り除き、アンカーを整える

完全な基準については、references/formatting-standards.md を参照してください。

使用例

ユーザーのリクエスト：

「この EPUB を Markdown に変換してください：/Users/john/Downloads/Effective.Java.3rd.Edition.epub」

スキルの実行：

1. 変換スクリプトを実行してコンテンツを抽出する
2. 構造を分析し、章のマップを作成する
3. AI サブエージェントを使用して各章をフォーマットする
4. 目次を付けて最終版の書籍にまとめる
5. books/effective-java-final.md をユーザーに提供する

スクリプト

• convert_book.py：メインの変換スクリプト（フェーズ 1）。EPUB を抽出し、プロジェクトを設定します
• analyze_structure.py：構造分析スクリプト（フェーズ 2）。見出しを抽出し、問題を効率的に検出します
• merge_book.py：再利用可能な統合スクリプト（フェーズ 4）。すべての章を最終版の書籍にまとめます

参考資料

• formatting-standards.md：フォーマット規則の全内容（フォーマット時に必要に応じて読み込みます）
• chapter-workflow.md：章のフォーマットワークフローの詳細（必要に応じて読み込みます）
• progress-template.md：進捗管理ファイルのテンプレート
• chapter-map-template.md：章マップのテンプレート
• formatting-plan-template.md：フォーマット上の問題を記録するためのテンプレート

注意事項

• 品質を重視：AI による手動のフォーマットにより、文章を自然な流れに整えます
• 自動スクリプトは使用しない：行の結合には、人間のような判断が必要です
• コンテンツを保持：意味を変えたり、コンテンツを削除したりしないでください
• コードの正確性：コードブロックが構文的に完全であることを確認してください