Sign PDF (signature stamping for sign-and-return workflows)

Overview

Most "sign and return" PDFs aren't true Docusign envelopes - they're flat PDFs with a "Signature:" line, or proper AcroForm PDFs with fillable signature fields. This skill stamps a transparent PNG of the user's signature at the right spot, optionally adds today's date, and saves a signed copy. The output is a normal PDF that can be attached to a reply email.

Tool: scripts/sign_pdf.py (PyMuPDF-based) Signature image: you provide this - see Setup below. Never use a placeholder or a signature that isn't the actual user's.

Setup

Before first use:

1. Get a clear image of the user's signature: a photo of it signed on plain white paper, or a scan.
2. Run scripts/prep_signature.py to turn it into a transparent PNG (white background removed, ink kept):

   python scripts/prep_signature.py "/path/to/signature-source.jpg" "/path/to/signature.png"

   Tune --threshold (default 230, range 0-255) if the result loses ink or keeps paper texture - lower is more aggressive at removing near-white pixels.
3. Tell sign_pdf.py where that PNG lives, either by passing --signature /path/to/signature.png on every command, or by setting the environment variable SIGNATURE_IMAGE so you don't have to repeat it.
4. Keep the signature PNG out of source control and treat it like a sensitive file (see Signature Asset Hygiene below).

When to Use

Use when:

• The user attaches/forwards a PDF and says "sign this", "add my signature", "sign and return"
• A contract/agreement/form needs their signature

Don't use for:

• Docs marked "must be wet-signed" or with notary blocks (legally insufficient)
• Real-estate closings, banking power-of-attorney, anything requiring witnessing
• True Docusign envelopes - those should go through Docusign's UI for the audit trail

Legal Note (ESIGN Act, US)

This is general background, not legal advice.

Image-stamp signatures on flat PDFs are binding for normal commercial contracts under the US ESIGN Act 2000. Avoid them for: notarized documents, anything explicitly requiring wet-ink, real-estate closings, and Docusign-grade-audit-trail required docs (some banking/HIPAA contexts). If you're outside the US, check your own jurisdiction's e-signature rules before relying on this. When in doubt, surface the question to the user before signing.

Workflow

inspect -> preview (optional) -> stamp OR auto

1. inspect - print page count, dimensions, AcroForm fields, and "Signature:"/"By:" labels detected by text search. Always start here.
2. auto - try AcroForm signature fields first; fall back to stamping near label text. Works on the majority of well-built PDFs, not all.
3. preview - render a page as PNG so you can eyeball the layout and pick (x,y) coordinates manually.
4. stamp - place signature image at explicit --page --x --y --width (PDF points, 72 per inch, top-left origin).
5. text - stamp plain text (printed name, title, date) at explicit --page --x --y --size. The y is the text baseline. Use this to fill the rows below the signature line.

Quick Reference

# Inspect
python scripts/sign_pdf.py inspect "/path/to/contract.pdf"

# Auto (try first - fastest path)
python scripts/sign_pdf.py auto "/path/to/contract.pdf" --signature "/path/to/signature.png"

# Preview a page to pick coordinates
python scripts/sign_pdf.py preview "/path/to/contract.pdf" --page 5

# Stamp at explicit coords + date below signature
python scripts/sign_pdf.py stamp "/path/to/contract.pdf" --page 5 --x 100 --y 620 --width 150 --date --signature "/path/to/signature.png"

# Stamp plain text (printed name, title, date) at coords. Run once per field; chain via --out.
python scripts/sign_pdf.py text "Jane Doe" --page 5 --x 316 --y 161 --size 11
python scripts/sign_pdf.py text "Chief Executive Officer" --page 5 --x 316 --y 194 --size 11
python scripts/sign_pdf.py text "2026-05-06" --page 5 --x 316 --y 227 --size 11

# Custom output path
... --out "/path/to/contract-signed.pdf"

Default output is <original>-signed.pdf next to the input. --signature can be omitted if you set the SIGNATURE_IMAGE environment variable.

Decision Flow

Got PDF to sign
  |
  v
Run inspect
  |
  v
Has AcroForm signature widgets?  -- yes --> auto, then verify with preview
  |
  no
  v
Has "Signature:" / "By:" labels found?  -- yes --> auto (text-search fallback), verify
  |
  no
  v
Manual: preview each candidate page, pick coords, stamp explicitly

Common Mistakes

Signature Asset Hygiene

• Keep the source photo/scan and the transparent working PNG out of source control (.gitignore should cover them - see this repo's own .gitignore as an example, but if you install this skill inside your own project, make sure your .gitignore there also excludes it).
• If the machine holding the signature PNG is compromised, that PNG could be used to forge documents. Consider encrypting it at rest, or storing it in your OS's credential manager, if that risk matters to you.

Limitations (current v1)

• Single signature per run for stamp mode (auto can place multiple if multiple fields/labels found)
• No initials-per-page mode - would need a --initials flag with corner placement
• No checkbox/text-field filling - only signature image stamping
• No verification of signed output - always open the signed PDF and visually confirm before sending
• Coordinate origin is top-left in PyMuPDF, but some PDF tools use bottom-left. If a stamp lands in the wrong place, try --y (page_height - y).