Skip to content

oliverv/caro / .agents/skills/oma-pdf

oma-pdf

Flagged

Extract PDF text, headings, tables, and images into Markdown using opendataloader-pdf. Use for PDF parsing, not PDF layout creation.

FileKindSize
SKILL.mdskill md8.7 KB
config/pdf-config.yamlconfig975 B
resources/execution-protocol.mdmarkdown5.4 KB

resources/execution-protocol.md

View on GitHub
# PDF Conversion - Execution Protocol

## Step 0: Validate Input

1. Read `config/pdf-config.yaml` for defaults (image output, struct tree, OCR languages, hybrid port, overwrite behavior); explicit user options override config values
2. Confirm the PDF file path exists
3. Check file size (`wc -c` or `ls -lh`); warn if >100MB
4. Determine output location:
   - If user specified output path → use it
   - If not specified → use the same directory as the input PDF
5. Determine output filename: `{input_name}.md` (same base name, `.md` extension)
6. If the output file already exists and config `output.overwrite` is `false`, confirm with the user before overwriting

## Step 1: Assess PDF Type

Quick check to determine conversion strategy — probe only the first pages, no temp files:

```bash
# Check if PDF has text layer (vs scanned image).
# -q is required: without it, Java INFO logs mix into stdout.
uvx opendataloader-pdf input.pdf -f text --pages 1-3 --to-stdout -q
```

- If output contains readable text → standard mode
- If output is empty or garbled → needs OCR (hybrid mode)

## Step 2: Convert

### Standard conversion
```bash
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
```

### If Tagged PDF (structured documents, official reports)
```bash
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --use-struct-tree
```

### If tables are missing or broken (try these BEFORE hybrid)

Hybrid mode downloads a large OCR stack; the core CLI has cheaper retries:

```bash
# Borderless tables: cluster-based detection
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --table-method cluster

# Complex tables (row/col spans): allow HTML tables inside Markdown
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --markdown-with-html
```

Escalate to hybrid mode only if tables are still wrong (typically scanned tables).

### If the PDF is large (memory pressure or slow conversion)

```bash
# Convert each page range into a distinct directory, then concatenate the files
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}/p1-50" --pages "1-50"
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}/p51-100" --pages "51-100"

# Or append each range from stdout into one combined file
uvx opendataloader-pdf "{input_path}" --format markdown --pages "1-50" --to-stdout >> "{output_path}"

# Or parallelize per-page processing (experimental)
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --threads 4
```

### Optional flags on request

- `--sanitize` — mask PII (emails, phone numbers, IPs, credit cards, URLs) for AI-ready data prep
- `--detect-strikethrough` — mark struck-through text with `~~` (experimental)
- `--markdown-page-separator "%page-number%"` — insert page markers between pages
- Hybrid server extras: `--enrich-formula` (LaTeX formulas), `--enrich-picture-description` (AI chart/image descriptions). Both require client-side `--hybrid-mode full`; the default `auto` mode may keep pages on the local path and skip enrichment.

### If scanned/image-based PDF (requires hybrid server)
```bash
# Start hybrid server (if not already running).
# The server is a console script of the [hybrid] extra — bare `uvx opendataloader-pdf-hybrid` fails (no such PyPI package).
# First run downloads a large OCR stack (torch, easyocr, docling); warn the user before starting.
uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"

# Convert
uvx opendataloader-pdf --hybrid docling-fast --hybrid-mode full "{input_path}" --format markdown --output-dir "{output_dir}"
```

## Step 3: Lint & Format

Run `mdformat` to normalize the converted Markdown:

```bash
uvx mdformat "{output_path}"
```

This auto-fixes:
- Inconsistent heading style
- Missing blank lines around blocks
- Trailing whitespace
- Unordered list marker normalization

## Step 4: Verify

1. Read the generated Markdown file
2. Verify structure:
   - Headings preserved (`#`, `##`, etc.)
   - Tables rendered correctly (pipe syntax)
   - Lists maintained (bullets, numbered)
   - No garbled or missing sections
3. If output directory is temporary, move the file to the target location
4. If the user needs the content in the conversation, read and present it

## Step 5: Report

Tell the user:
- Output file path
- Page count processed — read it from the converter log line `Processing N pages`, or `pdfinfo` when available
- Any issues encountered (missing tables, OCR quality, etc.)
- Suggest hybrid mode if standard conversion had quality issues

## Error Recovery

| Error | Recovery |
|-------|----------|
| `uvx` not found | Ask user to install `uv`: `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| PDF password protected | Ask user for the password, then retry with `-p "{password}"` (`opendataloader-pdf --password`) |
| Missing or broken tables | Retry with `--table-method cluster` or `--markdown-with-html` first; hybrid mode only for scanned tables |
| Hybrid server not running | Guide user to start it, or fall back to standard mode with quality warning |
| Out of memory on large PDF | Process each `--pages` range into a distinct output directory (or append `--to-stdout`) before concatenating; reusing one directory overwrites the same basename |
| Network error (hybrid mode) | Check server port, retry, or fall back to standard mode |
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall