ebookSkill: EPUB to Markdown Splitter & Translator

A specialized AI-Agent skill for converting EPUB ebooks into clean, well-structured, and intelligently split Markdown files, optimized for reading, knowledge management (Obsidian), and AI-driven translation workflows.

---

🚀 Overview

ebookSkill solves the problem of “monolithic” ebook conversions. Instead of one massive, unmanageable Markdown file, this tool:

1. Converts EPUB to GitHub-Flavored Markdown using Pandoc.
2. Extracts all images into a local folder with relative links.
3. Splits the content intelligently by chapters (H1/H2) and manageable line counts (200-300 lines) to prevent context window exhaustion during AI processing.
4. Cleans residual HTML tags (like , ) often left behind by conversion tools.
5. Standardizes an AI translation workflow for high-quality, chapter-by-chapter translation.

📂 Directory Structure

ebookSkill/
├── SKILL.md                # AI-Agent instructions and workflow logic
├── README.md               # This file
└── scripts/
    ├── epub_to_md_splitter.py  # Core conversion and splitting engine
    └── clean_markdown.py       # HTML tag cleanup utility

🛠 Prerequisites

• Pandoc: Required for initial EPUB to MD conversion.
• Python 3: Required to run the processing scripts.

📖 Usage Guide

1. Basic Conversion & Splitting

Run the core script on any .epub file:

python scripts/epub_to_md_splitter.py /path/to/your/ebook.epub

Output: A new folder named after the book containing:

• images/: All extracted media.
• 01_Chapter_Name.md, 02_Part_1.md, etc.: The split content.
• full_content.md: The raw, un-split conversion.

2. Markdown Cleanup

If your Markdown files contain messy HTML tags:

python scripts/clean_markdown.py path/to/file.md

3. AI-Driven Translation Workflow

This skill defines a specific SOP for AI agents (like Claude or Gemini):

1. Delete full_content.md to avoid accidental massive processing.
2. Generate a translation_prompt.txt for domain-specific terminology.
3. Confirm the prompt with the user.
4. Translate split files sequentially into a Translated/ folder.

⚙️ Splitting Logic

• Primary Split: Triggered by # or ## headers.
• Secondary Split: Triggered if a section exceeds 200 lines. The script looks ahead for natural breaks (sub-headers or paragraph ends) between 200-300 lines to ensure structural integrity.

---

ebookSkill: EPUB 转 Markdown 切分与翻译工具 (ZH)

这是一个专门为 AI Agent 设计的技能，用于将 EPUB 电子书转换为干净、结构化且智能切分的 Markdown 文件。针对阅读、知识管理（Obsidian）以及 AI 驱动的翻译工作流进行了深度优化。

🚀 概述

ebookSkill 解决了电子书转换中“大一统”文件的痛点。与其产出一个巨大且难以处理的 Markdown 文件，本工具可以：

1. 转换：使用 Pandoc 将 EPUB 转换为 GitHub 风格的 Markdown (GFM)。
2. 提取：将所有图片提取到本地文件夹，并保持相对链接。
3. 切分：按章节 (H1/H2) 和可控行数（200-300 行）智能切分内容，防止 AI 处理时超出上下文窗口。
4. 清理：清除转换工具常残留的 HTML 标签（如 , ）。
5. 标准化：定义了 AI 翻译 SOP，实现高质量的逐章翻译。