Documents
oma-pdf
Convert PDF files to Markdown using opendataloader-pdf. Extracts text, tables, headings, lists, and images with correct reading order. Use for PDF parsing, PDF to Markdown conversion, document extraction, and AI-ready data preparation.
first-fluke · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add first-fluke/oh-my-agent --skill oma-pdfAbout this skill
name: oma-pdf description: > Convert PDF files to Markdown using opendataloader-pdf. Extracts text, tables, headings, lists, and images with correct reading order. Use for PDF parsing, PDF to Markdown conversion, document extraction, and AI-ready data preparation.
PDF Skill - PDF to Markdown Conversion
Scheduling
Goal
Convert PDF files into structured Markdown or another requested extraction format while preserving readable document structure for LLM context, RAG, or downstream review.
Intent signature
- User asks to convert, parse, read, extract, or transform a PDF.
- User needs PDF text, headings, lists, tables, or images prepared for AI consumption.
- User mentions "PDF to markdown", "parse PDF", "read this PDF", or equivalent wording.
When to use
- Converting PDF documents to Markdown for LLM context or RAG
- Extracting structured content such as tables, headings, lists, images, footnotes, or hyperlinks
- Preparing PDF data for AI consumption
- Checking whether a PDF has a text layer before choosing OCR
When NOT to use
- Generating or creating PDFs -> use document-generation tools
- Editing existing PDFs -> out of scope
- Reading an already-text file -> use direct file reading
- Processing HWP, HWPX, DOCX, XLSX, or slide decks -> use the matching document skill
Expected inputs
input_path: PDF file or folder pathoutput_dir: optional target directoryformat: optional output format, defaultmarkdownocr_languages: optional OCR language list for scanned or image-based PDFsextraction_options: optional flags for tagged structure, image extraction, or hybrid conversion
Expected outputs
- Markdown, text, JSON, HTML, or combined extraction output
- Normalized Markdown when Markdown is produced
- A short report with output path, page count, and conversion issues
Dependencies
uvx opendataloader-pdffor standard conversionuvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybridfor OCR or hybrid conversion (the hybrid server is a console script of the[hybrid]extra, not a standalone package)uvx mdformatfor Markdown normalization- Local filesystem access to input and output paths
- Optional OCR runtime via the hybrid server
Control-flow features
- Branches on text-layer quality, tagged PDF availability, scan/OCR needs, and user-requested output format
- Calls external CLI tools through
uvx - Reads local files and writes local extraction outputs
- Uses a hybrid server only when OCR or complex extraction needs justify it
Structural Flow
Entry
- Confirm that the input path exists and is a PDF file, PDF folder, or supported batch input.
- Check file size and warn when the input is large enough to risk slow conversion or memory pressure.
- Resolve
output_dirand the expected output filename.
Scenes
- PREPARE: Validate the input path, output target, and requested extraction options.
- ACQUIRE: Assess whether the PDF has a readable text layer by extracting a text preview.
- ACT: Convert using standard mode, tagged-structure mode, or hybrid OCR mode.
- VERIFY: Run
mdformatfor Markdown output and inspect the result for readable structure. - FINALIZE: Report output path, page count, format, and any extraction quality issues.
Transitions
- If the preview text is readable, use standard conversion.
- If the PDF is tagged and standard output is garbled, retry with
--use-struct-tree. - If tables are missing or broken, retry with
--table-method clusteror--markdown-with-htmlbefore escalating to hybrid mode. - If the PDF is scanned or image-based, start or reuse the hybrid OCR server and convert with hybrid mode.
- If conversion fails because the PDF is encrypted, stop and ask for the password or an unlocked copy.
- If conversion hits memory or size limits, process smaller page ranges into distinct output directories (or append
--to-stdout) so repeated runs do not overwrite the same basename.
Failure and recovery
| Failure | Recovery |
|---|---|
uvx unavailable | Ask user to install uv before conversion |
opendataloader-pdf-hybrid not found | Invoke via uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid; the bare package name does not exist on PyPI |
| Password-protected PDF | Ask for password or unlocked PDF |
| Garbled output | Retry with tagged structure or hybrid mode |
| Missing tables | Retry with --table-method cluster or --markdown-with-html first; hybrid mode for scanned tables |
| OCR language mismatch | Retry with explicit OCR languages, for example ko,en |
| Large file or memory pressure | Split into page ranges using distinct output directories or --to-stdout; never reuse one output directory for the same basename |
Exit
- Success: output file exists, Markdown is formatted when applicable, and extracted structure is readable.
- Partial success: output exists but quality issues are reported explicitly.
- Failure: no reliable output is produced and the blocking cause is reported.
Logical Operations
Actions
| Action | SSL primitive | Evidence |
|---|---|---|
| Validate path and options | VALIDATE | Input preflight in execution protocol |
| Probe text layer | READ | Text preview extraction |
| Choose conversion strategy | SELECT | Standard, tagged, or hybrid mode decision |
| Run converter | CALL_TOOL | uvx opendataloader-pdf |
| Start OCR server | CALL_TOOL | uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid |
| Write output artifact | WRITE | Markdown, text, JSON, or HTML output |
| Normalize Markdown | CALL_TOOL | uvx mdformat |
| Inspect extraction quality | VALIDATE | Structure/readability verification |
| Report result | NOTIFY | Final user-facing summary |
Tools and instruments
opendataloader-pdf: primary PDF extraction CLIopendataloader-pdf-hybrid: hybrid OCR and complex extractio