pdfcraft-documents
/pdfcraft-documents
Edit, secure, fill, sign, redact, OCR, compare and check PDFs in PdfCraft (ArtCraft's Acrobat-class PDF editor, driven through the `pdfcraft` MCP server, tools mcp__pdfcraft__*). Use whenever the user mentions PdfCraft or the pdfcraft MCP tools, or asks to work on an existing PDF in/with PdfCraft: reorganise pages (merge, split, extract, rotate, reorder, delete), edit text, add text/images/stamps/watermarks/headers/footers/bookmarks/links, fill or build forms, redact or sanitise sensitive content, sign or certify, OCR scans, compare versions, make it accessible (PDF/UA tags, alt text), convert
- Author
- dnviti ↗
- Repository
- artcraft-skills ↗
- Licence
- MIT
- Last repository change
- 30.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 30.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Edit, secure, fill, sign, redact, OCR, compare and check PDFs in PdfCraft (ArtCraft's Acrobat-class PDF editor, driven through the `pdfcraft` MCP server, tools mcp__pdfcraft__*). Use whenever the user mentions PdfCraft or the pdfcraft MCP tools, or asks to work on an existing PDF in/with PdfCraft: reorganise pages (merge, split, extract, rotate, reorder, delete), edit text, add text/images/stamps/watermarks/headers/footers/bookmarks/links, fill or build forms, redact or sanitise sensitive content, sign or certify, OCR scans, compare versions, make it accessible (PDF/UA tags, alt text), convert
Original author description
Edit, secure, fill, sign, redact, OCR, compare and check PDFs in PdfCraft (ArtCraft's Acrobat-class PDF editor, driven through the `pdfcraft` MCP server, tools mcp__pdfcraft__*). Use whenever the user mentions PdfCraft or the pdfcraft MCP tools, or asks to work on an existing PDF in/with PdfCraft: reorganise pages (merge, split, extract, rotate, reorder, delete), edit text, add text/images/stamps/watermarks/headers/footers/bookmarks/links, fill or build forms, redact or sanitise sensitive content, sign or certify, OCR scans, compare versions, make it accessible (PDF/UA tags, alt text), convert
How it works
- 0. Ground rules for the tools
- 1. Workflow
- 2. PDF safety rules (non-negotiable)
- 3. Tool families (details in references/task-map.md)
- 4. Domain know-how
- 5. Verify loop (mandatory)
- 6. Save / export
- 7. Show and approve (mandatory final phase)
- 8. Top gotchas (more in references/gotchas.md)
SKILL.md preview
---
name: pdfcraft-documents
description: "Edit, secure, fill, sign, redact, OCR, compare and check PDFs in PdfCraft (ArtCraft's Acrobat-class PDF editor, driven through the `pdfcraft` MCP server, tools mcp__pdfcraft__*). Use whenever the user mentions PdfCraft or the pdfcraft MCP tools, or asks to work on an existing PDF in/with PdfCraft: reorganise pages (merge, split, extract, rotate, reorder, delete), edit text, add text/images/stamps/watermarks/headers/footers/bookmarks/links, fill or build forms, redact or sanitise sensitive content, sign or certify, OCR scans, compare versions, make it accessible (PDF/UA tags, alt text), convert to PDF/A, protect with passwords, reduce size, export to Word/text/images. Covers the safe-copy workflow, redaction apply-and-verify, render-and-verify, save and the mandatory show-and-approve phase. Not for cases where the user explicitly asked for another tool or format (a PDF generated by code/reportlab/LaTeX, the generic pdf skill's scripts, Word/Docs documents, spreadsheets, slides)."
license: MIT
metadata:
author: dnviti
version: "1.0.0" # x-release-please-version
---
# PdfCraft documents
PdfCraft is an Acrobat-class PDF app (page organiser, text and object editing, forms, redaction,
digital signatures, OCR, accessibility checker, compare, PDF/A, optimiser). You drive it through
the `pdfcraft` MCP server (`pdfcraft-cli mcp`). This skill says **how to work safely, which tool
does what, how to verify, and how to hand the file to the user**.
- Task map (tool per job, with params): `references/task-map.md`
- Recipes (redaction, form, sign, OCR, compare, accessibility, merge/split, protect): `references/workflows.md`
- Traps and fixes: `references/gotchas.md`
## 0. Ground rules for the tools
The tools are deferred: load schemas with ToolSearch before calling (`select:mcp__pdfcraft__doc_open,
mcp__pdfcraft__page_render,...`; a keyword query returns at most ~40 at a time, so select by name).
There are ~170 tools; the registry commands (`command_list {filter}` -> `command_run {id, params}`,
`command_batch {steps}`) map onto the same tools (`doc.compare` = `doc_compare`), so prefer the named
tools. Unknown params are ignored with a warning: read `warnings`.
- **Session model**: `doc_open {path, password?}` returns a **document id** (`doc`); every other tool
takes it. `doc_create {from: blank|images|text}` makes an unsaved doc. `doc_list` shows open docs and
dirty state. Edits live **in memory** and are undoable (`edit_undo`/`edit_redo`) until `doc_save`.
`doc_close {doc, discard_changes:true}` when finished.
- **Coordinates**: points (1/72 inch), **origin top-left, y down**, page numbers **1-based**, for
`rect [x0,y0,x1,y1]`, `at [x,y]`, text_find rects, comments, form `rect`. Exceptions: `doc_compare`
rects and `form_detect_fields` rects are **bottom-left** origin (PDF space); `doc_watermark offset_y`
is up-positive. US Letter is 612x792, A4 595x842.
- Page ranges are arrays (`pages:[1,3,5]`); `doc_combine` takes range strings (`"1-3, 6"`).
- Text edited or added must be Western European (WinAnsi) in standard fonts (helvetica/times/courier)
unless the build has extra faces; unsupported characters draw as `?` (see `warnings`).
- `render_preview {doc, page, max_side}` (PNG, default 1024) and `page_render {doc, page, dpi}`
(default 96, max 600) show what a page really looks like; neither changes the document.
- Path confinement: the server may be started with read/write roots; a refused path says so.
- `pdfcraft-cli` (shell): `info`, `render`, `text`, `edit`, `combine`, `extract`, `split`, `audit`
(faux-redaction finder, non-zero exit if found), `check`, `batch`. Handy for independent checks.
## 1. Workflow
1. **Understand the job and the file**: what must change, what must not; is it signed, encrypted,
scanned (no text), a form (AcroForm/XFA)? `doc_open`, then `doc_info` (pages, sizes, metadata, bookmarks,
annotations, form fields, signatures, security, fonts, repair notes) and `render_preview` of the first
pages. `text_extract` empty on a page means a scan: OCR first if text work is needed.
2. **Work on a copy** (section 2). Never modify the user's original.
3. **Plan** the edits in order of structure: pages first (organise), then content (text/images),
then annotations/forms, then redaction, then metadata/accessibility, then security/signature last.
Signing and encryption must be the final steps: any later change breaks the signature (or must
be a permitted incremental change).
4. **Edit** with named tools; batch same-kind edits; check each result's `warnings`.
5. **Verify loop** (section 5): render the changed pages, extract text, run the task-specific audit.
6. **Save** to a new file (section 6).
7. **Show and approve** (mandatory, always last): section 7.
State the acceptance checklist before mutating; report at phase boundaries.
## 2. PDF safety rules (non-negotiable)
- **Keep originals.** Never overwrite or modify the source file unless the user explicitly asked.
Save results to a **new file** next to it or in the project dir (`contract-redacted.pdf`,
`form-filled.pdf`). `doc_save` with `path` is a full rewrite to a new file (original untouched);
`doc_save` **without** `path` saves in place (incremental update): do that only when told to.
If the target name exists and the user did not ask to replace it, pick another name.
- **Redaction must be applied AND verified**: `redact_mark` alone removes nothing. After
`redact_apply`, **save, reopen the saved file** and prove the content is gone (recipe in
`references/workflows.md` A): `text_find`/`text_extract` for each sensitive string, `doc_audit_redactions`
(must report zero findings), render and look, `doc_hidden_info` for metadata/comments/attachments/form
fields/hidden text that still carry the data, and optionally `pdfcraft-cli audit` + `pdftotext` on the saved
file. Never "redact" by drawing a black rectangle (`comment_add rectangle`, `page_add_*`) over text:
that is a faux redaction and the text stays extractable. Redaction is irreversible once saved;
say so, keep the unredacted original, and don't send/upload the original.
- **Sanitise on request** (`doc_hidden_info` shows categories; `doc_remove_hidden` removes them and
flattens form fields). Remember metadata (Title, Author, XMP) can leak names.
- **Signatures**: `sign_document` always saves to `out` and the document then shows the signed file.
Do not edit a signed PDF without telling the user it invalidates (or adds a revision to) the
signature; certify levels restrict changes. `sign_list` validates (status valid / unknown = untrusted
self-signed / invalid). A self-signed ID is "unknown" until `sign_trust` is given its certificate.
Never create or use a digital ID, password or signature image on someone's behalf without being given
it/asked; a typed "signature" (`fill_sign_add`) is a visual mark, not a cryptographic signature.
- **Passwords**: choose none by yourself; use the user's. Don't echo them. `doc_protect` applies at the
next `doc_save` (full rewrite). Keep the unprotected original.
- **Compare/OCR/optimise write new files**; they leave the open document unchanged.
- Don't fabricate content in legal/financial documents: edit only what was asked; show before/after.
## 3. Tool families (details in `references/task-map.md`)
| Job | Tools |
|---|---|
| Open/create/save | `doc_open`, `doc_create`, `doc_save`, `doc_close`, `doc_list`, `doc_info`, `doc_inspect` |
| Pages | `page_delete/move/rotate/extract/duplicate/reverse/replace/insert_blank/insert_file/set_box/number`, `doc_combine`, `doc_split` |
| Text | `text_extract/find/lines/paragraphs/fonts/word_count`, `text_edit`, `page_add_text`, `content_list/update/copy/delete` |
| Images/objects | `page_add_image`, `page_images`, `image_edit`, `object_list/move`, `doc_export_images/all_images` |
| Marks | `doc_watermark`, `doc_background`, `doc_header_footer`, `stamp_custom`, `doc_remove_marks` |
| Navigation | `bookmark_*`, `link_*`, `links_from_urls`, `doc_initial_view`, `attachment_*` |
| Comments | `comment_add/list/edit/reply/set_status/delete`, `comments_summarize/hide` |
| Forms | `form_fields`, `form_fill`, `form_add_field`, `form_detect_fields`, `form_set_props`, `form_reset`, `form_tab_order`, `doc_import_data/export_data`, `doc_flatten` |
| Redaction/privacy | `redact_mark/apply/clear`, `doc_audit_redactions`, `doc_hidden_info`, `doc_remove_hidden` |
| Signing | `sign_id_create`, `sign_document`, `sign_list`, `sign_trust`, `fill_sign_add` |
| OCR | `ocr_status`, `ocr_recognize`, `ocr_recognize_files`, `page_enhance_camera` |
| Accessibility | `accessibility_check/fix/report/tags/figures/set_alt/autotag_*` |
| Compare | `doc_compare {doc:newer, other:older, visual?}`, `doc_compare_mark`, `doc_compare_report` |
| Standards/size | `pdfa_verify/convert`, `print_readiness`, `doc_optimize`, `doc_reduce`, `doc_audit_space` |
| Security | `doc_protect`, `doc_unprotect` |
| Export | `doc_export_text`, `doc_export_office` (.docx/.pptx/.html/.rtf by extension), `doc_export_data` |
## 4. Domain know-how
- **Form filling**: `form_fields` for names/types/options/required; `form_fill {values:{name:value}}`
(text/combo/radio: string; checkbox: true/false; multi-select list: array). A PDF with no fields: use
`form_detect_fields {add:true}` to create fields from blanks, or `fill_sign_add` to place text/check marks.
Verify by `form_fields` and a render. Keep the form editable unless asked to flatten (`doc_flatten`).
XFA forms: `xfa_to_static` first (irreversible for scripts; ask).
- **Added marks belong to the document**: headers/footers, stamps, watermarks and added text take the
standard face closest to the existing type (`text_fonts`), its colours and its margins, not a stock
grey diagonal "CONFIDENTIAL" in Helvetica, unless the user asks for exactly that.
- **Merging/splitting**: `doc_combine {paths, pages?, out}` (ordered; keeps bookmarks, renames clashing
form fields); `doc_split {doc, every|before|bookmarks|max_mb, out_dir}`; `page_extract`.
- **Text edits**: `text_paragraphs {page}` gives paragraph numbers and boxes; `text_edit {paragraph|line,
text, font, size, color}` rewraps in place with standard fonts; for scans OCR first. Edited text may not
match the original embedded font exactly: render and compare.
- **Accessibility**: `accessibility_check` (32 rules) -> fix what can be fixed (`accessibility_fix`
title/primary-language/tab-order; `accessibility_set_alt` for figures; `accessibility_autotag_*` only for
simple untagged text-only/forms). The checker never certifies compliance: report failed and manual rules
honestly. Set the document Title (`doc_set_info`) and language.
- **PDF/A**: `pdfa_verify` -> `pdfa_convert {level:"2b"|"3b"}` -> verify again; non-embedded fonts remain
as unfixable findings.
- **Size**: `doc_optimize {path, preset:"standard"|"mobile"}` or `doc_reduce {path}`; compare sizes, render
to check legibility; signed documents are refused.
- **OCR**: `ocr_status` first (English only); `ocr_recognize {pages, dpi}` adds invisible text over the scan;
verify with `text_find` and by spot-checking text vs image (OCR errors on numbers/names matter).
## 5. Verify loop (mandatory)
After each phase on the working copy:
1. `doc_info` / `doc_list`: page count, dirty state, fields, signatures, security as expected.
2. `render_preview`/`page_render` every changed page and **look**: placement, clipping, overlap, fonts.
3. Content: `text_extract`/`text_find` to confirm presence (edits) or absence (redactions).
4. Task audit: `doc_audit_redactions`, `sign_list`, `accessibility_check`, `pdfa_verify`, `form_fields`,
`doc_compare` of original vs result (only the intended changes appear).
5. Fix with `edit_undo`/new edits; repeat.
For saved results, **reopen the saved file** (`doc_open` on the new path) for the final check, not only
the in-memory doc.
## 6. Save / export
- `doc_save {doc, path:"/abs/new.pdf"}` (new file, full rewrite, atomic). `flatten_fill_sign:true` bakes
Fill & Sign marks in. `full:true/false` forces rewrite/incremental. Encryption and sanitising take
effect in the save.
- Other outputs: `doc_export_office {path:".docx|.pptx|.html|.rtf"}`, `doc_export_text`, `doc_export_images`,
`doc_optimize`, `doc_split`, `page_extract {out}`, `doc_compare_report {path}`: all create new files;
tell the user the paths.
- Close docs and delete scratch files afterwards.
## 7. Show and approve (mandatory final phase)
Every PDF job ends here, after the verify loop. The headless `pdfcraft-cli mcp` session has no window,
so the user cannot see the result until you save it and open the real app on it.
1. **Save to a new file** (never over the original unless the user said so) with `doc_save {path}` in
the project directory or the path the user named; descriptive name (`contract-redacted.pdf`); for signed
output the `out` of `sign_document`. Note the full absolute path. Reopen it once to verify.
2. **Open PdfCraft on that file**, detached so it doesn't block:
`setsid pdfcraft /abs/path/result.pdf >/dev/null 2>&1 &`
(`pdfcraft [options] [files...]` is the desktop app, `/usr/bin/pdfcraft`, MIME `application/pdf`;
optional `--page N`, `--zoom 150`, `--theme dark`, `--new-window`. If a PdfCraft window is already
running, the file is passed to it.)
3. **Stop and ask.** Give the full path (and the original's path, kept untouched) and ask the user to accept
the result or describe changes. Never continue on your own: nothing is sent, uploaded, emailed, signed,
deleted, replaced or exported to another format/handed to another tool before explicit acceptance.
Silence or a vague reaction is not acceptance. For redactions, ask the user to look at the black boxes.
4. **Loop on changes**: apply them (from the in-memory working copy or a fresh `doc_open` of the saved file),
re-run the verify loop, save again (new version name or the same new file), reopen/refresh PdfCraft,
ask again, until accepted.
5. **Inside a subagent** (cannot talk to the user): do steps 1 and 2, then return the file path, the
original path, a short summary of changes, the verification results, and state clearly that **user
approval is pending**. The orchestrator asks the user and relays changes back.
## 8. Top gotchas (more in `references/gotchas.md`)
- `redact_mark` removes nothing; `redact_apply` + save + reopen + audit does. Black rectangles are not redaction.
- `doc_save` without `path` overwrites in place: never by default.
- `sign_document` writes `out` itself; sign last; later edits break signatures.
- Coordinates: top-left origin, points, 1-based pages (compare and detect_fields rects are bottom-left).
- `doc_protect` and `doc_remove_hidden` only apply at the next save (full rewrite).
- `doc_compare {doc: newer, other: older}`: order matters.
- Scans have no text: OCR before searching/redacting by text; `redact_mark rect` works without text.
- Added text is limited to standard fonts/WinAnsi; others draw `?`.
- Open docs stay in the session: close them and delete scratch files.
Files in this package (4)
- SKILL.md 15 KB
- references/gotchas.md 2 KB
- references/task-map.md 7 KB
- references/workflows.md 5 KB
Versions
The database has no other skills named pdfcraft-documents.
Database snapshot: 13.11.2026 · package version 99133915299f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100pdfcraft
Headless PDF work with PdfCraft, provisioned on demand by pi-craft - combine, split, extract, rotate, delete and reorder pages, read text, render a page to png, audit faux redactions, script its 163 tools. Use for "merge these two PDFs", "extract pages 1 and 3 from this PDF",… - 100pdf
Create, inspect, edit, redact, sign, render, and verify PDF files through explicit, fail-closed provider routes. Use for new tagged documents, imported PDFs, forms, annotations, OCR, conformance, and visual QA. - 95Pdf
Create, merge, split, extract text/tables from PDFs, fill forms, add watermarks, and convert to/from other formats. USE WHEN pdf, PDF file, merge PDF, extract tables, fill form, split PDF. - 95Pdf
Create, merge, split, extract text/tables from PDFs, fill forms, add watermarks, and convert to/from other formats. USE WHEN pdf, PDF file, merge PDF, extract tables, fill form, split PDF. - 100pdf-processing
Inspect, extract, OCR, create, merge, split, reorder, rotate, annotate, fill, redact, compress, secure, and verify PDF documents while preserving source files and visual fidelity. Use when working with one or more .pdf files; converting documents to or from PDF; extracting text,… - 100processing-pdf
Use when the user needs to extract data from PDFs, work with scanned documents, or manipulate PDF files. Triggers include: "extract text from PDF", "convert PDF to text/CSV/images", "scan/OCR this document", "merge/split/rotate PDF", "fill PDF form", "PDF is blank/empty" (likely…