# PDF To Markdown

Split a PDF into chunks and convert it to readable markdown text.

- Repository: https://github.com/claesbackman/AI-research-feedback (523 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add claesbackman/AI-research-feedback --skill pdf-to-markdown -g -a claude-code -y`
Codex: `npx skills add claesbackman/AI-research-feedback --skill pdf-to-markdown -g -a codex -y`
Cursor: `npx skills add claesbackman/AI-research-feedback --skill pdf-to-markdown -g -a cursor -y`
Gemini CLI: `npx skills add claesbackman/AI-research-feedback --skill pdf-to-markdown -g -a gemini-cli -y`

## Description

Split a PDF into chunks and convert it to readable markdown text. Use when the user wants to read, extract, or convert a PDF document.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# PDF Split & Convert

Convert a PDF file to readable markdown text. Handles large PDFs efficiently.

## Input

- `$ARGUMENTS[0]`, Path to the PDF file (required)

## Choose the method first

Before reading anything, check whether `pdftotext` (part of poppler) is available:

```bash
which pdftotext
```

- **If available** → use the **pdftotext path** below. It is 10, 100× faster than the Read tool, uses no model context for the text content, and doesn't suffer from stream idle timeouts. **Always prefer this for PDFs longer than ~30 pages.**
- **If not available** → fall back to the **Read-tool path**. Warn the user that large PDFs (>40 pages) may hit stream idle timeouts when run in subagents (~12 min cap). Prefer running in the main conversation for large files.

## Resolve the path and get page count

1. If the path is relative, resolve it relative to the current working directory.
2. Run `mdls -name kMDItemNumberOfPages "<pdf_path>"` to get the total page count. If `mdls` is unavailable or returns `(null)`, use `pdftotext` or Read to probe.

## Method A, pdftotext (preferred)

Extract the full PDF to text in one shot, then trim at references/appendix and add page markers. `pdftotext` emits a form-feed character (`\f`) at every page break, use that for pagination.

Reference implementation (bash + awk):

```bash
PDF="$1"
OUT="${PDF%.pdf}.md"
TITLE=$(basename "${PDF%.pdf}")
TMPTXT=$(mktemp)

pdftotext -layout "$PDF" "$TMPTXT"

awk -v title="$TITLE" '
BEGIN {
    print "# " title
    print ""
    page = 1
    printf "---\n## Pages %d-%d\n---\n", page, page+19
    next_marker = page + 20
}
{
    # Convert form-feed page breaks to newlines and count pages
    n = gsub(/\f/, "\n")
    if (n > 0) {
        page += n
        if (page >= next_marker) {
            printf "\n---\n## Pages %d-%d\n---\n", next_marker, next_marker+19
            next_marker += 20
        }
    }

The rest: https://github.com/claesbackman/AI-research-feedback/blob/HEAD/Skills/pdf-to-markdown/SKILL.md