document-converter

Purpose

Convert documents between formats and perform PDF operations using local, free, offline tools. No API key, no cost, no internet required. Supports Office formats, PDF manipulation, image-to-PDF, and OCR using LibreOffice, ghostscript, pdftk, tesseract, and imagemagick.

When to Use

Converting Office documents (DOCX, PPTX, XLSX, ODP, ODT) to PDF or HTML
Converting PDF pages to images (PNG, JPG, TIFF) or images to PDF
PDF operations: merge multiple PDFs, split by page range, rotate pages, encrypt or decrypt
OCR: extract searchable text from scanned PDFs or image files
Any document format conversion that does not involve video or audio

Do NOT use for:

Video or audio format conversion (use a dedicated media skill)
Converting code between programming languages
Simple markdown → HTML (use pandoc directly)
Structured text extraction from PDFs (use
```
docling-converter
```
instead)

Step 0: Discovery — Detect Available Tools

Before any conversion, detect which tools are installed and identify the operating system:

bash

# Detect OS
uname -s   # Darwin = macOS, Linux = Linux; on Windows use 'ver' or check $OS

# Check each tool
libreoffice --version 2>/dev/null || echo "NOT FOUND"
gs --version 2>/dev/null || echo "NOT FOUND"
pdftk --version 2>/dev/null || echo "NOT FOUND"
tesseract --version 2>/dev/null || echo "NOT FOUND"
convert -version 2>/dev/null || echo "NOT FOUND"   # ImageMagick

If a required tool is missing, show the install command for the user's OS before proceeding:

Tool	macOS	Linux (apt)	Windows
LibreOffice	`brew install --cask libreoffice`	`sudo apt install libreoffice`	`winget install TheDocumentFoundation.LibreOffice`
Ghostscript	`brew install ghostscript`	`sudo apt install ghostscript`	`winget install ArtifexSoftware.GhostScript`
pdftk	`brew install pdftk-java`	`sudo apt install pdftk`	`winget install PDFTechnologies.PDFtk`
Tesseract	`brew install tesseract`	`sudo apt install tesseract-ocr`	`winget install UB-Mannheim.TesseractOCR`
ImageMagick	`brew install imagemagick`	`sudo apt install imagemagick`	`winget install ImageMagick.ImageMagick`

If the user is on Windows and Microsoft Office is installed, note that LibreOffice and Office produce equivalent results for DOCX/PPTX/XLSX; Office via COM automation is an advanced alternative.

Workflow

Office Documents → PDF (most common)

Use LibreOffice headless mode. Works for DOCX, PPTX, XLSX, ODP, ODT, and any format LibreOffice opens.

bash

# Convert single file to PDF in the same directory
libreoffice --headless --convert-to pdf "/path/to/file.pptx" --outdir "/path/to/output/"

# Convert to HTML
libreoffice --headless --convert-to html "/path/to/file.docx" --outdir "/path/to/output/"

# Batch: convert all PPTX in a directory
libreoffice --headless --convert-to pdf /path/to/folder/*.pptx --outdir /path/to/output/

Notes:

Output file is placed in
```
--outdir
```
with the same base name and new extension
For batch, run one
```
libreoffice
```
process — do NOT spawn multiple instances in parallel (LibreOffice uses a single user profile lock)
If LibreOffice is open as a GUI app, close it first or use
```
--norestore
```
flag

PDF → Images / Images → PDF

Use ImageMagick for image-PDF interchange:

bash

# PDF pages → PNG (one file per page)
convert -density 150 "/path/to/doc.pdf" "/path/to/output/page_%03d.png"

# PDF pages → JPG with quality control
convert -density 150 "/path/to/doc.pdf" -quality 85 "/path/to/output/page_%03d.jpg"

# Single image → PDF
convert "/path/to/image.png" "/path/to/output/document.pdf"

# Multiple images → single PDF
convert img1.png img2.jpg img3.tiff "/path/to/output/combined.pdf"

Note: On some systems ImageMagick's PDF support requires ghostscript. If conversion fails with a policy error, check

/etc/ImageMagick-*/policy.xml

and ensure PDF is not restricted.

PDF Operations — Merge, Split, Rotate

Prefer

pdftk

when available (simpler syntax). Fall back to

ghostscript

if pdftk is not installed.

Merge PDFs:

bash

# pdftk (preferred)
pdftk file1.pdf file2.pdf file3.pdf cat output merged.pdf

# ghostscript (fallback)
gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -sOutputFile=merged.pdf file1.pdf file2.pdf file3.pdf

Split PDF by page range:

bash

# pdftk — extract pages 1-3 and 5
pdftk input.pdf cat 1-3 5 output extracted.pdf

# ghostscript — extract pages 2 to 5
gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -dFirstPage=2 -dLastPage=5 -sOutputFile=extracted.pdf input.pdf

Rotate pages:

bash

# pdftk — rotate all pages 90° clockwise
pdftk input.pdf rotate 1-endeast output rotated.pdf

# pdftk — rotate specific page (page 3) 180°
pdftk input.pdf rotate 3south output rotated.pdf

Encrypt PDF (add password):

bash

pdftk input.pdf output secured.pdf user_pw "userpass" owner_pw "ownerpass"

Decrypt PDF (remove password):

bash

pdftk secured.pdf input_pw "password" output decrypted.pdf

OCR — Extract Text from Scanned Documents

Use Tesseract. Input must be an image (PNG, JPG, TIFF) or a PDF that ImageMagick can rasterize first.

bash

# OCR a single image → searchable text file
tesseract "/path/to/scan.png" "/path/to/output/result"
# Output: result.txt

# OCR with language specification (Portuguese example)
tesseract "/path/to/scan.png" output -l por

# OCR → searchable PDF (requires tesseract with pdf support)
tesseract "/path/to/scan.png" output -l eng pdf
# Output: output.pdf

# OCR a scanned PDF: rasterize first, then OCR
convert -density 300 "scan.pdf" "scan_page_%03d.tiff"
tesseract "scan_page_000.tiff" output -l eng pdf

For multi-page scanned PDFs:

bash

# Rasterize all pages
convert -density 300 "scan.pdf" "page_%03d.tiff"

# OCR each page and merge results
for f in page_*.tiff; do
  tesseract "$f" "${f%.tiff}" -l eng pdf
done
pdftk page_*.pdf cat output final_ocr.pdf

Tool Routing Decision Table

Task	Primary tool	Fallback
Office → PDF	LibreOffice	None (LibreOffice is the standard)
Office → HTML	LibreOffice	None
PDF → images	ImageMagick	ghostscript ( `gs -sDEVICE=png16m` )
Images → PDF	ImageMagick	ghostscript
Merge PDFs	pdftk	ghostscript
Split PDF	pdftk	ghostscript
Rotate PDF	pdftk	ghostscript
Encrypt PDF	pdftk	None
Decrypt PDF	pdftk	None
OCR	tesseract	None

Comparison: When to Use document-converter vs Alternatives

Tool	Best for
`document-converter`	Office → PDF, PDF operations (merge/split/rotate/encrypt), OCR, image ↔ PDF
`docling-converter`	PDF/Office → structured Markdown or JSON; layout-aware content extraction
`pandoc`	Markdown ↔ HTML ↔ LaTeX ↔ DOCX; lightweight lightweight text format conversions
`pptx-translator`	Translating PowerPoint files between languages

Critical Rules

NEVER start a batch LibreOffice conversion with multiple parallel processes — LibreOffice uses a single user-profile lock and parallel instances will crash
ALWAYS run Step 0 Discovery to confirm the required tool is installed before invoking it
ALWAYS suggest the correct install command for the user's OS when a tool is missing
NEVER use cloudconvert, external APIs, or paid services — this skill is fully offline
ALWAYS prefer pdftk over ghostscript for PDF operations when both are available (simpler, safer syntax)
ALWAYS specify output directory explicitly to avoid writing files to unexpected locations

Example Usage

Convert PPTX to PDF:

bash

libreoffice --headless --convert-to pdf presentation.pptx --outdir ./output/

Merge 3 PDFs:

bash

pdftk report.pdf appendix.pdf cover.pdf cat output final.pdf

OCR a scanned image (Portuguese):

bash

tesseract scan.png resultado -l por

PDF pages to PNG images:

bash

convert -density 150 document.pdf page_%03d.png

Encrypt a PDF:

bash

pdftk sensitive.pdf output protected.pdf user_pw "secret123"

document-converter

NPX Install

Tags

SKILL.md Content

document-converter

Purpose

When to Use

Step 0: Discovery — Detect Available Tools

Workflow

Office Documents → PDF (most common)

PDF → Images / Images → PDF

PDF Operations — Merge, Split, Rotate

OCR — Extract Text from Scanned Documents

Tool Routing Decision Table

Comparison: When to Use document-converter vs Alternatives

Critical Rules

Example Usage