document-SKILLs

# Document Skills

Skills for creating, reading, and manipulating PDF, PPTX, XLSX, and DOCX files.

> `CLAUDE.md` in this directory is a symlink to this file (`AGENTS.md`).

## Python

- Always use `uv run` to execute Python scripts in these skills.
- All directly-run scripts declare their dependencies via PEP 723 inline metadata — `uv run` resolves them automatically. (Library modules imported by those scripts inherit the runner's environment and need no header of their own.) No manual `pip install` needed.
- When writing a new script, add a PEP 723 header:
  ```python
  # /// script
  # requires-python = ">=3.12"
  # dependencies = ["pypdf", "Pillow"]
  # ///
  ```
- Never run bare `pip install`. Never use the system Python (`/usr/bin/python3`).

### Python Packages

| Package | PyPI name | Used by | Purpose |
|---------|-----------|---------|---------|
| pypdf | `pypdf` | pdf | PDF reading/writing, form fields, annotations |
| pdf2image | `pdf2image` | pdf | PDF page to image conversion (requires poppler) |
| Pillow | `Pillow` | pdf, pptx | Image processing, drawing, fonts |
| pdfplumber | `pdfplumber` | pdf | Text and table extraction |
| reportlab | `reportlab` | pdf | PDF creation from scratch |
| pytesseract | `pytesseract` | pdf | OCR wrapper for Tesseract |
| pypdfium2 | `pypdfium2` | pdf | PDF rendering using PDFium engine |
| python-pptx | `python-pptx` | pptx | PowerPoint file manipulation |
| markitdown | `markitdown[pptx]` | pptx | Extract PPTX text as Markdown |
| openpyxl | `openpyxl` | pdf, xlsx | Excel file manipulation |
| pandas | `pandas` | pdf, xlsx | Data analysis, table operations |
| matplotlib | `matplotlib` | xlsx | Chart and visualization creation |
| lxml | `lxml` | pptx, docx | XML processing and XSD schema validation |
| defusedxml | `defusedxml` | pptx, docx | Secure XML parsing (XXE protection) |

## Node.js

Each skill that needs Node packages has its own `package.json` and `node_modules/`. Run `npm install` in the skill directory once to set up.

| Skill | Packages |
|-------|----------|
| pptx | `pptxgenjs`, `playwright` (launches Chromium for HTML→image rendering), `sharp`, `react`, `react-dom`, `react-icons` (the last four serve agent-written html2pptx scripts, not `html2pptx.js` itself) |
| docx | `docx` |

pdf and xlsx do not use Node packages.

## System Tools (`brew` or `apt-get`)

On macOS, `brew bundle` at the repo root installs everything below. The Brewfile keeps optional tools commented out and skips uv and node when they are already on the PATH.

### Required

| Package | Install | Provides | Used by |
|---------|---------|----------|---------|
| poppler | `brew install poppler` | `pdftoppm`, `pdftotext`, `pdfimages` | pdf, pptx, docx |
| LibreOffice | `brew install --cask libreoffice` | `soffice` | pptx, xlsx, docx |
| pandoc | `brew install pandoc` | `pandoc` | docx |

### Optional

| Package | Install | Provides | Used by |
|---------|---------|----------|---------|
| tesseract | `brew install tesseract` | `tesseract` | pdf |
| tesseract-lang | `brew install tesseract-lang` | language packs | pdf |
| qpdf | `brew install qpdf` | `qpdf` | pdf |
| coreutils | `brew install coreutils` | `gtimeout` | xlsx |

## Skill Structure

Each skill has:
- `SKILL.md` — the prompt/instructions for the skill
- `scripts/` — Python scripts the agent calls via `uv run` (xlsx instead ships a single `recalc.py` at the skill root)
- `package.json` — Node.js dependencies (docx, pptx only)
- `ooxml/` — XML pack/unpack/validate tooling (docx, pptx only)