book-skill-generator

name	book-skill-generator
description	OCR JSONから本ごとの専用ナレッジスキルを自動生成する。「この本のスキルを作って」「本を登録したい」「OCRした本をスキルにしたい」と言われた時にこのスキルを使う。本のOCR JSONファイルパスを指定してもらい、チャプター構造の解析、要約生成、スキルファイルの生成までを自動で行う。

Book Skill Generator

OCR JSON（Cosense形式）から、本ごとの専用ナレッジスキルを自動生成する。

背景

本一冊をまるごと読むのは時間がかかるが、問題にぶち当たった時にその本の知識を活用できれば十分なケースが多い。このスキルは、本のOCRデータを解析して「必要な時に必要な知識を引き出せる」スキルを生成する。生成されたスキルは、ユーザーが関連する問題に遭遇した時に自動でトリガーされ、本の該当箇所を参照して回答する。

前提

• 本のデータはCosenseエクスポート形式のJSON（pages配列、各ページにtitleとlines）
• OCRテキストは > プレフィックスの行に含まれる
• 生成されるスキルは ~/.claude/skills/ に配置される

生成ワークフロー

Phase 1: OCR JSONの解析

ユーザーからOCR JSONのパスを受け取ったら、パーススクリプトを実行する。

python3 ~/.claude/skills/book-skill-generator/scripts/parse_book.py "<OCR_JSON_PATH>" "/tmp/book-parse-output"

このスクリプトは以下を行う：

• > プレフィックスのテキストを抽出
• ヘッダー/フッター（進捗表示、ランニングヘッダー等）を除去
• 章の見出し（第N章、第N部、はじめに、おわりに等）を検出（複数行にまたがるOCR特有のパターンにも対応）
• 目次ページと本文ページを区別
• チャプターごとにテキストファイルを生成

出力:

• structure.json: チャプター構造（タイトル、ページ範囲、文字数）
• chapters/: チャプターごとのマークダウンファイル

Phase 2: 構造の確認と修正

structure.json を読み、以下を確認する：

1. チャプター数が妥当か: 目次と照合して、抜けている章がないか確認
2. 巨大なチャプターがないか: 1つのチャプターが本の大部分を占めている場合、章の分割が失敗している可能性がある
3. タイトルが取れているか: "chapter 1" のように番号だけになっている場合、本文から正しいタイトルを探す
4. 章の順序が正しいか: OCRの章検出が前後していないか確認

問題が見つかった場合は、OCR JSONの該当ページを直接読んで正しい章境界を特定し、手動でチャプターファイルを修正する。

典型的な問題と対処法：

• 章の見出しが本文中に埋もれている場合: OCR JSONのページを直接読み、第N章 や セクション番号 (N.N) を探す
• 目次ページが本文として扱われている場合: structure.json から該当エントリを除外
• front_matter が大きすぎる場合: 序文やはじめにが含まれている可能性。適切に分割する
• タイトルがgenericの場合: OCR JSONの該当ページの > 行を直接読み、正しいタイトルを取得する。 < 第N章 > の後の行に書いてあることが多い
• 末尾に索引・参考文献が章として検出される場合: 1-2ページの小さなエントリは back_matter として扱うか、削除する

Phase 3: チャプター要約の生成

各チャプターの要約をサブエージェント（Task ツール）で並列生成する。コンテキスト溢れを防ぐため、以下のルールを厳守すること。

サブエージェントへの指示方法

サブエージェントのプロンプトには チャプターのテキストを埋め込まない。代わりにファイルパスを渡し、サブエージェント自身に Read ツールで読ませる。

各サブエージェントには以下を指示する：

1. 指定されたチャプターファイル（/tmp/book-parse-output/chapters/{slug}.md）を Read ツールで読む
   • ファイルが 20,000 文字を超える場合は、offset/limit パラメータを使って分割して読む（例: 最初に offset=1, limit=300、次に offset=301, limit=300 のように）
2. 読んだ内容から以下を生成する：
   • 章の要約（3-5文）: その章で扱っている主要なテーマと論点
   • キー概念（5-10個）: その章で説明されている重要な用語や概念。ユーザーが検索しそうな言葉を含める
   • 実践的な知見（2-3個）: 問題解決に直接使える知識やパターン。「〜な状況では〜が有効」のように、問題と解法をセットで記述する
3. 結果を /tmp/book-parse-output/summaries/{slug}_summary.md に Write ツールで書き出す

サブエージェントの設定

Task ツールの設定:
- subagent_type: "general-purpose"
- model: "haiku"           # 要約タスクにはhaiku で十分。コンテキスト節約のため必須
- max_turns: 5             # Read → (分割読みの場合追加Read) → 要約作成 → Write で十分
- run_in_background: true  # 並列実行のため必須

プロンプトのテンプレート

以下のチャプターファイルを読んで要約を生成し、結果をファイルに書き出してください。

チャプターファイル: /tmp/book-parse-output/chapters/{slug}.md
出力先: /tmp/book-parse-output/summaries/{slug}_summary.md

手順:
1. Read ツールでチャプターファイルを読む（20,000文字超の場合は offset/limit で分割して読む）
2. 以下の形式で要約を生成する
3. Write ツールで出力先に書き出す

出力形式:
---
**要約**: （3-5文でこの章の主要テーマと論点を記述）

**キー概念**: 概念A, 概念B, 概念C, ...（5-10個）

**実践的な知見**:
- 〜する場合は〜が有効
- 〜の問題には〜で対処できる
---

メインコンテキストの保護

• サブエージェントを run_in_background: true で起動した後、TaskOutput でサブエージェントの結果を読み込まない
• 代わりに、全サブエージェントの完了を待ってから、結果ファイル（/tmp/book-parse-output/summaries/ 配下）を 1つずつ Read ツールで読み、index.md に統合する
• 全てのサブエージェント完了の確認は、summaries ディレクトリ内のファイル数とチャプター数の一致で判断する（ls /tmp/book-parse-output/summaries/ | wc -l で確認）

事前準備

サブエージェント起動前に、出力ディレクトリを作成する：

mkdir -p /tmp/book-parse-output/summaries

Phase 4: index.md の生成

Phase 3 で /tmp/book-parse-output/summaries/ に書き出された要約ファイルを 1つずつ Read ツールで読みながら、index.md を組み立てる。一度に全ファイルを読み込まないこと（コンテキスト保護のため）。このファイルが生成されるスキルの「目次」となり、ユーザーの質問に対してどの章を参照すべきかを判断する際の手がかりになる。

フォーマット：

# 「本のタイトル」インデックス

**著者**: XXX
**概要**: 本全体の内容を2-3文で要約

## 章構成

### 第1章: タイトル (pages XXX-YYY)

**要約**: この章では〜を扱っている。〜について説明し、〜を論じている。
**キー概念**: 概念A, 概念B, 概念C, ...
**実践的な知見**:

- 〜する場合は〜が有効
- 〜の問題には〜で対処できる

### 第2章: タイトル (pages XXX-YYY)

...

Phase 5: スキルの生成

以下のファイルを ~/.claude/skills/<スキル名>/ に生成する：

1. SKILL.md: テンプレート（templates/skill_template.md）をベースに、以下を埋める

   • {{SKILL_NAME}}: 本のドメインに基づく英語スラッグ（例: virtualization-tech-book）
   • {{SKILL_DESCRIPTION}}: 最も重要。本のドメインに特化したトリガー説明。以下を含める：
     • この本が扱うドメイン・分野
     • 具体的なトピック、キーワード、用語（日本語と英語の両方）
     • この本の知識が役立つ具体的な問題場面
     • 「〜について知りたい」「〜の仕組みを教えて」「〜で困っている」のようなトリガーフレーズ
   • {{BOOK_TITLE}}: 本のタイトル
   • {{BOOK_AUTHOR}}: 著者名

2. references/index.md: Phase 4 で生成したもの

3. references/chapters/: Phase 1-2 で生成したチャプターファイル

Phase 6: 動作確認

生成されたスキルのパスをユーザーに伝え、想定される利用シーンを2-3個提示する。

例:

• 「仮想マシンのメモリアドレス空間について教えて」
• 「ハイパーバイザで割り込みを処理する方法は？」

注意事項

• OCRの品質が低い箇所（文字化け、行の途切れ）は、前後の文脈から補完して理解する
• 図表のキャプションが本文に混在していることがある。章の要約では図表の内容も含める
• 生成するスキルの description は、ユーザーが自然に使うであろう言葉（日本語）を含める
• description は少し「押しが強い」くらいがちょうどよい。スキルがトリガーされないよりは、少し広めにトリガーされた方がよい