PDF Skill
Tech Stack Target / Version: PDF extraction, OCR-capable tooling, conversion scripts, and Acrobat-compatible review workflows.
- Leverage native parallel subagent dispatch and 200k+ context windows where available.
When to use
Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
- Read or review PDF content where layout and visuals matter.
- Create PDFs programmatically with reliable formatting.
- Validate final rendering before delivery.
Workflow
- Prefer visual review: render PDF pages to PNGs and inspect them.
- Use
pdftoppm if available.
- If unavailable, install Poppler or ask the user to review the output locally.
- Use
reportlab to generate PDFs when creating new documents.
- Use
pdfplumber (or pypdf) for text extraction and quick checks; do not rely on it for layout fidelity.
- After each meaningful update, re-render pages and verify alignment, spacing, and legibility.
Temp and output conventions
- Use
tmp/pdfs/ for intermediate files; delete when done.
- Write final artifacts under
output/pdf/ when working in this repo.
- Keep filenames stable and descriptive.
Dependencies (install if missing)
Prefer uv for dependency management.
Python packages:
uv pip install reportlab pdfplumber pypdf
If uv is unavailable:
python3 -m pip install reportlab pdfplumber pypdf
System tools (for rendering):
# macOS (Homebrew)
brew install poppler
# Ubuntu/Debian
sudo apt-get install -y poppler-utils
If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
Environment
No required environment variables.
Rendering command
pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX
Quality expectations
- Maintain polished visual design: consistent typography, spacing, margins, and section hierarchy.
- Avoid rendering issues: clipped text, overlapping elements, broken tables, black squares, or unreadable glyphs.
- Charts, tables, and images must be sharp, aligned, and clearly labeled.
- Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
- Citations and references must be human-readable; never leave tool tokens or placeholder strings.
Final checks
- Do not deliver until the latest PNG inspection shows zero visual or formatting defects.
- Confirm headers/footers, page numbering, and section transitions look polished.
- Keep intermediate files organized or remove them after final approval.
Cross-Client Portability
This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
workflow in project instructions when folder discovery is unavailable.
- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
- Codex: install or sync the folder into
$CODEX_HOME/skills/pdf and restart Codex after major changes.
MCP Availability And Fallback
Preferred MCP Server: None required
- Fallback prompt: "Use the PDF Skill skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
- Do not claim an MCP operation was used when the active host does not expose it.
- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
Anti-Patterns
- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.
Verification Protocol
Before claiming the pdf workflow succeeded:
- Pass/fail: The request matches this skill's documented activation boundary.
- Pass/fail: Required inputs, dependencies, and safety checks were resolved or reported as blockers.
- Pass/fail: The narrowest relevant workflow was completed without inventing unavailable tools or results.
- Pass/fail: Output was checked with the most relevant local test, inspection, render, or source evidence.
- Pressure test: Repeat the decision with the preferred integration unavailable and confirm the fallback remains safe and actionable.
- Success metric: The result, evidence, and any unverified limitation are explicit enough for another agent to reproduce.
Related Skills
1---
2name: pdf
3version: "2.0"
4last_updated: 2026-09-08
5tags: [pdf, docs, writing, quality, templates]
6description: "Use when tasks involve reading, creating, or reviewing PDF files where rendering and layout matter; prefer visual checks by rendering pages (Poppler) and use Python tools such as `reportlab`, `pdfplumber`, and `pypdf` for generation and extraction."
7metadata:
8 source: https://skillmd.com/skills/practicalswan/pdf
9---
10
11# PDF Skill
12
13> Tech Stack Target / Version: PDF extraction, OCR-capable tooling, conversion scripts, and Acrobat-compatible review workflows.
14
15- Leverage native parallel subagent dispatch and 200k+ context windows where available.
16
17
18## When to use
19Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
20
21- Read or review PDF content where layout and visuals matter.
22- Create PDFs programmatically with reliable formatting.
23- Validate final rendering before delivery.
24
25## Workflow
261. Prefer visual review: render PDF pages to PNGs and inspect them.
27 - Use `pdftoppm` if available.
28 - If unavailable, install Poppler or ask the user to review the output locally.
292. Use `reportlab` to generate PDFs when creating new documents.
303. Use `pdfplumber` (or `pypdf`) for text extraction and quick checks; do not rely on it for layout fidelity.
314. After each meaningful update, re-render pages and verify alignment, spacing, and legibility.
32
33## Temp and output conventions
34- Use `tmp/pdfs/` for intermediate files; delete when done.
35- Write final artifacts under `output/pdf/` when working in this repo.
36- Keep filenames stable and descriptive.
37
38## Dependencies (install if missing)
39Prefer `uv` for dependency management.
40
41Python packages:
42```
43uv pip install reportlab pdfplumber pypdf
44```
45If `uv` is unavailable:
46```
47python3 -m pip install reportlab pdfplumber pypdf
48```
49System tools (for rendering):
50```
51# macOS (Homebrew)
52brew install poppler
53
54# Ubuntu/Debian
55sudo apt-get install -y poppler-utils
56```
57
58If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
59
60## Environment
61No required environment variables.
62
63## Rendering command
64```
65pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX
66```
67
68## Quality expectations
69- Maintain polished visual design: consistent typography, spacing, margins, and section hierarchy.
70- Avoid rendering issues: clipped text, overlapping elements, broken tables, black squares, or unreadable glyphs.
71- Charts, tables, and images must be sharp, aligned, and clearly labeled.
72- Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
73- Citations and references must be human-readable; never leave tool tokens or placeholder strings.
74
75## Final checks
76- Do not deliver until the latest PNG inspection shows zero visual or formatting defects.
77- Confirm headers/footers, page numbering, and section transitions look polished.
78- Keep intermediate files organized or remove them after final approval.
79
80<!-- MCP:START -->
81
82<!-- PORTABILITY:START -->
83## Cross-Client Portability
84
85This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
86
87- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
88 workflow in project instructions when folder discovery is unavailable.
89- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
90- Codex: install or sync the folder into
91 `$CODEX_HOME/skills/pdf` and restart Codex after major changes.
92
93<!-- PORTABILITY:END -->
94
95## MCP Availability And Fallback
96
97Preferred MCP Server: None required
98
99- Fallback prompt: "Use the PDF Skill skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
100- Do not claim an MCP operation was used when the active host does not expose it.
101- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
102
103<!-- MCP:END -->
104
105## Anti-Patterns
106
107- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
108- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
109- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.
110
111## Verification Protocol
112
113Before claiming the `pdf` workflow succeeded:
114
1151. Pass/fail: The request matches this skill's documented activation boundary.
1162. Pass/fail: Required inputs, dependencies, and safety checks were resolved or reported as blockers.
1173. Pass/fail: The narrowest relevant workflow was completed without inventing unavailable tools or results.
1184. Pass/fail: Output was checked with the most relevant local test, inspection, render, or source evidence.
1195. Pressure test: Repeat the decision with the preferred integration unavailable and confirm the fallback remains safe and actionable.
1206. Success metric: The result, evidence, and any unverified limitation are explicit enough for another agent to reproduce.
121
122## Related Skills
123
124- [documentation-authoring](../documentation-authoring/SKILL.md): Use it when the workflow also needs drafting structured technical or product documents.
125- [documentation-patterns](../documentation-patterns/SKILL.md): Use it when the workflow also needs reusable documentation structures and templates.
126- [documentation-quality](../documentation-quality/SKILL.md): Use it when the workflow also needs documentation review standards and quality gates.
127- [documentation-verification](../documentation-verification/SKILL.md): Use it when the workflow also needs final documentation validation before publishing.