oma-pdf
Extract PDF text, headings, tables, and images into Markdown using opendataloader-pdf. Use for PDF parsing, not PDF layout creation.
How do I install this agent skill?
npx skills add https://github.com/first-fluke/oh-my-agent --skill oma-pdfIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is safe. It uses established tools for PDF parsing and Markdown formatting. It includes standard installation instructions for the uv package manager from its official domain.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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, or HWPML -> use
oma-hwp - Processing DOCX, XLSX, or slide decks -> out of scope
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
- Optional preflight commands when available:
file,wc, orpdfinfo
Structural Flow
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. - When a transition above leaves standard conversion, record the selected mode with subject
pdf.route-selectionperreferences/_shared/runtime/route-selection.md(mode, and the probe or output defect that required it).
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
Canonical command path
- Confirm that the input path exists and is a readable PDF file, PDF folder, or supported batch input, and that the output location is writable or can be created. Resolve
output_dirand the expected output filename. Defaults come from thepdf:section of.agents/oma-config.yaml, falling back toconfig/pdf-config.yamlfor unset keys; explicit user options override both, andoutput.overwrite: falserequires confirmation before replacing an existing output file. Check file size and warn when the input is large enough to risk slow conversion or memory pressure. - Assess whether the PDF has a readable text layer by extracting a text preview:
uvx opendataloader-pdf "{input_path}" -f text --pages 1-3 --to-stdout -q # text-layer probe (no temp files) - Convert in the mode the preview and Transitions select (standard, tagged-structure, or hybrid OCR). Standard conversion:
For scanned/image-based PDFs, start OCR first and then convert through hybrid mode. Attempt OCR only when the hybrid server is available or can be started:uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}" uvx opendataloader-pdf --hybrid docling-fast --hybrid-mode full "{input_path}" --format markdown --output-dir "{output_dir}" - For Markdown output, normalize it and inspect the result for readable structure:
uvx mdformat "{output_path}" - Report the output path, page count, format, and any extraction quality issues.
On-request flags — --sanitize (PII masking), --pages (range extraction), --threads (parallel pages), --detect-strikethrough, hybrid --enrich-formula / --enrich-picture-description — are detailed in resources/execution-protocol.md. The two enrichment flags require client-side --hybrid-mode full.
Resource scope and effects
Reads the input PDFs and does not modify the source PDF. Creates or overwrites extraction output in the output directory, depending on configuration and user intent. Runs uvx subprocesses and, for OCR, may start a local hybrid server on the configured port. Large or scanned PDFs may consume significant CPU, memory, or time.
Guardrails
- Do not invent missing content when extraction is incomplete.
- Always report garbled text, missing tables, OCR uncertainty, or partial extraction.
- Prefer standard conversion first when the text layer is readable.
- Use OCR only when the PDF is scanned, image-based, or standard extraction quality is insufficient.
- Keep detailed command sequences in
resources/execution-protocol.mdrather than duplicating every variant here.
References
- Execution protocol:
resources/execution-protocol.md - Configuration: read the
pdf:section of.agents/oma-config.yamlfirst, then fall back toconfig/pdf-config.yamlfor any key it does not set. User overrides belong in.agents/oma-config.yaml, sinceoma updateoverwrites the skill config. - Context loading:
references/_shared/core/context-loading.md - Quality principles:
references/_shared/core/quality-principles.md
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/first-fluke/oh-my-agent/oma-pdf">View oma-pdf on skillZs</a>