---
name: work-with-pdfs
title: Read, create and review PDF documents
description: Read, create, edit and verify PDFs through bounded text extraction, structured conversion and rendered-page evidence.
---

# Work with PDFs

Use this skill when a PDF must be read, reviewed, compared, or used as evidence.
Do not treat extracted text as evidence about layout, figures, equations, scans,
or handwriting.

## Native PDF reading

If the `view_pdf` tool is available, the connected model can read PDFs
natively. Call it with the workspace path to attach the document to the next
model step; both its text and page images reach the model directly, with no
conversion step. For a long document, read it a page range at a time (the
`pages` argument, e.g. `"1-50"`) rather than the whole file in one call — a
whole-document call past the configured page ceiling is refused and reports
the document's page count so the range can be chosen. Prefer `view_pdf` over
the conversion-and-render workflow below whenever it is available.

If `view_pdf` is absent, the active model has no evidenced native PDF
capability. Use the conversion + rendered-page + `view_image` workflow
described in the rest of this skill instead.

If a provider refuses a native PDF attachment, its successful preparation does
not mean the model read it. Follow the recovery note, keep the source path and
requested page range, and use bounded extraction and rendered-page inspection
below. Do not repeat the same native attachment or abandon unrelated work.

## Resolve evidence, not accessibility

Every PDF supplied to the turn has a usable path on the connected agent:

- A workspace `@` reference supplies its verified workspace path and revision.
- An uploaded attachment supplies an independent working copy beneath the
  active workspace's `.clio/inputs/` directory. Its immutable custody original
  remains available to CLIO's conversion pipeline.

Use the supplied workspace path for shell, Docling, Poppler, OCR, Python, and
other file-based tools. Never use or modify a private custody path. Do not ask
whether the PDF is accessible or ask the user to upload it again merely to
obtain a filesystem path.

For an uploaded attachment, inspect its resource record when structured
conversion could help. If conversion is queued or processing, call
`workspace_resource_wait` once with the supplied task id. When conversion is
complete, use `workspace_resource_structure`, `workspace_resource_search`, and
bounded `workspace_resource_read` calls for searchable text, tables, and
document structure.

For either source, use the workspace path and local workflow when no usable
conversion exists or when the question depends on geometry, layout, figures,
equations, scans, handwriting, or other visual evidence.

## Local conversion and page rendering

Prefer the prepared document stack for local work. Call
`prepare_document_runtime` for the execution host's verified commands, packages,
fonts and output directory. It uses locked dependencies outside Clio's own Python
environment. Keep source files and requested outputs inside the active workspace;
use its returned `.tmp/` scratch directory for intermediate scripts and data.
Use `prepare_document(path, action="inspect", pages="1-10")` for
bounded embedded text, and `prepare_document(path, action="render", pages="1-5")`
for bounded page PNGs. Read the returned manifest and content derivative. Long
documents require an explicit range; scans with empty embedded text require
visual inspection or OCR. Rendering alone does not read an image for the model.

Execute authoring and editing scripts with the returned `python_argv` (uv selects
the prepared Python). For PDF creation use the prepared ReportLab environment; for page merging,
splitting or rotation use `pypdf` or PyMuPDF. Preserve the source and reopen the
output to check page count and requested content, then render and visually inspect
material pages. Designate the requested final file with `create_artifact`. Do not
claim form, signature or accessibility preservation from a successful rewrite.
Name the published artifact in the final response; Clio shows its artifact card.
Use the runtime's workspace-file or registered artifact/resource citation format
for clickable references. Do not use browser-local `file://` links.

When Docling's richer structural conversion is needed and the attachment has no
usable structured derivative, the following existing helper remains available.
Docling is a separate optional dependency and may download model assets; it is
not advertised by the prepared stack unless installed there.

Resolve this skill's directory as `SKILL_ROOT`. Use the returned absolute `uv`
and `python` paths as `UV` and `PYTHON`, then run:

```text
"UV" run --no-project --python "PYTHON" --with "docling>=2.0" --with "pymupdf>=1.24" python "SKILL_ROOT/scripts/prepare_pdf.py" "INPUT.pdf" "OUTPUT_DIR"
```

This uses uv's shared cached environment. Do not create a `.venv` inside the
installed skill or plugin directory.

For a drawing, scan, or other explicitly visual question, skip the slower text
conversion and render pages immediately:

```text
"UV" run --no-project --python "PYTHON" python "SKILL_ROOT/scripts/prepare_pdf.py" "INPUT.pdf" "OUTPUT_DIR" --visual-only
```

The helper performs two independent operations:

- Docling exports Markdown plus its structured JSON document.
- PyMuPDF renders bounded page PNGs and writes a manifest recording every
  output and any partial failure.

Use `--max-pages`, `--max-bytes`, and `--dpi` to keep large documents bounded.
The default limits are intentionally conservative. Read `manifest.json` before
claiming either conversion succeeded.

Prefer the Markdown/JSON outputs for text, headings, tables, and document
structure. Search or read only the relevant sections instead of putting an
entire large conversion into the model context.

## Visual evidence boundary

An image-capable CLIO model has a `view_image` tool. Prefer the Markdown/JSON
conversion when it answers the question faithfully. When converted text is
missing or insufficient—for example, scans, plots, equations, handwriting, or
layout-dependent questions—render the relevant PDF pages with the helper and
call `view_image` on each relevant page PNG. That tool attaches the verified
workspace image pixels to the next model step; a successful shell render alone
does not count as visual inspection.

If `view_image` is absent, the active model has no evidenced image capability.
Use only available text/OCR/structured evidence and state the limitation. Never
infer visual facts from filenames, dimensions, metadata, or successful
rendering alone, and do not ask the user to reattach pages merely to compensate
for a missing agent-side image inspection path.

For scanned or image-only PDFs, treat a weak or empty text conversion as a
signal to use the rendered-page path. For mixed PDFs, combine bounded textual
evidence with visual inspection of only the pages whose layout or figures
matter.

## Engineering drawings and diagrams

Questions about dimensions, feature counts, geometry, callout-to-feature
associations, or relative size are always layout-dependent. Render the relevant
page and call `view_image` before answering, even when text extraction contains
the requested number. Extracted labels without their positions do not show
which feature they dimension. A completed render is not evidence until
`view_image` has returned the page pixels to the model.

Do not infer drawing units from decimal style, likely engineering convention,
software metadata, filename, or the magnitude of dimensions. Report units only
when a visible note, title-block field, or explicit callout states them. If no
unit is specified, say so plainly and keep numerical dimensions unitless.

For large-format drawings or small, dense callouts, inspect the full page first,
then create and inspect high-resolution crops of every relevant view or callout
region. Do not claim a complete list of dimensions or radii from a page preview
whose labels are not all legible.

## Evidence and completion

- Cite page numbers and section/table/figure labels when the source exposes
  them.
- Separate source text, observed visual content, OCR output, and inference.
- Do not call a PDF fully reviewed until the relevant textual content and every
  visually material page have been checked through a representation the model
  actually received.
- Preserve the original PDF. Write derivatives to a separate output directory.