{"id":"21a6d746-122e-4eaa-8f25-9c30b48f9ad0","slug":"doc-eye","kind":"skill","name":"doc-eye","summary":"Claude Code skill: vision-LLM audit of rendered .docx/.pptx/.pdf pages. Catches formatting drift, typography mixing, SmartArt overflow, placeholder text, broken cross-refs — what Claude can't see when","owner":"pedroreisper","repoUrl":"https://github.com/pedroreisper/doc-eye","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-05-25T00:28:46.000Z","addedAt":"2026-10-21T13:18:03.844Z","logoUrl":"https://avatars.githubusercontent.com/u/113413436?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","developer-tools"],"tags":["agent-verification","anthropic","claude-code","document-quality","pdf-audit","vision-llm","docx-audit"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T19:54:13.444Z","sample":false,"url":"https://conduits.dev/tools/doc-eye","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# doc-eye\n\n> Claude reads your code well but doesn't *look* at the rendered PDF. This skill makes it look.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## The pain it solves\n\nYou wrote the LaTeX. You ran `pandoc`. You hit \"Save as PDF\". The source is right. The PDF has SmartArt clipping off the page, a heading orphaned on page 7, and `Lorem ipsum` still on page 3 because the template variable never got filled in.\n\nClaude can read your `.tex` source. Claude cannot *see* the rendered page. So Claude says \"looks good\" while the PDF looks broken.\n\n**doc-eye** closes that gap. It renders every page of a Word, PowerPoint, or PDF document, feeds each page to Claude's vision model with a structured rubric, and emits a per-page report of formatting, typography, colour, content, layout, and visual-coherence defects.\n\nIt catches what a meticulous human reviewer would catch in a 5-second skim per page — except across 50 pages, in 30 seconds, for 10 cents.\n\n## What it catches\n\n- **FORMATTING** — margins, indents, alignment, line spacing, broken page breaks, missing/duplicate headers\n- **TYPOGRAPHY** — font mixing, inconsistent sizes, orphan/widow lines, hyphenation\n- **COLOUR** — accidental coloured runs, low-contrast text, palette drift\n- **CONTENT** — typos, broken cross-references, leftover `TODO` / `Lorem ipsum` placeholders\n- **LAYOUT** — SmartArt overflow, blank pages, tables overflowing margins, disconnected captions\n- **VISUAL_COHERENCE** — mixed numbering schemes, inconsistent heading styles, footnote/anchor mismatches\n\nIt does NOT:\n- Review code or source — that's `/code-review`\n- Check clinical / scientific correctness — that's `scientific-manuscript-reviewer`\n- OCR scanned PDFs (it can still audit layout on them, but won't proofread the scanned text)\n- Propose fixes — reports only; you decide what to do\n\n## Install\n\n```bash\ngit clone https://github.com/pedroreisper/doc-eye\ncd doc-eye\nless install.sh         # 80 lines, no obfuscation\nbash install.sh\n```\n\nOne-liner if you trust the source:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/pedroreisper/doc-eye/main/install.sh | bash\n```\n\nSet your API key (the skill calls the Anthropic API directly):\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\nVerify:\n\n```bash\nbash ~/.claude/skills/doc-eye/scripts/doctor.sh\n```\n\nProject-scoped (team-shared via your repo):\n\n```bash\nbash install.sh --project\n```\n\n## Requirements\n\n- Python 3.10+\n- `pymupdf` and `anthropic` Python packages (auto-installed)\n- `soffice` (LibreOffice) for `.docx`/`.pptx` rendering: `brew install --cask libreoffice` on macOS, `apt install libreoffice` on Debian/Ubuntu\n- `ANTHROPIC_API_KEY` env var\n- macOS or Linux\n\nThe `doctor.sh` self-diagnostic confirms each of these.\n\n## Usage\n\n```bash\n# basic\nbash scripts/audit.sh path/to/document.pdf\nbash scripts/audit.sh path/to/manual.docx\n\n# use Opus instead of default Haiku (more expensive, better for nuance)\nbash scripts/audit.sh manual.docx --opus\n\n# audit only a subset of pages\nbash scripts/audit.sh long.pdf --max-pages 10\nbash scripts/audit.sh long.pdf --sample              # first 10 + last 5 + every 5th in between\n\n# restrict to specific defect categories\nbash scripts/audit.sh manual.docx --only LAYOUT,TYPOGRAPHY\n\n# JSON output (for piping into other tools)\nbash scripts/audit.sh manual.docx --format json | jq '.summary_counts'\n\n# keep the rendered PNGs for inspection\nbash scripts/audit.sh manual.docx --keep-renders\n```\n\nThe audit writes `.doc-eye/<basename>/audit-report.json` next to your cwd.\n\n## Cost\n\n| Model | Per page | 50-page doc | Best for |\n|---|---|---|---|\n| `claude-haiku-4-5` (default) | ~$0.006 | ~$0.30 | Typography, layout, typos |\n| `claude-sonnet-4-6` | ~$0.018 | ~$0.90 | + nuanced visual coherence |\n| `claude-opus-4-7` (`--opus`) | ~$0.029 | ~$1.45 | + argument-level visual analysis |\n\nHaiku is usually enough. Reserve Opus for documents where the cost of a missed defect is high (regulatory submissions, journal manuscripts).\n\n`audit.sh` prints an estimated cost before the audit phase. Estimates over $1 require either `DOC_EYE_NO_CONFIRM=1` or an interactive `y` confirmation — protects against accidental `--opus` on huge docs.\n\nA free placeholder pre-pass (PyMuPDF text extraction, no API cost) runs before the vision phase and catches the cheapest, highest-frequency defect class: leftover `TODO`, `CITATION`, `Lorem ipsum`, `{{template_var}}`, `[insert]`, `FALAR DE`, `SINTETIZAR`, etc. Calibrated against real failure patterns.\n\n## Example output\n\n```\nDOC-EYE — visual audit report\n────────────────────────────────────────────────────────────\nSource:        exports/Manual_NC_v4.docx\nModel:         claude-haiku-4-5\nPages:         42 audited / 42 rendered\nFindings:      ❌ 3 critical   ⚠️  11 warning   • 4 info\nToken usage:   201840 in / 4218 out\n\nDOCUMENT-LEVEL FINDINGS (2)\n────────────────────────────────────────────────────────────\n  ❌ [LAYOUT] pp. 7, 12, 19\n      Diagram box text clips at the right edge of the page (consistent SmartArt overflow).\n      location: top-right quadrant\n\n  ⚠️  [TYPOGRAPHY] pp. 3, 5, 11, 14, 22, 30 (6 occurrences)\n      Body text mixes Calibri 11pt with Liberation Serif 11pt across paragraphs.\n\nPER-PAGE FINDINGS (5)\n────────────────────────────────────────────────────────────\n  Page 8:\n    ❌ [CONTENT] Placeholder text \"TODO: insert reference\" left in body.\n        text: \"TODO: insert reference here\"\n  Page 23:\n    ⚠️  [TYPOGRAPHY] Widow line: last line of paragraph alone at bottom of page.\n        text: \"...portanto a conclusão é\"\n  ...\n\n────────────────────────────────────────────────────────────\nVERDICT: FINDINGS_PRESENT\n```\n\n## Integration with did-it-actually\n\nIf you use [`did-it-actually`](https://github.com/pedroreisper/did-it-actually) for request-fidelity audits, the result of a doc-eye audit can be a `must_review` criterion in your contract — see [`references/did-it-actually-bridge.md`](references/did-it-actually-bridge.md).\n\n## Honest limits\n\n- **SmartArt fidelity** — LibreOffice headless is not byte-identical to Word for SmartArt. If your doc has lots of SmartArt, prefer to export the PDF from Word directly (File → Save As → PDF) and feed that PDF.\n- **Not OCR-grade** — Claude vision reads text from images well but isn't a substitute for spell-check on long body text. Use a text-based spell-checker alongside.\n- **One page at a time** — no facing-page-spread awareness in v1.\n- **Stateless across pages** — each page is audited independently. Multi-page patterns are caught by post-hoc fingerprint deduplication, not by passing context between calls.\n\nSee [`references/edge-cases.md`](references/edge-cases.md) for the full taxonomy.\n\n## Layout\n\n```\ndoc-eye/\n├── SKILL.md                              # entry point\n├── README.md\n├── LICENSE\n├── install.sh\n├── references/\n│   ├── audit-categories.md               # full defect taxonomy\n│   ├── vision-prompt-template.md         # per-page prompt + tool schema\n│   ├── output-schema.json                # JSON Schema for audit-report.json\n│   ├── edge-cases.md                     # encrypted PDFs, scans, RTL, monorepos\n│   └── did-it-actually-bridge.md         # composability with did-it-actually\n└── scripts/\n    ├── audit.sh                          # main driver\n    ├── render.py                         # DOCX/PPTX → PDF → PNG via PyMuPDF\n    ├── vision_audit.py                   # per-page vision calls (forced tool use)\n    ├── aggregate.py                      # dedup + scoring → audit-report.json\n    ├── report.py                         # JSON → prose\n    └── doctor.sh                         # self-diagnostic\n```\n\n## Contributing\n\nTwo things especially valuable:\n\n1. **Fixtures** — add a `.docx`, `.pptx` or `.pdf` with a known defect to `examples/` plus an `expected.md` finding note. See [`examples/README.md`](examples/README.md) for the layout. Helps regression-test prompt changes.\n2. **New categories or sub-categories** — propose via issue. Edits to the category set are a breaking change to the report schema (bump version).\n\n## License\n\n[MIT](LICENSE).\n\n## Acknowledgments\n\nDesigned via parallel-think-tank simulation (research + architecture + technical feasibility) following the same methodology as [`did-it-actually`](https://github.com/pedroreisper/did-it-actually). The unifying insight across both skills: **Claude can't see what it's producing without an explicit perceptual loop**.\n"}