# PDF Toolkit

Structured `.pdf` operations: extract text/tables, merge pages from multiple PDFs...

- Repository: https://github.com/TokenRhythm/opensquilla (7104 stars)
- Category: Documents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add TokenRhythm/opensquilla --skill pdf-toolkit -g -a claude-code -y`
Codex: `npx skills add TokenRhythm/opensquilla --skill pdf-toolkit -g -a codex -y`
Cursor: `npx skills add TokenRhythm/opensquilla --skill pdf-toolkit -g -a cursor -y`
Gemini CLI: `npx skills add TokenRhythm/opensquilla --skill pdf-toolkit -g -a gemini-cli -y`

## Description

Structured `.pdf` operations: extract text/tables, merge pages from multiple PDFs, split a PDF by page ranges, fill PDF form fields, and generate fresh PDFs from JSON. Trigger when the user wants deterministic programmatic PDF work, examples: pull tables from a report, combine three PDFs, extract pages 5-12, fill a tax form, or build a new PDF from data. This is the single public PDF entry and uses pypdf, pdfplumber, and reportlab.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# pdf-toolkit

Deterministic, structural PDF operations. Use this skill for programmatic
work where you know exactly what you want done. For a natural-language rewrite,
first draft the replacement content with ordinary reasoning, then use the
explicit extract/generate/merge operations here to create the final PDF.

Use the inline Python examples with `execute_code` in a restricted channel.
Keep files in the active workspace and call `publish_artifact` with the
finished PDF. Shell commands below require an available `exec_command`;
they are optional shortcuts, not a reason to request host execution. If the
sandbox or a required library is unavailable, report the limitation rather
than retrying outside the sandbox.

## Decide the operation

| Goal | Script |
|---|---|
| Get text or tables out of a PDF | `extract.py` |
| Combine pages from multiple PDFs | `merge.py` |
| Split a PDF by page ranges | `split.py` |
| Fill `/Tx` form fields in a PDF | `form_fill.py` |
| Build a new PDF from data | inline `reportlab` snippet, see Path C below |

---

## Path A: Extract

```bash
python {baseDir}/scripts/extract.py /path/to/doc.pdf --json
```

Output:

```json
{
  "pages": 12,
  "metadata": {"title": "...", "author": "..."},
  "text": [
    {"page": 1, "content": "..."},
    {"page": 2, "content": "..."}
  ],
  "tables": [
    {"page": 3, "rows": [["..."], ["..."]]}
  ]
}
```

Text uses `pdfplumber` (already in default dependencies) which preserves
column layout better than naive PDF text extraction. Tables use
`pdfplumber.extract_tables()` with default settings; for tricky layouts
pass `--tables-strategy lines|text|explicit` to switch detection mode.

For OCR (scanned PDFs), this skill does not include Tesseract, use the
sibling skill that wraps an OCR engine (out of scope here).

---

## Path B: Merge / Split

Merge full files:

```bash
python {baseDir}/scripts/merge.py a.pdf b.pdf c.pdf --out combined.pdf
```

Or merge specific page ranges with the manifest form:

The rest: https://github.com/TokenRhythm/opensquilla/blob/HEAD/src/opensquilla/skills/bundled/pdf-toolkit/SKILL.md