# pdf-to-markdown

pdf-to-markdown transcribes scanned and image-based PDFs into formatted Markdown files saved in the same directory as the source document.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 5 installs · ★ 4 repo stars
- Author: lttr
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/lttr/dotfiles/tree/HEAD/claude/skills/pdf-to-markdown/SKILL.md
- Updated: 2026-10-22
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/lttr-pdf-to-markdown

## What it does

This skill relies on vision capabilities to read pages directly instead of calling separate OCR APIs. It first inspects page totals with `pdfinfo`. When a document spans 10 or more pages, it splits the file into 4-page batches with `qpdf` and handles them simultaneously through Task agents.

The resulting `.md` file retains headings, lists, original diacritics, and handwritten notes in italics. Strikethrough syntax marks crossed-out phrases. Once merging finishes, temporary files are cleaned up automatically.

Without `qpdf` installed on your machine, processing documents with 10 or more pages will fail during the chunking phase.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add lttr/dotfiles --skill pdf-to-markdown -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/pdf-to-markdown/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/pdf-to-markdown/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add lttr/dotfiles --skill pdf-to-markdown -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/pdf-to-markdown/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add lttr/dotfiles --skill pdf-to-markdown -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/pdf-to-markdown/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install lttr/dotfiles claude/skills/pdf-to-markdown
```

2. **Manually: put the files in place**
- File: `.github/skills/pdf-to-markdown/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add lttr/dotfiles --skill pdf-to-markdown -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/lttr/dotfiles --path claude/skills/pdf-to-markdown
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/pdf-to-markdown/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add lttr/dotfiles --skill pdf-to-markdown -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/lttr/dotfiles/tree/HEAD/claude/skills/pdf-to-markdown/SKILL.md

## When to use it
- extract text from scanned or image-based PDF files
- convert multi-page documents in parallel 4-page batches
- preserve handwritten edits and crossed-out notes in markdown
- format raw scanned pages into clean heading and list structures

## Example prompts
- Transcribe `scanned_contract.pdf` into a markdown file
- Convert the image document `history_archive.pdf` to markdown
- Extract text from `records.pdf` while preserving handwritten annotations

## Similar
- [pdf-tools](https://affpapa.org/en/nevibecode/skills/pdf-tools.md) — skill · 186 installs
- [markdown-converter](https://affpapa.org/en/nevibecode/skills/steipete-markdown-converter.md) — skill · 346 installs
- [PDF to Markdown](https://affpapa.org/en/nevibecode/mcp/pdf-to-markdown.md) — MCP server
- [oma-pdf](https://affpapa.org/en/nevibecode/skills/oma-pdf.md) — skill · ★ 1472 repo stars
- [pdf-toolkit-mcp](https://affpapa.org/en/nevibecode/mcp/pdf-toolkit-mcp.md) — MCP server · ★ 12 repo stars
- [PDF OCR Extraction](https://affpapa.org/en/nevibecode/skills/pdf-ocr-extraction.md) — skill · 6000 installs

## Other versions with the same name
- [pdf-to-markdown · pspdfkit-labs](https://affpapa.org/en/nevibecode/skills/pdf-to-markdown.md) — 870 installs
- [pdf-to-markdown · claesbackman](https://affpapa.org/en/nevibecode/skills/claesbackman-pdf-to-markdown.md) — ★ 579 repo stars
- [pdf-to-markdown · aliceisjustplaying](https://affpapa.org/en/nevibecode/skills/aliceisjustplaying-pdf-to-markdown.md) — 14 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
