К основному содержанию
скилл CX Codex

oma-pdf — скилл для Claude Code: что делает и как установить

Скилл oma-pdf конвертирует PDF-документы в Markdown с сохранением таблиц, заголовков и списков. Запускается при подготовке файлов для RAG и контекста LLM.

MIT ★ 1 472 обновлён 2026-11-12

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma-research@oh-my-agent
Открыть на GitHub

Что делает oma-pdf

Скилл разбирает PDF на структурные элементы через утилиту opendataloader-pdf и форматирует итоговый Markdown инструментом mdformat. Сначала агент проверяет первые страницы на наличие текстового слоя. Если текст читается, запускается стандартная конвертация без тяжёлых библиотек.

Для сканов и изображений скилл поднимает локальный сервер распознавания через opendataloader-pdf-hybrid на порту 5002. Если таблицы ломаются, применяются методы --table-method cluster или HTML-разметка таблиц. Для работы в системе обязательно нужен установленный менеджер пакетов uv, иначе вызовы через uvx завершатся ошибкой.

Какие задачи решает

  • конвертировать PDF в чистый Markdown для контекста нейросети
  • извлечь сложные таблицы с сохранением структуры через кластеризацию
  • распознать текст на отсканированных страницах через гибридный OCR-сервер
  • нормализовать итоговый Markdown с помощью mdformat

Примеры запросов агенту

  • Преобразуй отчёт report.pdf в Markdown и сохрани в папку docs/
  • Разбери скан contract_scan.pdf через OCR и вытащи таблицы
  • Сконвертируй страницы с 1 по 10 из файла handbook.pdf в чистый текст

Как установить oma-pdf

1Через маркетплейс плагинов

/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma-research@oh-my-agent

Команда ставит плагин oma-research целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add first-fluke/oh-my-agent --skill oma-pdf -a claude-code

3Вручную: положить файлы

~/.claude/skills/oma-pdf/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/oma-pdf/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об oma-pdf

Как установить oma-pdf в Claude Code?

Выполните команду npx skills add first-fluke/oh-my-agent --skill oma-pdf -a claude-code в терминале.

Что делает скилл oma-pdf?

Он преобразует PDF в структурированный Markdown, HTML, JSON или простой текст, сохраняя структуру заголовков, списков и таблиц.

Что нужно для распознавания отсканированных PDF?

Для сканов скилл использует гибридный режим и консольный скрипт opendataloader-pdf-hybrid из пакета opendataloader-pdf[hybrid], требующий наличия uv в системе.

Исходный текст

SKILL.md · MIT
---
name: oma-pdf
description: Extract PDF text, headings, tables, and images into Markdown using
  opendataloader-pdf. Use for PDF parsing, not PDF layout creation.
---

# 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 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

### 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
1. Confirm that the input path exists and is a PDF file, PDF folder, or supported batch input.
2. Check file size and warn when the input is large enough to risk slow conversion or memory pressure.
3. Resolve `output_dir` and the expected output filename.

### Scenes
1. **PREPARE**: Validate the input path, output target, and requested extraction options.
2. **ACQUIRE**: Assess whether the PDF has a readable text layer by extracting a text preview.
3. **ACT**: Convert using standard mode, tagged-structure mode, or hybrid OCR mode.
4. **VERIFY**: Run `mdformat` for Markdown output and inspect the result for readable structure.
5. **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 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 `../_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

### 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 CLI
- `opendataloader-pdf-hybrid`: hybrid OCR and complex extraction path
- `mdformat`: Markdown normalization
- Filesystem commands such as `file`, `wc`, or `pdfinfo` may be used for preflight when available

### Canonical command path
```bash
uvx opendataloader-pdf "{input_path}" -f text --pages 1-3 --to-stdout -q   # text-layer probe (no temp files)
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
uvx mdformat "{output_path}"
```

For scanned/image-based PDFs, start OCR first and then convert through hybrid mode:
```bash
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}"
```

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
| Scope | Resource target |
|-------|-----------------|
| `LOCAL_FS` | Input PDFs and generated output files |
| `PROCESS` | `uvx` subprocesses and optional hybrid server |
| `MEMORY` | Extracted previews and validation notes |
| `OTHER` | OCR model/runtime behavior inside hybrid mode |

### Preconditions
- The input PDF path exists and is readable.
- The output location is writable or can be created.
- Required CLIs are available through `uvx`.
- OCR is only attempted when hybrid mode is available or can be started.
- 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.

### Effects and side effects
- Creates or overwrites extraction output depending on configuration and user intent.
- May start a local hybrid OCR server on the configured port.
- May consume significant CPU, memory, or time for large or scanned PDFs.
- Does not intentionally modify the source PDF.

### 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: `../_shared/core/context-loading.md`
- Quality principles: `../_shared/core/quality-principles.md`

© First Fluke · MIT · first-fluke/oh-my-agent

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
pdf-to-markdown PSPDFKit-labs Скилл pdf-to-markdown для Claude Code и Codex. Превращает PDF в структурированный Markdown: заголовки, таблицы, списки и порядок чтения сохраняются. Извлекает текст для анализа или передачи агенту. CX Codex +1 870установок pdf-mcp jztan Даёт агенту доступ к одному PDF или целой папке: гибридный поиск, чтение нужных страниц, таблицы и OCR сканов. CX Codex +1 ★ 174звёзд репо pdf-toolkit-mcp AryanBV MCP-сервер pdf-toolkit-mcp с 22 инструментами для чтения, сборки, шифрования и слияния PDF. Рендерит страницы в изображения, чтобы модель прочитала отсканированный документ без текстового слоя. CX Codex +1 ★ 12звёзд репо PDF OCR Extraction claude-office-skills Скилл PDF OCR Extraction для Claude Code извлекает текст из сканов и PDF с изображениями. Запросите распознавание, поиск по документу или обработку нескольких файлов. CX Codex +1 6 000установок pdf-processing-pro davila7 Скилл pdf-processing-pro для Claude Code обрабатывает PDF: заполняет формы, извлекает таблицы и распознаёт текст. Включается при пакетной обработке документов. CX Codex +1 5 869установок pdf Nous Research Работает с PDF-файлами: создаёт, читает, объединяет, заполняет формы, извлекает текст и таблицы. CX Codex +1 283установок

Из того же набора69

Весь набор →
oma-image Скилл oma-image генерирует изображения через несколько провайдеров сразу — Codex, Pollinations, Gemini — и подхватывает референсы для вариаций по стилю и композиции. CX Codex +1 ★ 1 472звёзд репо oma-architecture Скилл oma-architecture помогает проектировать границы модулей и сервисов, сравнивать альтернативные решения и оформлять архитектурные решения в формате ADR. CX Codex +1 ★ 1 472звёзд репо oma-coordination Скилл oma-coordination помогает вручную координировать работу нескольких специализированных агентов. Он раскладывает задачу по этапам, отслеживает договорённости между командами и доводит работу до QA-проверки. CX Codex +1 ★ 1 472звёзд репо oma-hwp Скилл oma-hwp превращает корейские документы HWP, HWPX и HWPML в Markdown через kordoc. Извлекает текст, таблицы, списки, изображения и сноски. CX Codex +1 ★ 1 472звёзд репо oma-market Скилл oma-market собирает сигналы рынка из сообществ и оформляет их в краткий отчёт о болях клиентов, трендах или конкурентах. CX Codex +1 ★ 1 472звёзд репо oma-video Создаёт видео через CLI OMA video или обрабатывает готовый клип: извлекает кадры, режет паузы, собирает дубляж. CX Codex +1 ★ 1 472звёзд репо oma-skill-creator Скилл oma-skill-creator создаёт, форматирует и проверяет скиллы OMA в стандарте SSL-lite с четырьмя обязательными блоками внутри .agents/skills/. CX Codex +1 ★ 1 472звёзд репо oma-frontend Субагент oma-frontend для фронтенда на React, Next.js и TypeScript с архитектурой FSD-lite, shadcn/ui и design-tokens. Ставь, когда работаешь с UI, компонентами, страницами, стилями и клиентской логикой. CX Codex +1 ★ 1 472звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой