EPUB Read

Task-mode-driven EPUB reading and analysis skill with overview, targeted reading, chunked full reading, extraction, complex-content inspection, and batch pro...

Security Scan

The skill's code, runtime instructions, and requested environment are consistent with an EPUB parsing/chunking/reading tool and do not ask for unrelated credentials or network access.

Purpose & Capability

Name/description (EPUB reading, chunking, extraction) match the included scripts (parse_epub.py, chunk_book.py, task_router.py, update_session_state.py, utils.py). Requested binary is python3 which is appropriate; no unrelated binaries or secrets are required.

Instruction Scope

SKILL.md instructs the agent to parse, chunk, route tasks, and manage session state using the included Python scripts and to read/write files under the book output directory. The instructions do not attempt to read system-wide config, environment secrets, or transmit data to external endpoints. All file reads/writes are confined to the parsed-book output tree.

Install Mechanism

There is no install spec (no automatic downloads), which is low risk. The repository includes a requirements.txt (beautifulsoup4, lxml) so the user must install Python dependencies manually or via pip. No external installers, URL downloads, or extracted archives are used by the skill.

Credentials

The skill declares no required environment variables or credentials and the code does not reference environment secrets. All required resources are local files and Python packages, which is proportionate to the stated functionality.

Persistence & Privilege

always is false and the skill does not modify other skills or global agent settings. It writes/reads session_state.json and various parse artifacts inside the book output directory, which is expected for a reading-progress feature.

Assessment

This skill appears coherent and safe for EPUB processing: it runs local Python scripts, writes output under a dedicated book directory, and does not request secrets or make network calls. Before installing: (1) install its Python dependencies in an isolated venv (pip install -r requirements.txt), (2) run test_integration.py with a non-sensitive local EPUB to confirm behavior, and (3) only run it on EPUB files you trust (it will write parsed content and state files to disk). If you want extra assurance, review the omitted truncated files (remaining parse/chunk logic) or run the scripts in a sandbox/container.

<objective> Provide a strict, auditable EPUB workflow that safely handles long books through explicit task routing instead of loading full-book text by default. </objective>

<use_when>

• The user mentions an .epub file or ebook
• The user wants a quick structural overview
• The user wants chapter-specific or chunk-specific reading
• The user wants full-book sequential reading with chunking
• The user wants structured extraction
• The user wants to inspect images, tables, or other complex content
• The user wants to batch-process multiple EPUB files </use_when>

<process>

STEP 0 - Choose exactly one task mode before doing anything else

Mode	Purpose	Use when
overview	Fast structural overview	Metadata, TOC, themes, structure only
targeted_read	Focused reading	Specific chapters, chunk ranges, or keyword hits
full_read	Sequential reading	Long-book chunked reading with saved progress
extract	Structured extraction	Keywords, definitions, quotes, examples, action items, entities, tables, lists
complex_content	Complex-layout inspection	Images, tables, SVG, low-text sections
batch	Multi-book planning	Multiple EPUB files or folders

Default to overview or targeted_read when the user intent is ambiguous. Never load a long book's full body text by default.

STEP 1 - Parse if needed

1. Check whether the output directory already exists and contains manifest.json.
2. If not, run parse_epub.py.
3. After parsing, report:
   • title
   • author
   • chapter count
   • chunk count if available
   • image count
   • table count
   • output directory

STEP 2 - Build an execution plan

Use task_router.py to decide whether parsing, chunking, or state updates are required:

python3 task_router.py <book_dir> --mode <mode> [params...]

The plan should tell you:

• whether parsing is required
• whether chunking is required
• which files are recommended to read
• whether session state must be updated

STEP 3 - Mode-specific behavior

overview

• Read only metadata, TOC, reading index, and other structural outputs
• Do not load the whole book body by default
• Return:
  • title
  • author
  • chapter count
  • TOC structure
  • theme overview
  • suggested next actions

targeted_read

Support:

• --chapter
• --chapter-id
• --chunk-start
• --chunk-end
• --keyword

Return:

• the requested section
• short context
• concise summary

full_read

• Prefer chunk-based reading for long books
• Support continue, previous, next, and jump flows
• Always update session_state.json
• Never pretend progress exists if the session state is missing

extract

Support extracting:

• keywords
• definitions
• quotes
• examples
• action_items
• names
• locations
• organizations
• tables
• lists

Return a hit list with chapter references and short context.

complex_content

Inspect:

• images
• SVG
• tables
• image-heavy sections
• low-text / high-resource sections

Return a structured report. OCR is not required by default.

batch

Support:

• multiple EPUB file paths
• directory scanning
• batch planning
• batch extraction requests

Return success / failure counts and a concise overview.

STEP 4 - Long-book safety rules

• Never push the full body of a long book into context at once
• Prefer chunks/ over chapter markdown for full sequential reading
• When chunking is required, run chunk_book.py first
• Use reading_index.json to map chapters to chunk ranges

STEP 5 - State management rules

When running full_read or any progress-sensitive flow:

1. Read session_state.json first
2. Update it after every progress-changing action
3. Respect existing saved progress unless the user explicitly asks to restart

STEP 6 - Output style

Be explicit about:

• what files were used
• what mode was selected
• why a long book was chunked instead of loaded fully
• what the user can do next

When possible, point the user toward the safest next step:

• continue reading
• jump to a chapter
• inspect a chunk range
• extract a structure
• review complex content

</process> <validation>

Before considering the task complete, check:

• parsing outputs exist
• chunk files exist when required
• reading index and session state are coherent
• extraction targets match the requested type
• complex-content reports are generated from real parsed outputs

</validation>