EPUB Reader Skill for Claude Code
A Claude Code skill that enables efficient reading of EPUB ebook files.
Capabilities
- Metadata extraction - title, author, publisher, date, language
- Table of contents - view chapter structure
- Chapter reading - read specific chapters by number
- Full extraction - extract entire book as markdown
- Search - find text with surrounding context
Directory Structure
~/.claude/skills/epub/
├── SKILL.md # Skill definition (triggers on EPUB-related requests)
├── AGENTS.md # This documentation
├── CLAUDE.md -> AGENTS.md # Symlink
└── scripts/epub-reader/
├── package.json
├── tsconfig.json
├── src/index.ts # TypeScript source
└── dist/ # Compiled JavaScript
Technology Stack
- TypeScript - main implementation language
- jszip - extract EPUB contents (EPUBs are ZIP archives)
- xml2js - parse OPF/NCX metadata files
- turndown - convert HTML content to Markdown
- commander - CLI argument parsing
CLI Commands
# View metadata
node ~/.claude/skills/epub/scripts/epub-reader/dist/index.js metadata "<file.epub>"
# List table of contents
node ~/.claude/skills/epub/scripts/epub-reader/dist/index.js toc "<file.epub>"
# Read specific chapter (1-indexed)
node ~/.claude/skills/epub/scripts/epub-reader/dist/index.js chapter "<file.epub>" <number>
# Extract entire book
node ~/.claude/skills/epub/scripts/epub-reader/dist/index.js full "<file.epub>"
# Search for text
node ~/.claude/skills/epub/scripts/epub-reader/dist/index.js search "<file.epub>" "<query>"
How the Skill Works
- SKILL.md defines when Claude should use this skill (any EPUB-related request)
- Claude automatically invokes the appropriate CLI command based on user intent
- Output is clean Markdown suitable for reading and analysis
Rebuilding
If you need to modify and rebuild:
cd ~/.claude/skills/epub/scripts/epub-reader
npm install
npm run build
Restart Claude Code after any changes to SKILL.md for them to take effect.
Changelog
2025-11-26: TOC-to-Chapter Navigation Fix
Problem: The table of contents (TOC) display showed sequential numbering that didn't correspond to the chapter command's spine-based indexing. Users had no way to know which chapter number to use.
Solution:
- TOC now displays inline chapter references:
Chapter Five [ch: 14] - Users can see exactly which number to use with the
chaptercommand - Fixed title extraction to properly search the nested TOC tree by href instead of assuming index alignment
Changes made to src/index.ts:
- Added
buildHrefToSpineMap()- creates href-to-spine index mapping - Added
findTocItemByHref()- recursively searches TOC tree for matching href - Updated
formatToc()- shows[ch: N]inline with each entry - Fixed
getChapterContent()- uses proper TOC lookup for title extraction
2025-11-26: Open-Ended Search Documentation
Added documentation for handling broad/conceptual queries using LLM-assisted query expansion. For queries like "what are the main themes?" or "find references to the protagonist's childhood", Claude expands the query into multiple specific search terms using domain knowledge, runs parallel searches, and synthesizes the results. This leverages Claude's knowledge to catch synonyms and related concepts without requiring fuzzy search infrastructure.