Agent skill

pdf-to-markdown

Convert a PDF book or document into clean, structured Markdown files split by chapter/section, with embedded images. Uses the Gemini Files API for high-quality conversion. Handles hyphenation repair, page-break paragraph joining, and blockquote formatting.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/akaihola/skills-akaihola/tree/main/pdf-to-markdown

SKILL.md

PDF to Markdown

Convert a structured PDF (book, report, manual) into clean Markdown files – one file per section – with images extracted and embedded.

Requirements

  • GEMINI_API_KEY environment variable set
  • uv available

Usage

Step 1: Create a config file

Create config.toml next to your PDF describing the sections and their page ranges:

toml
pdf = "MyBook.pdf"
output_dir = "."
images_dir = "images"
model = "gemini-2.0-flash"          # optional, this is the default
rate_limit_sleep = 1.0              # seconds between API calls

[[sections]]
slug = "chapter-1"
start_page = 10
end_page = 53
heading = "# Chapter 1 – Introduction"
output = "chapters/01-introduction.md"

[[sections]]
slug = "chapter-2"
start_page = 54
end_page = 113
heading = "# Chapter 2 – Core Concepts"
output = "chapters/02-core-concepts.md"

[[sections]]
slug = "appendix-1"
start_page = 114
end_page = 121
heading = "# Appendix 1 – Self-Assessment"
output = "appendices/appendix-1.md"
# Optional: extra instructions appended to the prompt for this section
instructions = "Format all quiz questions as numbered lists."

Tips for setting page ranges:

  • Use a PDF viewer that shows physical page numbers (not printed numbers)
  • Sections that are too long (>~50 pages) may hit the model's output token limit – split them
  • Use gemini-2.0-flash (not flash-lite) for long sections

Step 2: Run the converter

bash
GEMINI_API_KEY=your-key uv run ~/.claude/skills/pdf-to-markdown/scripts/convert.py config.toml

The script:

  1. Extracts all embedded images from the PDF with pymupdf
  2. Uploads the PDF once to the Gemini Files API
  3. Converts each section with a targeted prompt
  4. Fixes remaining hyphenation and page-break artifacts in post-processing
  5. Embeds image references at the correct locations
  6. Deletes the uploaded file from the API when done

Output structure

./
├── config.toml
├── images/
│   ├── image-01-page11.png
│   └── image-01-page22.png
└── chapters/
    ├── 01-introduction.md
    └── 02-core-concepts.md

Image paths in Markdown are relative from each output file to the images directory.

What Gemini handles well

  • Removing page numbers and headers/footers
  • Preserving heading hierarchy (##, ###)
  • Formatting block quotes (>)
  • Recognising section structure from visual layout

Known limitations

  • Footnote superscripts (¹ ²) and asterisk references (*) are reproduced as-is, not linked to their footnote text
  • Very long sections (>60 pages) may truncate – split them in config.toml
  • Image placement within a section is approximate (Gemini marks [IMAGE page N] which maps to extracted images by page number)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

akaihola/skills-akaihola

youtube-to-markdown

Convert a YouTube video into clean, readable Markdown using its free auto-generated captions (no paid API needed). Use when the user asks to "convert YouTube video to markdown", "get transcript from YouTube URL", "summarise this video", or wants to turn YouTube subtitles/captions into readable text. Prefer this over youtube-transcription when the video already has auto-generated subtitles — it's free and faster. Accepts YouTube URLs.

1 0
Explore
akaihola/skills-akaihola

brave-search

Search the web using Brave Search API. Use when the user asks to "search the web", "look up current information", "find news about", "research a topic online", "check prices online", or needs up-to-date facts that may not be in the model's training data. Requires BRAVE_SEARCH_API_KEY. Supports structured web results (pages, FAQs, news, videos) and an optional AI summarizer.

1 0
Explore
akaihola/skills-akaihola

verkkokauppa

Search products on the Verkkokauppa.com Finnish webshop. This skill uses the Verkkokauppa search API directly, requiring no browser. Use when the user asks to "search Verkkokauppa", "find products on verkkokauppa.com", "verkkokauppa product search", "check Verkkokauppa prices", or mentions searching the Verkkokauppa store.

1 0
Explore
akaihola/skills-akaihola

clasohlson

Search products on the Clas Ohlson Finland webshop (clasohlson.com/fi/). This skill uses the Voyado Elevate (Apptus eSales) search API directly, requiring no browser. Use when the user asks to "search Clas Ohlson", "find products on clasohlson.com", "clas ohlson product search", "check Clas Ohlson prices", or mentions searching the Finnish Clas Ohlson store.

1 0
Explore
akaihola/skills-akaihola

bauhaus

Search products on the Bauhaus webshop (bauhaus.fi). This skill uses the Algolia search API with automatic key refresh. Use when the user asks to "search Bauhaus", "find products on bauhaus.fi", "bauhaus product search", "check Bauhaus prices", or mentions searching the Bauhaus store.

1 0
Explore
akaihola/skills-akaihola

library

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results