[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CB3AF0EGGYA2K76X38B6ES":3,"skill-same:01M6CB3AF0EGGYA2K76X38B6ES":175},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":50,"linkOnly":51,"markdownContent":52,"markdownBody":53,"frontMatter":54,"refName":69,"commitSha":70,"skillDirectory":71,"forksCount":72,"repositoryHtmlUrl":73,"repositoryHomepageUrl":6,"ownerHtmlUrl":74,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":75,"install":76,"resources":89},"01M6CB3AF0EGGYA2K76X38B6ES","pdf",null,"PDF files: create, read, merge, fill, OCR, edit text.","adnichols\u002Fai-configs","adnichols","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F493746?v=4","01M6C33VRY9WF6XWYPT1AFA7JJ","Aaron Nichols","01M6C33VWTNKGRM92E9G643V4W",5,"MIT","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000004","电子表格",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000034","行政与办公人员","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49],"PDF","files","docx","edit","read","text","ocr","productivity","extraction","create","powerpoint","documents","windows","merge","research","linux","macos","xlsx","2026-11-10 10:12:30",false,"---\nname: pdf\ndescription: \"PDF files: create, read, merge, fill, OCR, edit text.\"\nversion: 1.1.0\nauthor: Nous Research\nlicense: MIT\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    tags: [pdf, documents, forms, ocr, text-extraction, reportlab, pypdf, pdfplumber, pymupdf, marker]\n    category: productivity\n    related_skills: [docx, xlsx, powerpoint]\n---\n\n# PDF Skill\n\nCreate PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text\u002Ftables\u002Fmetadata, merge\u002Fsplit\u002Frotate\u002Fwatermark\u002Fstamp pages, export page images, manage metadata and attachments, and encrypt\u002Fdecrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references\u002F (read the matching file before those tasks):\n\n- **Scanned\u002Fimage-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts\u002Fextract_pymupdf.py + scripts\u002Fextract_marker.py): `references\u002Focr-extraction.md`\n- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references\u002Fnano-pdf-editing.md`\n\n## When to Use\n\n- Generate a report, invoice, or multi-page document as PDF.\n- Build a fillable AcroForm (text\u002Fcheckbox\u002Fradio\u002Fdropdown) from a JSON spec, linting the layout first.\n- Pull text, tables (JSON\u002FCSV), metadata, or form-field values out of a PDF.\n- Merge, split, rotate, extract page subsets, watermark, stamp text\u002Fimages at coordinates, bookmark, or compress PDFs.\n- Export pages as PNGs for visual review or for OCR hand-off; set\u002Fclear document metadata; add\u002Fextract file attachments.\n- Fill or flatten AcroForm forms; encrypt or decrypt with passwords.\n- NOT for scanned\u002Fimage-only PDFs (use `references\u002Focr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).\n\n## Prerequisites\n\n- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`:\n  `python -m pip install pypdf reportlab pdfplumber`\n- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `python -m pip install pypdfium2`, or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{\"rendered\": false, \"missing\": [...]}` (exit 0) when neither exists.\n- Each helper script checks imports lazily and prints an install hint if a dependency is missing.\n\n## How to Run\n\nAll helpers live in `scripts\u002F` and are argparse CLIs — run them with the `terminal` tool; every one supports `--help`. They read\u002Fwrite JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure.\n\n```bash\npython scripts\u002Fpdf_create.py spec.json -o out.pdf         # build PDF from JSON spec\npython scripts\u002Fpdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec\npython scripts\u002Fpdf_form_layout.py formspec.json           # lint form layout BEFORE building\npython scripts\u002Fpdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]\npython scripts\u002Fpdf_read.py doc.pdf --text                 # per-page text (JSON)\npython scripts\u002Fpdf_read.py doc.pdf --tables --csv-dir t\u002F  # tables to JSON + CSV files\npython scripts\u002Fpdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted\u002Fscanned flags\npython scripts\u002Fpdf_read.py form.pdf --fields              # form fields: name, type, value\npython scripts\u002Fpdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]\npython scripts\u002Fpdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]\npython scripts\u002Fpdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]\npython scripts\u002Fpdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password\npython scripts\u002Fpdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password\npython scripts\u002Fpdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]\npython scripts\u002Fpdf_stamp.py doc.pdf -o out.pdf --text \"DRAFT\" --x 150 --y 400 \\\n    --font-size 60 --rotation 45 --opacity 0.3 --color \"#cc0000\" [--pages 1-3]\npython scripts\u002Fpdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120\npython scripts\u002Fpdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs\u002F\npython scripts\u002Fpdf_meta.py doc.pdf --set-meta --title \"T\" --author \"A\" -o out.pdf\npython scripts\u002Fpdf_meta.py doc.pdf --attach data.csv -o out.pdf\npython scripts\u002Fpdf_meta.py doc.pdf --list-attachments | --extract-attachments dir\u002F\n```\n\n## Quick Reference\n\n| Task | Tool | Command \u002F API |\n|---|---|---|\n| Create doc (headings, tables, images) | reportlab platypus | `pdf_create.py spec.json -o out.pdf` |\n| Build fillable form | reportlab acroForm | `pdf_make_form.py formspec.json -o form.pdf` |\n| Lint form layout \u002F overlay image | pure python + PIL | `pdf_form_layout.py formspec.json [--render-overlay o.png]` |\n| Per-page text | pdfplumber | `pdf_read.py f.pdf --text` |\n| Tables → JSON\u002FCSV | pdfplumber | `pdf_read.py f.pdf --tables` |\n| Metadata \u002F sizes \u002F encrypted \u002F scanned | pypdf + pdfplumber | `pdf_read.py f.pdf --meta` |\n| Merge (+ outline) | pypdf | `pdf_merge.py a.pdf b.pdf -o m.pdf` |\n| Split \u002F extract \u002F rotate | pypdf | `pdf_split.py f.pdf --pages 2-5 --rotate 90` |\n| List \u002F fill \u002F flatten form | pypdf | `pdf_read.py --fields`, `pdf_fill_form.py` |\n| Encrypt \u002F decrypt (AES-256) | pypdf | `pdf_secure.py --encrypt\u002F--decrypt` |\n| Watermark \u002F stamp PDF page | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` |\n| Stamp text\u002Fimage at coordinates | reportlab + pypdf | `pdf_stamp.py f.pdf --text \"Sign here\" --x 400 --y 60` |\n| Pages → PNG (review \u002F OCR hand-off) | pypdfium2 or pdftoppm | `pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs\u002F` |\n| Set\u002Fclear metadata, attachments | pypdf | `pdf_meta.py --set-meta \u002F --attach \u002F --extract-attachments` |\n| Compress content streams | pypdf | `pdf_split.py f.pdf --pages 1-N --compress` |\n\n## Procedure\n\n1. **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 \u003Cscanned> --dpi 300 --out-dir imgs\u002F` and hand the PNGs to the `references\u002Focr-extraction.md` skill — do not report empty text as \"no content\".\n2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`\u002F`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.\n3. **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.\n4. **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.\n5. **Build forms.** Write one form-spec JSON (fields with `label_box`\u002F`entry_box` in PDF points — see `references\u002Fforms.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`.\n6. **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`\u002F`false`; radio\u002Fchoice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed.\n7. **Metadata & attachments.** `pdf_meta.py --set-meta` writes Title\u002FAuthor\u002FSubject\u002FKeywords (DocInfo); `--clear-meta` drops them; `--attach`\u002F`--list-attachments`\u002F`--extract-attachments` round-trip embedded files.\n8. **Secure.** Encrypt with distinct user\u002Fowner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy.\n9. **Verify** (see below) before reporting success.\n\n## Pitfalls\n\n- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references\u002Focr-extraction.md`; do not fabricate text.\n- **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.\n- **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.\n- **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.\n- **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).\n- **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.\n- **Table extraction is heuristic**: pdfplumber detects tables from ruling lines\u002Fword alignment; borderless or merged-cell tables may need `table_settings` tuning or manual cleanup.\n- **Page indexing**: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert.\n- **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.\n- **Radio groups**: reportlab needs ≥2 `radio()` widgets per group, fills need the slashed export value (`\"\u002Fred\"`), and flatten fidelity is worst for radios — see `references\u002Fforms.md`.\n- **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.\n- **PDF\u002FA is out of scope**: pypdf\u002Freportlab cannot produce or validate conformant PDF\u002FA. 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.\n- Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation.\n\n## Verification\n\n- After create\u002Fmerge\u002Fsplit: `pdf_read.py out.pdf --meta` — confirm `page_count`, and per-page `rotation` when you rotated.\n- After extraction: check the JSON is non-empty and spot-check a known string or cell.\n- 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.\n- After building a form: `pdf_read.py form.pdf --fields` lists every spec field with the right type and options.\n- After form fill: `pdf_read.py filled.pdf --fields` and compare values (exact match, including non-ASCII).\n- After stamping: re-extract text (pypdf for rotated stamps) or render the page with `pdf_page_image.py` and inspect with `vision_analyze`.\n- After metadata\u002Fattachment edits: `pdf_read.py --meta` \u002F `pdf_meta.py --list-attachments`, and re-extract an attachment to byte-compare.\n- After encrypt: `--meta` shows `\"encrypted\": true` and opening without a password fails; after decrypt, text extraction matches the original.\n- For anything visual (watermarks, flattened forms), render and inspect with `vision_analyze`.\n","# PDF Skill\n\nCreate PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text\u002Ftables\u002Fmetadata, merge\u002Fsplit\u002Frotate\u002Fwatermark\u002Fstamp pages, export page images, manage metadata and attachments, and encrypt\u002Fdecrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references\u002F (read the matching file before those tasks):\n\n- **Scanned\u002Fimage-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts\u002Fextract_pymupdf.py + scripts\u002Fextract_marker.py): `references\u002Focr-extraction.md`\n- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references\u002Fnano-pdf-editing.md`\n\n## When to Use\n\n- Generate a report, invoice, or multi-page document as PDF.\n- Build a fillable AcroForm (text\u002Fcheckbox\u002Fradio\u002Fdropdown) from a JSON spec, linting the layout first.\n- Pull text, tables (JSON\u002FCSV), metadata, or form-field values out of a PDF.\n- Merge, split, rotate, extract page subsets, watermark, stamp text\u002Fimages at coordinates, bookmark, or compress PDFs.\n- Export pages as PNGs for visual review or for OCR hand-off; set\u002Fclear document metadata; add\u002Fextract file attachments.\n- Fill or flatten AcroForm forms; encrypt or decrypt with passwords.\n- NOT for scanned\u002Fimage-only PDFs (use `references\u002Focr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).\n\n## Prerequisites\n\n- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`:\n  `python -m pip install pypdf reportlab pdfplumber`\n- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `python -m pip install pypdfium2`, or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{\"rendered\": false, \"missing\": [...]}` (exit 0) when neither exists.\n- Each helper script checks imports lazily and prints an install hint if a dependency is missing.\n\n## How to Run\n\nAll helpers live in `scripts\u002F` and are argparse CLIs — run them with the `terminal` tool; every one supports `--help`. They read\u002Fwrite JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure.\n\n```bash\npython scripts\u002Fpdf_create.py spec.json -o out.pdf         # build PDF from JSON spec\npython scripts\u002Fpdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec\npython scripts\u002Fpdf_form_layout.py formspec.json           # lint form layout BEFORE building\npython scripts\u002Fpdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]\npython scripts\u002Fpdf_read.py doc.pdf --text                 # per-page text (JSON)\npython scripts\u002Fpdf_read.py doc.pdf --tables --csv-dir t\u002F  # tables to JSON + CSV files\npython scripts\u002Fpdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted\u002Fscanned flags\npython scripts\u002Fpdf_read.py form.pdf --fields              # form fields: name, type, value\npython scripts\u002Fpdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]\npython scripts\u002Fpdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]\npython scripts\u002Fpdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]\npython scripts\u002Fpdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password\npython scripts\u002Fpdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password\npython scripts\u002Fpdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]\npython scripts\u002Fpdf_stamp.py doc.pdf -o out.pdf --text \"DRAFT\" --x 150 --y 400 \\\n    --font-size 60 --rotation 45 --opacity 0.3 --color \"#cc0000\" [--pages 1-3]\npython scripts\u002Fpdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120\npython scripts\u002Fpdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs\u002F\npython scripts\u002Fpdf_meta.py doc.pdf --set-meta --title \"T\" --author \"A\" -o out.pdf\npython scripts\u002Fpdf_meta.py doc.pdf --attach data.csv -o out.pdf\npython scripts\u002Fpdf_meta.py doc.pdf --list-attachments | --extract-attachments dir\u002F\n```\n\n## Quick Reference\n\n| Task | Tool | Command \u002F API |\n|---|---|---|\n| Create doc (headings, tables, images) | reportlab platypus | `pdf_create.py spec.json -o out.pdf` |\n| Build fillable form | reportlab acroForm | `pdf_make_form.py formspec.json -o form.pdf` |\n| Lint form layout \u002F overlay image | pure python + PIL | `pdf_form_layout.py formspec.json [--render-overlay o.png]` |\n| Per-page text | pdfplumber | `pdf_read.py f.pdf --text` |\n| Tables → JSON\u002FCSV | pdfplumber | `pdf_read.py f.pdf --tables` |\n| Metadata \u002F sizes \u002F encrypted \u002F scanned | pypdf + pdfplumber | `pdf_read.py f.pdf --meta` |\n| Merge (+ outline) | pypdf | `pdf_merge.py a.pdf b.pdf -o m.pdf` |\n| Split \u002F extract \u002F rotate | pypdf | `pdf_split.py f.pdf --pages 2-5 --rotate 90` |\n| List \u002F fill \u002F flatten form | pypdf | `pdf_read.py --fields`, `pdf_fill_form.py` |\n| Encrypt \u002F decrypt (AES-256) | pypdf | `pdf_secure.py --encrypt\u002F--decrypt` |\n| Watermark \u002F stamp PDF page | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` |\n| Stamp text\u002Fimage at coordinates | reportlab + pypdf | `pdf_stamp.py f.pdf --text \"Sign here\" --x 400 --y 60` |\n| Pages → PNG (review \u002F OCR hand-off) | pypdfium2 or pdftoppm | `pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs\u002F` |\n| Set\u002Fclear metadata, attachments | pypdf | `pdf_meta.py --set-meta \u002F --attach \u002F --extract-attachments` |\n| Compress content streams | pypdf | `pdf_split.py f.pdf --pages 1-N --compress` |\n\n## Procedure\n\n1. **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 \u003Cscanned> --dpi 300 --out-dir imgs\u002F` and hand the PNGs to the `references\u002Focr-extraction.md` skill — do not report empty text as \"no content\".\n2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`\u002F`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.\n3. **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.\n4. **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.\n5. **Build forms.** Write one form-spec JSON (fields with `label_box`\u002F`entry_box` in PDF points — see `references\u002Fforms.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`.\n6. **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`\u002F`false`; radio\u002Fchoice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed.\n7. **Metadata & attachments.** `pdf_meta.py --set-meta` writes Title\u002FAuthor\u002FSubject\u002FKeywords (DocInfo); `--clear-meta` drops them; `--attach`\u002F`--list-attachments`\u002F`--extract-attachments` round-trip embedded files.\n8. **Secure.** Encrypt with distinct user\u002Fowner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy.\n9. **Verify** (see below) before reporting success.\n\n## Pitfalls\n\n- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references\u002Focr-extraction.md`; do not fabricate text.\n- **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.\n- **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.\n- **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.\n- **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).\n- **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.\n- **Table extraction is heuristic**: pdfplumber detects tables from ruling lines\u002Fword alignment; borderless or merged-cell tables may need `table_settings` tuning or manual cleanup.\n- **Page indexing**: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert.\n- **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.\n- **Radio groups**: reportlab needs ≥2 `radio()` widgets per group, fills need the slashed export value (`\"\u002Fred\"`), and flatten fidelity is worst for radios — see `references\u002Fforms.md`.\n- **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.\n- **PDF\u002FA is out of scope**: pypdf\u002Freportlab cannot produce or validate conformant PDF\u002FA. 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.\n- Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation.\n\n## Verification\n\n- After create\u002Fmerge\u002Fsplit: `pdf_read.py out.pdf --meta` — confirm `page_count`, and per-page `rotation` when you rotated.\n- After extraction: check the JSON is non-empty and spot-check a known string or cell.\n- 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.\n- After building a form: `pdf_read.py form.pdf --fields` lists every spec field with the right type and options.\n- After form fill: `pdf_read.py filled.pdf --fields` and compare values (exact match, including non-ASCII).\n- After stamping: re-extract text (pypdf for rotated stamps) or render the page with `pdf_page_image.py` and inspect with `vision_analyze`.\n- After metadata\u002Fattachment edits: `pdf_read.py --meta` \u002F `pdf_meta.py --list-attachments`, and re-extract an attachment to byte-compare.\n- After encrypt: `--meta` shows `\"encrypted\": true` and opening without a password fails; after decrypt, text extraction matches the original.\n- For anything visual (watermarks, flattened forms), render and inspect with `vision_analyze`.\n",{"name":5,"author":55,"license":15,"version":56,"metadata":57,"platforms":68,"description":7},"Nous Research","1.1.0",{"hermes":58},{"tags":59,"category":39,"related_skills":67},[5,43,60,38,61,62,63,64,65,66],"forms","text-extraction","reportlab","pypdf","pdfplumber","pymupdf","marker",[34,49,42],[47,48,44],"main","64e2fc9afa7bb3da1138eb73399144d0e7e73e9d","_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf",4,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs","https:\u002F\u002Fgithub.com\u002Fadnichols","2026-11-06 00:28:38",{"source":8,"skillName":5,"commands":77,"prompt":87,"zipAvailable":88},[78,81,84],{"tool":79,"command":80},"npx","npx skills add adnichols\u002Fai-configs --skill pdf",{"tool":82,"command":83},"bunx","bunx skills add adnichols\u002Fai-configs --skill pdf",{"tool":85,"command":86},"pnpm","pnpm dlx skills add adnichols\u002Fai-configs --skill pdf","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002FSKILL.md",true,[90,95,101,105,109,115,119,123,127,131,135,139,143,147,151,155,159,163,167,171],{"path":91,"resourceType":91,"resourceTypeDesc":92,"sizeBytes":93,"sourceHtmlUrl":94},"LICENSE","许可证",1070,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002FLICENSE",{"path":96,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":99,"sourceHtmlUrl":100},"references\u002Fforms.md","REFERENCE","参考文档",3950,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Freferences\u002Fforms.md",{"path":102,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":103,"sourceHtmlUrl":104},"references\u002Fnano-pdf-editing.md",1342,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Freferences\u002Fnano-pdf-editing.md",{"path":106,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":107,"sourceHtmlUrl":108},"references\u002Focr-extraction.md",5615,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Freferences\u002Focr-extraction.md",{"path":110,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":113,"sourceHtmlUrl":114},"scripts\u002F_raster.py","SCRIPT","脚本",2614,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002F_raster.py",{"path":116,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":117,"sourceHtmlUrl":118},"scripts\u002Fextract_marker.py",3458,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fextract_marker.py",{"path":120,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":121,"sourceHtmlUrl":122},"scripts\u002Fextract_pymupdf.py",3671,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fextract_pymupdf.py",{"path":124,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":125,"sourceHtmlUrl":126},"scripts\u002Fpdf_create.py",4562,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_create.py",{"path":128,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":129,"sourceHtmlUrl":130},"scripts\u002Fpdf_fill_form.py",3887,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_fill_form.py",{"path":132,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":133,"sourceHtmlUrl":134},"scripts\u002Fpdf_form_layout.py",7131,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_form_layout.py",{"path":136,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":137,"sourceHtmlUrl":138},"scripts\u002Fpdf_make_form.py",5988,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_make_form.py",{"path":140,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":141,"sourceHtmlUrl":142},"scripts\u002Fpdf_merge.py",1686,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_merge.py",{"path":144,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":145,"sourceHtmlUrl":146},"scripts\u002Fpdf_meta.py",4458,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_meta.py",{"path":148,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":149,"sourceHtmlUrl":150},"scripts\u002Fpdf_page_image.py",3589,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_page_image.py",{"path":152,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":153,"sourceHtmlUrl":154},"scripts\u002Fpdf_read.py",5895,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_read.py",{"path":156,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":157,"sourceHtmlUrl":158},"scripts\u002Fpdf_secure.py",2679,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_secure.py",{"path":160,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":161,"sourceHtmlUrl":162},"scripts\u002Fpdf_split.py",3045,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_split.py",{"path":164,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":165,"sourceHtmlUrl":166},"scripts\u002Fpdf_stamp.py",5779,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_stamp.py",{"path":168,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":169,"sourceHtmlUrl":170},"scripts\u002Fpdf_watermark.py",1852,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Fscripts\u002Fpdf_watermark.py",{"path":172,"resourceType":111,"resourceTypeDesc":112,"sizeBytes":173,"sourceHtmlUrl":174},"tests\u002Ftest_pdf_skill.py",17433,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fproductivity\u002Fpdf\u002Ftests\u002Ftest_pdf_skill.py",[176,194,223,248,259,275],{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":182,"publishedAt":50},"01M6CB7RN791P5RRRCJWWC7DAR","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[183,184,185,186,187,188,189,190,191,192,193,44,46,47,48],"recovery","page","blocked page recovery","bot","fallback","use","fetch","hermes agent","hermes","Citations","waf",{"skillNo":195,"name":196,"nameZh":6,"description":197,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":198,"categories":199,"keywords":209,"publishedAt":50},"01M6CB7NQY2VVYCQJ1QBXACQF4","writing-plans","Use when creating or updating executable software plans. Keep plans as local files unless the user explicitly asks to register them in Doct.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fwriting-plans\u002FSKILL.md",[200,203,206],{"categoryNo":201,"categoryName":202,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":204,"categoryName":205,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":207,"categoryName":208,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000036","内容创作者",[210,211,212,213,214,215,216,217,218,33,219,220,188,221,190,191,222],"writing","writing plans","documentation","test","workflow","design","user","development","planning","implementation","html","ops","plan",{"skillNo":224,"name":225,"nameZh":6,"description":226,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":227,"categories":228,"keywords":238,"publishedAt":50},"01M6CB7JME246KZQHP73Z2STDF","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[229,232,235],{"categoryNo":230,"categoryName":231,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":233,"categoryName":234,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":236,"categoryName":237,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000037","律师与法务",[213,217,239,240,241,190,191,242,222,243,244,245,48,246,47,247,44],"test driven development","red-green-refactor","superpowers","quality","refactor","code","debugging","tdd","testing",{"skillNo":249,"name":250,"nameZh":6,"description":251,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":252,"categories":253,"keywords":255,"publishedAt":50},"01M6CB7FQ407KQTD4Z9VAWKY54","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[254],{"categoryNo":233,"categoryName":234,"taxonomyType":21,"taxonomyTypeDesc":22},[245,256,217,241,190,191,257,222,258,44,213,47,48],"systematic debugging","troubleshooting","investigation",{"skillNo":260,"name":261,"nameZh":6,"description":262,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":263,"categories":264,"keywords":268,"publishedAt":50},"01M6CB7D57MK88HE5YPZHKH68Q","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[265],{"categoryNo":266,"categoryName":267,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[261,44,269,270,46,271,47,48,272,273,274,190,191,222,218],"validate","experiments","prototype","feasibility","sketch","experiment",{"skillNo":276,"name":277,"nameZh":6,"description":278,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":279,"categories":280,"keywords":285,"publishedAt":50},"01M6CB7APAQ37YE5YE1MAAFT42","simplify-code","Parallel 3-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[281,282],{"categoryNo":204,"categoryName":205,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":283,"categoryName":284,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师",[286,287,244,288,190,191,289,222,243,290,291,292,217,44,213,47,293,48],"simplify code","simplify","subagent","parallel","code-review","delegation","cleanup","review"]