document-processor

document-processor

A Claude Code skill that ingests business documents — .pptx, .pdf, .xlsx, .docx — into faithful Markdown for a RAG knowledge base or human review.

It is VLM-first (Vision-Language Model), not OCR. Plain text extraction looks like it works but silently drops charts, stacked/racing bars, merged-cell "dashboard" spreadsheets, and mixed-language layout. This skill extracts semantic structure — charts → JSON/Markdown, tables → HTML, verbatim text, [UNCLEAR: …] on doubt — and only routes genuinely-visual pages to the VLM, keeping text-dominant pages on a cheap, exact native path.

It also ships a built-in faithfulness self-check: an independent judge model reads the original page image and the produced Markdown and grades fidelity (a different model from the ingester = an honest cross-check). This is the procedure that validated the method 10/10 on real documents (see skills/document-processor/references/validation.md).

Install

As a Claude Code plugin:

/plugin marketplace add hungson175/document-processor-skill
/plugin install document-processor@document-processor-skill

Or copy the skill manually:

git clone https://github.com/hungson175/document-processor-skill.git
cp -r document-processor-skill/skills/document-processor ~/.claude/skills/

Requirements

• Python (run the scripts with uv or any venv with langchain-openai, python-pptx, python-dotenv, httpx, pypdfium2).
• LibreOffice (soffice) — renders .pptx/.xlsx/.docx pages.
• Poppler (pdftotext, pdfinfo) — native PDF text + page info.
• OPENROUTER_API_KEY in the environment or ~/dev/.env — the VLM runs via OpenRouter.

macOS headless LibreOffice can hang on Gatekeeper — render non-PDF formats on a Linux host; PDFs are fine anywhere.

Use

# convert one file to faithful markdown
python skills/document-processor/scripts/ingest.py --in deck.pptx --out deck.md

Model tiers (DOC_VLM_MODEL):

• medium (default) = qwen/qwen3-vl-32b-instruct — fast, cheap, faithful on charts/tables/text.
• flagship = qwen/qwen3-vl-235b-a22b-instruct — escalate only for dense same-shape cluster diagrams (honeycombs, packed icon grids) the medium model under-enumerates.
• small = qwen/qwen3-vl-8b-instruct.

DOC_VLM_MODEL=flagship python skills/document-processor/scripts/ingest.py --in dense_diagrams.pdf --out out.md

Verify faithfulness (recommended): render → prepare_judge.py → independent judge (references/faithfulness_judge.md) → judge_summary.py --dir. Don't trust the VLM ingester blindly — the whole point of this skill is that it self-verifies with a different model. See skills/document-processor/SKILL.md and references/method_and_gotchas.md for the full method and gotchas.

MIT licensed.