skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
first-fluke/oh-my-agent73 installs

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-pdf
view source ↗

Is 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 path
  • output_dir: optional target directory
  • format: optional output format, default markdown
  • ocr_languages: optional OCR language list for scanned or image-based PDFs
  • extraction_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-pdf for standard conversion
  • uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid for OCR or hybrid conversion (the hybrid server is a console script of the [hybrid] extra, not a standalone package)
  • uvx mdformat for Markdown normalization
  • Local filesystem access to input and output paths
  • Optional OCR runtime via the hybrid server
  • Optional preflight commands when available: file, wc, or pdfinfo

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 cluster or --markdown-with-html before 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-selection per references/_shared/runtime/route-selection.md (mode, and the probe or output defect that required it).

Failure and recovery

FailureRecovery
uvx unavailableAsk user to install uv before conversion
opendataloader-pdf-hybrid not foundInvoke via uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid; the bare package name does not exist on PyPI
Password-protected PDFAsk for password or unlocked PDF
Garbled outputRetry with tagged structure or hybrid mode
Missing tablesRetry with --table-method cluster or --markdown-with-html first; hybrid mode for scanned tables
OCR language mismatchRetry with explicit OCR languages, for example ko,en
Large file or memory pressureSplit 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

  1. 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_dir and the expected output filename. Defaults come from the pdf: section of .agents/oma-config.yaml, falling back to config/pdf-config.yaml for unset keys; explicit user options override both, and output.overwrite: false requires 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.
  2. 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)
    
  3. Convert in the mode the preview and Transitions select (standard, tagged-structure, or hybrid OCR). Standard conversion:
    uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
    
    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 --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}"
    
  4. For Markdown output, normalize it and inspect the result for readable structure:
    uvx mdformat "{output_path}"
    
  5. 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

  1. Do not invent missing content when extraction is incomplete.
  2. Always report garbled text, missing tables, OCR uncertainty, or partial extraction.
  3. Prefer standard conversion first when the text layer is readable.
  4. Use OCR only when the PDF is scanned, image-based, or standard extraction quality is insufficient.
  5. Keep detailed command sequences in resources/execution-protocol.md rather than duplicating every variant here.

References

  • Execution protocol: resources/execution-protocol.md
  • Configuration: read the pdf: section of .agents/oma-config.yaml first, then fall back to config/pdf-config.yaml for any key it does not set. User overrides belong in .agents/oma-config.yaml, since oma update overwrites the skill config.
  • Context loading: references/_shared/core/context-loading.md
  • Quality principles: references/_shared/core/quality-principles.md

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>