book-analyzer

<Use_When>

• User provides a path to an EPUB or PDF book file
• User says "analyze this book", "process this book", "read this book"
• User wants structured notes from a book-length document (20+ pages) </Use_When>

<Do_Not_Use_When>

• Short documents under 20 pages — use /paper or /process instead
• User wants to read or search specific sections — just use Read tool directly
• User wants EPUB output from markdown — wrong direction
• URL-only input with no file on disk — use /research instead </Do_Not_Use_When>

<Why_This_Exists> Book notes that merely transcribe content are useless — the value is in synthesis. Most book notes in a vault end up sparse because processing a full book manually is exhausting. This skill automates the mechanical work (extraction, splitting, formatting) while delegating the intellectual work (synthesis, assessment, connections) to specialized agents with strict quality constraints. </Why_This_Exists>

<Execution_Policy>

• Run extraction scripts first, verify output before proceeding to analysis
• Delegate chapter analysis to parallel agents (one per chapter, all simultaneous)
• Use Sonnet for chapter analysis, Opus for cross-book synthesis
• Vault integration is conditional — detect .obsidian/ or CLAUDE.md in working directory
• Report progress via TodoWrite at each stage transition
• If extraction fails, stop and report — don't guess at content
• Total chapters capped at 50 — if more, group adjacent chapters into batches </Execution_Policy>

Stage 1: PARSE ARGUMENTS AND EXTRACT

Parse $ARGUMENTS to get the book file path and optional flags.

Argument format:

$ARGUMENTS = "path/to/book.epub"                    # basic
$ARGUMENTS = "path/to/book.pdf --no-terms"          # skip term extraction
$ARGUMENTS = "path/to/book.epub --output ~/Desktop/" # custom output location

Parse logic:

1. Split $ARGUMENTS by spaces, treating quoted paths as single tokens
2. First non-flag token = file path (REQUIRED — stop if missing)
3. Optional flags: --no-terms (skip concept extraction), --output <dir> (custom output)
4. Detect format from file extension: .epub, .pdf, .mobi

Run extraction based on format:

For EPUB:

SKILL_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")"
# Find skill directory — check common locations
for dir in .claude/skills/book-analyzer ~/.claude/skills/book-analyzer; do
  if [ -f "$dir/scripts/extract_epub.py" ]; then SKILL_DIR="$dir"; break; fi
done
WORK_DIR=".book-work-$(date +%s)"
python3 "$SKILL_DIR/scripts/extract_epub.py" "INPUT_PATH" "$WORK_DIR"

For PDF:

WORK_DIR=".book-work-$(date +%s)"
"$SKILL_DIR/scripts/extract_pdf.sh" "INPUT_PATH" "$WORK_DIR"

For MOBI: Convert to EPUB first with ebook-convert (calibre), then run EPUB extraction.

The work directory is created inside the vault root (e.g., .book-work-1709398200/). Clean it up after the pipeline completes.

After extraction: Read $WORK_DIR/metadata.json to verify success.

PDF fallback: If metadata shows "needs_fallback": true, use the Claude Read tool instead:

• Read the PDF 20 pages at a time: Read(file_path="INPUT_PATH", pages="1-20"), then pages="21-40", etc.
• Write each batch to $WORK_DIR/pages/page_batch_NNN.txt
• Update metadata with actual content

Stage 2: STRUCTURE

Read metadata.json from the extraction output.

For EPUBs: Chapter structure comes directly from extraction (H1/H2 splitting). Proceed to Stage 3.

For PDFs: Chapter detection depends on extraction quality.

• If pages have clear chapter headings, group pages into chapters
• If no clear structure: Launch a single agent to read the first 5 pages and detect chapter boundaries:

Agent(
  subagent_type="general-purpose",
  model="haiku",
  prompt="Read the following text from the first 5 pages of a book. Identify chapter
  boundaries and return a JSON array of {title, start_page, end_page} objects.
  If no chapters are detectable, return [{title: 'Full Text', start_page: 1, end_page: LAST}].

  TEXT:
  [first 5 pages content]"
)

• Update metadata with detected chapter list
• Group page files into chapter files by concatenation

Result: A chapters/ directory with one file per chapter, and updated metadata.json.

Stage 3: ANALYZE (parallel, file-based)

Read the agent definition from agents/chapter-analyst.md in the skill directory.

Create analyses directory:

mkdir -p "$WORK_DIR/analyses"

For EACH chapter, launch a parallel agent that WRITES ITS OUTPUT TO A FILE:

Agent(
  subagent_type="general-purpose",
  model="sonnet",
  run_in_background=true,
  prompt="You are Chapter Analyst. Follow these instructions exactly:

  [INSERT FULL CONTENT OF agents/chapter-analyst.md HERE]

  BOOK CONTEXT:
  - Title: {title}
  - Author: {author}
  - This is Chapter {N} of {total_chapters}
  - Table of Contents: {chapter_list summary}

  CHAPTER FILE TO READ: {path to chapter .md file}
  OUTPUT_FILE: $WORK_DIR/analyses/ch{NN}_analysis.md

  CRITICAL: Read the chapter file, produce your analysis, then WRITE it to OUTPUT_FILE using the Write tool. Be detailed — include all interesting quotes, concrete examples, and anecdotes. The master agent will read your file later."
)

Parallel execution: Launch ALL chapter agents simultaneously with run_in_background=true. Wait for all to complete. Verify all analysis files exist in $WORK_DIR/analyses/.

Why file-based: Agent return messages get truncated by context compression. Writing to files preserves full detail — every quote, every example, every nuance. The master agent reads these files directly.

Chapter cap: If more than 50 chapters, batch adjacent chapters (2-3 per agent) to stay within limits.

Result: One analysis file per chapter in $WORK_DIR/analyses/, each containing detailed notes with quotes.

Stage 4: SYNTHESIZE + SECTION WRITE (parallel)

This stage runs the cross-book synthesizer AND section writers ALL IN PARALLEL.

Batching formula: Divide chapters into batches of ~5 chapters each. M = min(max(ceil(N/5), 1), 10) where N = total number of chapters.

Create sections directory:

mkdir -p "$WORK_DIR/sections"

Read agent definitions from agents/book-synthesizer.md and agents/section-writer.md.

Launch ALL of the following simultaneously (one message, all with run_in_background=true):

4a. Book Synthesizer (Opus)

Agent(
  subagent_type="general-purpose",
  model="opus",
  run_in_background=true,
  prompt="You are Book Synthesizer. Follow these instructions exactly:

  [INSERT FULL CONTENT OF agents/book-synthesizer.md HERE]

  BOOK METADATA:
  - Title: {title}
  - Author: {author}
  - Total chapters: {N}

  ANALYSIS FILES DIRECTORY: $WORK_DIR/analyses/
  Read ALL .md files in this directory.

  OUTPUT_FILE: $WORK_DIR/synthesis.md
  Write your synthesis to this file.

  IMPORTANT: Per-chapter detail is handled by section writer agents.
  Your job is ONLY cross-chapter patterns: Core Thesis, Deepest Insights,
  Chapter Map, Critical Assessment, Cross-Domain Connections."
)

4b. Section Writers (Sonnet, one per batch)

For each batch of ~5 chapters:

Agent(
  subagent_type="general-purpose",
  model="sonnet",
  run_in_background=true,
  prompt="You are Section Writer. Follow these instructions exactly:

  [INSERT FULL CONTENT OF agents/section-writer.md HERE]

  BOOK CONTEXT:
  - Title: {title}
  - Author: {author}

  YOUR ASSIGNED CHAPTER ANALYSES (read ALL of these):
  - $WORK_DIR/analyses/ch{NN}_analysis.md
  - $WORK_DIR/analyses/ch{NN}_analysis.md
  - ... (list all files in this batch)

  OUTPUT_FILE: $WORK_DIR/sections/part_{MM