К основному содержанию
скилл CX Codex

pdf · nousresearch — скилл для Claude Code, Codex, Cursor: создание и обработка PDF

Скилл для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode — работает с PDF-файлами: создаёт, читает, объединяет, заполняет формы, извлекает текст и таблицы.

MIT 283 установок ★ 265 216 обновлён 2026-11-10

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add NousResearch/hermes-agent --skill pdf -a claude-code
Открыть на GitHub

Что делает pdf

Под капотом — набор argparse-скриптов в scripts/: каждый принимает аргументы, возвращает JSON в stdout и выходит с ненулевым кодом при ошибке.

Покрывает большой диапазон задач: собрать PDF из JSON-спецификации через pdf_create.py, построить заполняемую AcroForm-форму (текст, чекбоксы, радиокнопки, выпадающие списки) с предварительным линтингом через pdf_form_layout.py, вытащить текст постранично, таблицы в JSON/CSV, значения полей формы. Отдельные скрипты — для слияния, разбивки, поворота страниц, наложения водяного знака, штампа текстом или картинкой с координатами, шифрования и расшифровки паролем, экспорта страниц в PNG.

Для сканов и PDF из изображений нужны references/ocr-extraction.md (пути через pymupdf или marker-pdf) — базовый скилл их не обрабатывает. Нужны Python 3.10+ и библиотеки pypdf, reportlab, pdfplumber; скрипт самостоятельно настраивает окружение или использует Hermes-окружение documents, если hermes есть в PATH.

Какие задачи решает

  • Собрать PDF-отчёт или счёт из JSON-данных
  • Построить и заполнить AcroForm-форму по спецификации
  • Извлечь таблицы из PDF в CSV-файлы
  • Объединить несколько PDF в один файл с закладками
  • Поставить штамп «DRAFT» с поворотом на нужные страницы

Примеры запросов агенту

  • Создай PDF-счёт по данным из invoice.json и сохрани в out.pdf
  • Объедини a.pdf и b.pdf в один файл с закладками
  • Вытащи все таблицы из report.pdf и сохрани каждую как CSV в папку tables/

Как установить pdf

1Через Skills CLI (Vercel)

npx skills add NousResearch/hermes-agent --skill pdf -a claude-code

2Вручную: положить файлы

~/.claude/skills/pdf/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/pdf/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о pdf

Как установить скилл pdf в Claude Code?

Выполните npx skills add NousResearch/hermes-agent --skill pdf -a claude-code. Скилл появится по пути ~/.claude/skills/pdf/SKILL.md.

Что умеет скилл pdf?

Создаёт PDF из JSON-спецификаций, строит и заполняет AcroForm-формы, извлекает текст и таблицы, объединяет и разбивает файлы, ставит водяные знаки и штампы, шифрует документы паролем, экспортирует страницы в PNG.

Работает ли скилл pdf со сканированными документами?

Нет. Сканы и PDF из изображений обрабатываются отдельно — через references/ocr-extraction.md со скриптами на pymupdf или marker-pdf. Базовый скилл рассчитан только на текстовые PDF.

Исходный текст

SKILL.md · MIT
---
name: pdf
description: "PDF files: create, read, merge, fill, OCR, edit text."
version: 1.1.0
author: Nous Research
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [pdf, documents, forms, ocr, text-extraction, reportlab, pypdf, pdfplumber, pymupdf, marker]
    category: productivity
    related_skills: [microsoft-office]
---

# PDF Skill

Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks):

- **Scanned/image-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): `references/ocr-extraction.md`
- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references/nano-pdf-editing.md`

## When to Use

- Generate a report, invoice, or multi-page document as PDF.
- Build a fillable AcroForm (text/checkbox/radio/dropdown) from a JSON spec, linting the layout first.
- Pull text, tables (JSON/CSV), metadata, or form-field values out of a PDF.
- Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs.
- Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments.
- Fill or flatten AcroForm forms; encrypt or decrypt with passwords.
- NOT for scanned/image-only PDFs (use `references/ocr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).

## Prerequisites

- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`.
- Pick the interpreter with `terminal`. Use `python` when it already imports
  the libraries (the Hermes Docker image ships them). Otherwise, when `hermes`
  is on PATH, let Hermes build its shared, pinned documents environment under
  the Hermes home: it survives container restarts, never touches the Hermes
  install itself, and is safe to run from several agents at once. When it is
  not (the terminal runs in a Docker sandbox, which has no Hermes), the block
  builds a venv in the sandbox home with the same pinned versions. Use this
  exact block in every document skill so they all share one environment:

  ```bash
  python -c "import pypdf, reportlab, pdfplumber" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then
    PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"
  else
    PY="$HOME/.cache/hermes-docs-venv/bin/python"
    "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (
      # Safe to run from several agents at once: each caller builds a private venv,
      # a symlink publishes the first finished one atomically, the others delete theirs;
      # a published build is replaced and deleted only while it still fails to import.
      mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1
      old="$(readlink hermes-docs-venv)"  # the published build, if any (another agent may have just published it)
      python3 -m venv "$stage" &&
        "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.4 pdfplumber==0.11.10 pypdfium2==5.14.0 &&
        "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&
        if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv
        elif [ "$(readlink hermes-docs-venv)" = "$old" ] && ! "$old/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null; then
          ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&
            case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac
        fi 2>/dev/null
      [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"
    )
  fi
  export PY
  "$PY" scripts/pdf_create.py --help
  ```

  Run every helper below with `"$PY"`. In PowerShell (Hermes runs on that
  host, so it is on PATH):
  `$env:PY = hermes pm environment documents --extra documents --extra documents-pdf`.
  Never `pip install` into the interpreter that runs Hermes or into the
  `hermes pm environment` one; Hermes owns both.
- Page rasterization (`pdf_page_image.py`, overlay rendering) uses `pypdfium2`, which the documents environment already has (if your `python` lacks it, switch `PY` to that environment with the command above), or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{"rendered": false, "missing": [...]}` (exit 0) when neither exists.
- Each helper script checks imports lazily and prints an install hint if a dependency is missing.

## How to Run

All helpers live in `scripts/` and are argparse CLIs — run them with the `terminal` tool; every one supports `--help`. They read/write JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure.

```bash
python scripts/pdf_create.py spec.json -o out.pdf         # build PDF from JSON spec
python scripts/pdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec
python scripts/pdf_form_layout.py formspec.json           # lint form layout BEFORE building
python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
python scripts/pdf_read.py doc.pdf --text                 # per-page text (JSON)
python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # tables to JSON + CSV files
python scripts/pdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted/scanned flags
python scripts/pdf_read.py form.pdf --fields              # form fields: name, type, value
python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]
python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]
python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]
python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password
python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password
python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 \
    --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/
python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf
python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/
```

## Quick Reference

| Task | Tool | Command / API |
|---|---|---|
| Create doc (headings, tables, images) | reportlab platypus | `pdf_create.py spec.json -o out.pdf` |
| Build fillable form | reportlab acroForm | `pdf_make_form.py formspec.json -o form.pdf` |
| Lint form layout / overlay image | pure python + PIL | `pdf_form_layout.py formspec.json [--render-overlay o.png]` |
| Per-page text | pdfplumber | `pdf_read.py f.pdf --text` |
| Tables → JSON/CSV | pdfplumber | `pdf_read.py f.pdf --tables` |
| Metadata / sizes / encrypted / scanned | pypdf + pdfplumber | `pdf_read.py f.pdf --meta` |
| Merge (+ outline) | pypdf | `pdf_merge.py a.pdf b.pdf -o m.pdf` |
| Split / extract / rotate | pypdf | `pdf_split.py f.pdf --pages 2-5 --rotate 90` |
| List / fill / flatten form | pypdf | `pdf_read.py --fields`, `pdf_fill_form.py` |
| Encrypt / decrypt (AES-256) | pypdf | `pdf_secure.py --encrypt/--decrypt` |
| Watermark / stamp PDF page | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` |
| Stamp text/image at coordinates | reportlab + pypdf | `pdf_stamp.py f.pdf --text "Sign here" --x 400 --y 60` |
| Pages → PNG (review / OCR hand-off) | pypdfium2 or pdftoppm | `pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/` |
| Set/clear metadata, attachments | pypdf | `pdf_meta.py --set-meta / --attach / --extract-attachments` |
| Compress content streams | pypdf | `pdf_split.py f.pdf --pages 1-N --compress` |

## Procedure

1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, export them with `pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/` and hand the PNGs to the `references/ocr-extraction.md` skill — do not report empty text as "no content".
2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`/`author` metadata; page numbers are added automatically), then run `pdf_create.py`. Verify visually with `vision_analyze` on a rendered page image if layout matters.
3. **Extract.** `--text` gives a JSON list of per-page strings; `--tables` gives row arrays per page and can also emit CSV files. Read results with `read_file`; never eyeball a binary PDF directly.
4. **Manipulate.** `pdf_merge.py` concatenates and can add one bookmark per source file; `pdf_split.py` handles page ranges (1-based, e.g. `1-3,5,9-`), rotation in 90° steps, and `--compress`. Watermark by preparing a single-page stamp PDF (e.g. via `pdf_create.py`) and overlaying it with `pdf_watermark.py`; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use `pdf_stamp.py` with text or an image at explicit coordinates.
5. **Build forms.** Write one form-spec JSON (fields with `label_box`/`entry_box` in PDF points — see `references/forms.md`), lint it with `pdf_form_layout.py` and fix every reported problem, optionally review the `--render-overlay` PNG with `vision_analyze`, then build with `pdf_make_form.py` and confirm with `pdf_read.py --fields`.
6. **Fill forms.** List fields (`--fields`) to learn exact names and types, write a UTF-8 JSON of `{"FieldName": "value"}` with `write_file` (checkboxes accept `true`/`false`; radio/choice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed.
7. **Metadata & attachments.** `pdf_meta.py --set-meta` writes Title/Author/Subject/Keywords (DocInfo); `--clear-meta` drops them; `--attach`/`--list-attachments`/`--extract-attachments` round-trip embedded files.
8. **Secure.** Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy.
9. **Verify** (see below) before reporting success.

## Pitfalls

- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references/ocr-extraction.md`; do not fabricate text.
- **Flattening limits**: `pdf_fill_form.py --flatten` uses pypdf's flatten support, which converts widget appearances into page content. It is reliable for plain text fields and checkboxes but can drop or misrender exotic widgets (rich text, custom appearance streams, some radio groups). Verify the flattened output visually with `vision_analyze`; for bulletproof flattening use an external renderer (e.g. Ghostscript or `pdftoppm`+reassembly) as a fallback.
- **NeedAppearances**: after filling, viewers only render values if appearance streams exist. The fill script sets the AcroForm `NeedAppearances` flag so conforming viewers regenerate them; some minimal viewers ignore it — flatten if display fidelity matters.
- **Non-Latin form values**: values are stored correctly (UTF-16), but the field's default font may lack glyphs, so a viewer can show blanks even though the data round-trips. Verify with `--fields`, not just visually.
- **Compression expectations**: `--compress` only deflates content streams. Typical savings are 0–20%; it does nothing for PDFs dominated by images or already-compressed streams. It is not a substitute for image downsampling (Ghostscript territory).
- **Permission flags don't enforce**: owner-password permission bits (no-print, no-copy) are polite requests that viewers may honor; any library (including pypdf) can read and strip them. Only the user password actually gates content via encryption. Never present permission flags as security.
- **Table extraction is heuristic**: pdfplumber detects tables from ruling lines/word alignment; borderless or merged-cell tables may need `table_settings` tuning or manual cleanup.
- **Page indexing**: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert.
- **Rotated stamp text extraction**: pdfplumber's line grouping scrambles rotated glyphs (a 45° "DRAFT" extracts as stray letters); verify rotated stamps with `pypdf`'s `extract_text()` or a rendered image instead.
- **Radio groups**: reportlab needs ≥2 `radio()` widgets per group, fills need the slashed export value (`"/red"`), and flatten fidelity is worst for radios — see `references/forms.md`.
- **Metadata scope**: `pdf_meta.py` writes the classic DocInfo dictionary only; embedded XMP metadata (if any) is left untouched and may show different values in some viewers.
- **PDF/A is out of scope**: pypdf/reportlab cannot produce or validate conformant PDF/A. If archival conformance is required, run Ghostscript via the `terminal` tool (e.g. `gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf` with a suitable ICC profile) and validate with veraPDF — both are external installs, and the result still needs validation, not assumption.
- Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation.

## Verification

- After create/merge/split: `pdf_read.py out.pdf --meta` — confirm `page_count`, and per-page `rotation` when you rotated.
- After extraction: check the JSON is non-empty and spot-check a known string or cell.
- Form design loop: `pdf_form_layout.py spec.json` must exit 0; then `--render-overlay boxes.png --pdf form.pdf` and review the PNG with `vision_analyze` (red = entry boxes with field names, blue = label boxes) asking about overlaps, misalignment, and labels detached from their fields. Iterate spec → lint → overlay until clean.
- After building a form: `pdf_read.py form.pdf --fields` lists every spec field with the right type and options.
- After form fill: `pdf_read.py filled.pdf --fields` and compare values (exact match, including non-ASCII).
- After stamping: re-extract text (pypdf for rotated stamps) or render the page with `pdf_page_image.py` and inspect with `vision_analyze`.
- After metadata/attachment edits: `pdf_read.py --meta` / `pdf_meta.py --list-attachments`, and re-extract an attachment to byte-compare.
- After encrypt: `--meta` shows `"encrypted": true` and opening without a password fails; after decrypt, text extraction matches the original.
- For anything visual (watermarks, flattened forms), render and inspect with `vision_analyze`.

© Nous Research · MIT · NousResearch/hermes-agent

Похожие скиллы

Все скиллы по теме «Документы и офис» →

Сначала — pdf от других авторов.

pdf официальный anthropics Читает, создаёт и меняет PDF-файлы, включая формы и сканы. Обрабатывает PDF в проекте. CX Codex +1 216 041установок pdf официальный openai Читает, создаёт и проверяет PDF через визуальный рендер страниц — агент видит результат, а не только текст. CX Codex +1 14 000установок pdf nexu-io Извлекает текст, собирает PDF-документы и заполняет формы. Помогает оформлять пресс-релизы, одностраничники и печатные макеты. CX Codex +1 3 200установок pdf appautomaton Скилл читает, создаёт, заполняет и меняет PDF. Он пригодится для форм, сканов, таблиц и подготовки итогового файла. CX Codex +1 720установок pdf shareAI-lab Извлекает текст из PDF, создаёт PDF из Markdown и склеивает файлы. CX Codex +1 ★ 80 707звёзд репо openai-pdf OpenAI Плагин openai-pdf помогает читать, генерировать и проверять PDF в Claude Code с контролем вёрстки страниц. ★ 540звёзд репо pdf-reading SeifBenayed Скилл pdf-reading для чтения PDF-файлов с диска: извлечение текста, растеризация страниц, анализ таблиц, картинок и вложений. CX Codex +1 ★ 116звёзд репо pdf-construction datadrivenconstruction Скилл pdf-construction разбирает строительную документацию в PDF: извлекает данные RFI, делит чертежи по листам, парсит разделы спецификаций и собирает пакеты согласования. CX Codex +1 126установок pdf-processing-pro davila7 Скилл pdf-processing-pro для Claude Code обрабатывает PDF: заполняет формы, извлекает таблицы и распознаёт текст. Включается при пакетной обработке документов. CX Codex +1 5 869установок pdf-to-structured datadrivenconstruction Скилл pdf-to-structured парсит таблицы, ведомости материалов и отчёты из PDF в Excel, CSV и JSON. Работает со сканами через OCR и с исходными PDF-файлами через pdfplumber. CX Codex +1 149установок pdf-extraction claude-office-skills Скилл pdf-extraction для Claude Code извлекает текст и таблицы из PDF с помощью pdfplumber. Разбирает отчёты и инвойсы, переносит данные в DataFrames. CX Codex +1 9 600установок

Из того же набора61

Весь набор →
pretext Скилл для браузерных демо на @chenglou/pretext: текст обтекает фигуры, ломается на графемы и меряется через canvas без пересчёта страницы. CX Codex +1 320установок docx Создаёт, читает, правит и проверяет файлы .docx через Python CLI-скрипты. Собирает отчёты, заполняет шаблоны и обрабатывает правки. CX Codex +1 310установок grounded-citations Скилл grounded-citations привязывает утверждения агента к проверенным ссылкам со сквозной нумерацией в стиле Perplexity и проверяет точность цитат по сохранённому тексту. CX Codex +1 307установок openhue Скилл openhue для Claude Code управляет светильниками, комнатами и сценами Philips Hue через терминал. Настраивает освещение дома из чата с агентом. CX Codex +1 288установок polymarket Получает из публичных REST API Polymarket данные о рынках, ценах, стаканах заявок и истории. Показывает, какие шансы рынок даёт событию. CX Codex +1 282установок inspecting-hermes-desktop-dom Скилл inspecting-hermes-desktop-dom читает DOM, CSS и консоль работающего Hermes Desktop через CDP. Пригодится, чтобы проверить, применился ли стиль и какое CSS-правило победило. CX Codex +1 263установок github Скилл github управляет задачами, пулл-реквестами, ревью и репозиториями через консольную утилиту gh. Помогает вести полный цикл от создания issue до слияния проверенного PR. CX Codex +1 245установок heartmula Запускает локальную генерацию песен из текста и тегов через HeartMuLa. Работает без облачного сервиса. CX Codex +1 230установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой