VERBATIM SOURCE
SKILL.md
skill://flora-skills/root/.codex/skills/builtins/pdf/SKILL.md
---
name: "pdf"
description: "Read, create, inspect, render, and verify PDF files where visual layout matters, including fillable AcroForms. Use Poppler rendering plus Python tools such as reportlab, pdfplumber, and pypdf for generation and extraction."
---
# PDF Skill
## When To Use
- Read or review PDF content where layout and visuals matter.
- Create PDFs programmatically with reliable formatting.
- Fill and validate interactive PDF forms.
- Validate final rendering before delivery.
## Tools + Contract Requirements
Immediately before the first create/edit authoring command, run `mark_artifact_operation_started.mjs` successfully exactly once using the command below. Do not run it for read-only work. For edits, replace `create` with `edit`; adjust the expected count and output format to match the requested outputs.
```bash
node container_tools/mark_artifact_operation_started.mjs --operation-kind create --expected-output-count 1 --output-format pdf
```
## Workflow
1. Prefer visual review: render PDF pages to PNGs and inspect them.
- Use `pdftoppm` from the bundled runtime or system Poppler when available.
- If unavailable, install Poppler or ask the user to review the output locally.
2. Use `reportlab` to generate PDFs when creating new documents.
3. Use `pdfplumber` or `pypdf` for text extraction and quick checks; do not rely on text extraction for layout fidelity.
4. After each meaningful update, re-render pages and verify alignment, spacing, and legibility.
## Fill And Validate AcroForms
Visual review alone is not a correctness check for a fillable PDF. A page `/Widget` annotation can render a value from its appearance stream while the canonical `/AcroForm/Fields` tree is missing or contains a stale value.
1. Keep the result interactive by default; set `flatten=True` only when the user explicitly requests a completed, static form. Preserve the source PDF, and do not flatten a signed PDF without an explicit workflow decision.
2. Inspect both representations before filling: enumerate fields from `reader.get_fields()` and `/Widget` annotations from every page's `/Annots`, following `/Parent` and `/Kids`. If a widget and a canonical field have the same name but are distinct objects with no `/Parent` relationship, do not call `reattach_fields()` blindly: it can create a second top-level field with the same name. Report the ambiguity or produce a static result.
3. Recover genuinely orphaned widgets, fill all pages, and write the result with `pypdf`:
```python
from pypdf import PdfReader, PdfWriter
from pypdf.generic import NameObject
reader = PdfReader(input_pdf)
writer = PdfWriter()
writer.clone_document_from_reader(reader)
# Restores widgets that are missing from /AcroForm/Fields.
writer.reattach_fields()
fields = writer.get_fields() or {}
missing = set(expected_values) - set(fields)
if missing:
raise ValueError(f"Form fields not found after repair: {sorted(missing)}")
values_to_write = dict(expected_values)
if flatten:
# Paint every existing value before removing every widget.
values_to_write = {
name: field.get("/V", "/Off" if field.get("/FT") == "/Btn" else "")
for name, field in fields.items()
}
values_to_write.update(expected_values)
writer.update_page_form_field_values(
None, values_to_write, auto_regenerate=False, flatten=flatten
)
if flatten:
# pypdf's flatten=True paints appearances but does not remove widgets.
writer.remove_annotations(subtypes="/Widget")
writer.root_object.pop(NameObject("/AcroForm"), None)
with open(output_pdf, "wb") as stream:
writer.write(stream)
```
4. Reopen the written PDF before delivery. For an interactive result, require every expected field to be present in `get_fields()` with the expected `/V`, enumerate page widgets again, and confirm their effective `/V` (the widget value or inherited `/Parent` value) agrees. Confirm each updated widget has a non-empty `/AP` `/N` appearance and render the final pages to catch stale or clipped appearances. Do not rely on `/NeedAppearances` or a successful PNG render as proof that logical field data was updated.
5. For a flattened result, require zero `/Widget` annotations and no remaining `/AcroForm` field tree after reopening, then render the final pages. Keep an editable copy when the user may need to revise the form.
## Temp And Output Conventions
- Use `tmp/pdfs/` for intermediate files; delete them when done.
- Write final artifacts under `output/pdf/` when working in this repo.
- Keep filenames stable and descriptive.
## Dependencies
Prefer the Codex bundled workspace/runtime dependencies when available. The primary runtime is expected to include:
- Python packages: `reportlab`, `pdfplumber`, `pypdf`
- Rendering tools: `pdftoppm` and `pdfinfo` from Poppler
If a dependency is missing, install only what is needed.
Python packages:
```bash
uv pip install reportlab pdfplumber pypdf
```
If `uv` is unavailable:
```bash
python3 -m pip install reportlab pdfplumber pypdf
```
System tools for rendering:
```bash
# macOS (Homebrew)
brew install poppler
# Ubuntu/Debian
sudo apt-get install -y poppler-utils
```
If installation is not possible in this environment, tell the user which dependency is missing and how to install it locally.
## Environment
No required environment variables.
## Rendering Command
```bash
pdftoppm -png "$INPUT_PDF" "$OUTPUT_PREFIX"
```
## Quality Expectations
- Maintain polished visual design: consistent typography, spacing, margins, and section hierarchy.
- Avoid rendering issues: clipped text, overlapping elements, broken tables, black squares, or unreadable glyphs.
- Charts, tables, and images must be sharp, aligned, and clearly labeled.
- Use ASCII hyphens only. Avoid U+2011 and other Unicode dashes.
- Citations and references must be human-readable; never leave tool tokens or placeholder strings.
## Final Checks
- Do not deliver until the latest PNG inspection shows zero visual or formatting defects.
- Confirm headers, footers, page numbering, and section transitions look polished.
- Keep intermediate files organized or remove them after final approval.