epub-reader
Skill0 starsChanged 3 months agoMITView on GitHub
Use this skill when the user wants to read, navigate, extract, or summarize content from an epub ebook file. Trigger phrases include: 'read this epub', 'open this ebook', 'what does chapter X say', 'summarize this book', 'show me the table of contents', 'find the section about X in this epub', 'epub file', '.epub'. Always consult the TOC before reading any content. Do NOT use for PDF, DOCX, or other non-epub formats.
In this repository24 other files it gives its agents.
- corporate-espionageSkill
- dispatching-parallel-agentsSkill
- executing-plansSkill
- finishing-a-development-branchSkill
- github-raw-readerSkill
- magisk-moduleSkill
- notepadpp-plugin-skillSkill
- planningSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- reviewSkill
- skill-creator2Skill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- technical-writerSkill
- test-driven-developmentSkill
- text-humanizerSkill
- using-git-worktreesSkill
- using-superpowersSkill
- verification-before-completionSkill
- windows-diagnosticsSkill
- writing-plansSkill
- zed-extensionSkill
- zed-themeSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Read and navigate epub ebook files using a TOC-first strategy.
- Distinctive: line 10
Always map the book structure via the TOC before reading any chapter content.
- Distinctive: line 14
Follow these steps in order for every epub reading task.
- Distinctive: line 35
Do not skip this step. The TOC is the navigation map for all subsequent reads.
- Distinctive: line 54
When the user asks about a topic and the chapter is not obvious from the TOC:
- Very specific: line 61
Use the returned index to run a read command.
- Very specific: line 83
If toc returns zero entries, the epub has no readable TOC.
- Distinctive: line 91
Run from the skill root directory or pass absolute paths.
- Distinctive: line 92
No external dependencies. Uses Python 3 stdlib only.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
epub-reader
Read and navigate epub ebook files using a TOC-first strategy. An epub is a ZIP archive containing HTML chapter files organized by a manifest and table of contents. Always map the book structure via the TOC before reading any chapter content.
Workflow
Follow these steps in order for every epub reading task.
Step 1 - Inspect the file
python scripts/epub_reader.py info <epub_path>Output is JSON with title author language publisher and structural counts. Present the book title and author to the user before proceeding.
Step 2 - Load and display the TOC
python scripts/epub_reader.py toc <epub_path>Output is JSON with an entries array.
Each entry has index, id, title, href, and level.
Present the TOC as a numbered list using the title and index fields.
The href field is the internal path used when reading.
Do not skip this step. The TOC is the navigation map for all subsequent reads.
Step 3 - Read a chapter
python scripts/epub_reader.py read <epub_path> <ref>ref is a 1-based index number, an exact TOC entry id, or a partial title string.
The script resolves the ref against the TOC and extracts plain text from the HTML file.
Output is truncated to 8999 chars by default.
To read the full chapter without truncation:
python scripts/epub_reader.py read <epub_path> <ref> --fullStep 4 - Search the TOC (optional)
When the user asks about a topic and the chapter is not obvious from the TOC:
python scripts/epub_reader.py search <epub_path> "<query>"Output lists all TOC entries whose titles match the query.
Use the returned index to run a read command.
Decision rules
| User asks for | Action |
| Table of contents or chapter list | Run toc and present as numbered list |
| A specific chapter by name or number | Run toc first then read with matching index |
| A topic or keyword | Run search then read the best match |
| Book metadata or summary of what the book is | Run info and toc then synthesize |
| Full book content | Warn user that full extraction can be large then loop read over all entries |
Error handling
| Error message | Cause | Fix |
not a valid epub zip | File is not an epub or is corrupted | Ask user to verify the file |
META-INF/container xml missing | File is not a valid epub container | Try running file <path> to confirm format |
content file not found in epub | TOC entry href does not match zip contents | Run toc to get valid hrefs and retry |
ambiguous match | Partial title matched multiple entries | Use the numeric index from toc output instead |
index N out of range | Index exceeds total entry count | Check total_entries in toc output |
If toc returns zero entries, the epub has no readable TOC.
Fall back to reading by spine order using numeric index starting at 1.
Script reference
See references/epub-structure.md for details on EPUB format internals, namespace constants, and edge cases the script handles.
Script location: scripts/epub_reader.py
Run from the skill root directory or pass absolute paths.
No external dependencies. Uses Python 3 stdlib only.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

