Preface¶

Whether you are a developer or an operations engineer, PDF is almost an unavoidable format: contract scans need to be OCR’d into searchable text, multiple invoices need to be merged into one for archiving, tables in reports need to be extracted into Excel, there are also password-protected PDFs, forms to fill out, internal documents to watermark… Every time you encounter these requirements, you often have to switch between browser extensions, Python scripts, and command-line tools, and look up API documentation on your own.

If you are already using AI programming assistants like Cursor, Claude Code, or Codex, the pdf Skill officially maintained by Anthropic can consolidate the above workflow into a reusable working method: after the Agent reads the operation guide in the Skill, it will select Python libraries such as pypdf, pdfplumber, reportlab, or command-line tools such as pdftotext, qpdf according to the scenario to complete the task. This article is organized based on verification from the official repository, introducing the positioning, capabilities, installation, and usage of this Skill.

What is this¶

pdf is an Agent Skill provided by Anthropic in the anthropics/skills repository, following the Agent Skills open standard, and can be used in tools that support this standard such as Cursor, Claude Code, Codex CLI, etc.

Its core positioning is straightforward: whenever the user mentions a .pdf file or needs to perform PDF-related operations, the Agent should load this Skill and execute it according to the Processing Guide inside. The Skill’s YAML frontmatter specifies the trigger scope—reading and extracting text/tables, merging/splitting, rotating pages, adding watermarks, creating PDFs, filling forms, encrypting/decrypting, extracting images, OCRing scans, etc.

It should be noted that pdf, along with docx, pptx, and xlsx, belongs to Anthropic’s “Document Skills” and is a reference implementation of Claude’s document capabilities in the repository. The official README states that these document Skills are source-available (source code for reference), licensed as Proprietary, not open-source under Apache 2.0; please read the LICENSE.txt in the directory before using.

Core Features and Highlights¶

The main body of the Skill is in SKILL.md, form filling details are in forms.md, and advanced usage and JavaScript libraries (such as pdf-lib) are in reference.md. The directory structure is as follows:

skills/pdf/
├── SKILL.md       # Main guide and common code snippets
├── forms.md       # Special instructions for PDF form filling
├── reference.md   # Advanced references (pypdfium2, pdf-lib, etc.)
├── scripts/       # Optional auxiliary scripts
└── LICENSE.txt

The official Quick Reference recommends tools by task type, with the main capabilities as follows:

A few official details worth noting:
1. ReportLab subscripts and superscripts: Do not use Unicode subscript/superscript characters (such as H₂O), the built-in fonts will display black blocks; you should use <sub> and <super> tags instead.
2. Form filling: The Skill clearly requires reading forms.md first, do not fill fields based on guesswork.
3. Progressive loading: Only put common operations in the main file, read reference.md on demand for complex scenarios to save Agent context.

Installation and Activation¶

The pdf Skill is essentially a folder with SKILL.md, and the installation methods vary slightly across different tools.

Claude Code¶

The official recommendation is to install the full package of document Skills via Plugin:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

After installation, you can directly state your needs in the conversation, for example: “Use the PDF skill to extract the form fields from path/to/file.pdf”. The Agent will automatically match according to the Skill description, and can also be called explicitly in environments that support the / command.

Paid Claude.ai plan users can also upload or enable custom Skills on the web side according to Using skills in Claude.

Cursor¶

Cursor will automatically scan the following directories when starting (project-level takes precedence over user-level):

You can copy the official skills/pdf directory to one of the above paths, for example:

git clone https://github.com/anthropics/skills.git
mkdir -p ~/.cursor/skills
cp -r skills/skills/pdf ~/.cursor/skills/pdf

You can also import the repository address in the Cursor sidebar Customize → Rules → Add Rule → Remote Rule (Github). The Agent will automatically select the pdf Skill based on the conversation context, or manually call it by typing / in the Agent chat and searching for pdf.

Codex CLI¶

Codex follows the Agent Skills standard and scans by default:

Installation example:

mkdir -p ~/.agents/skills
git clone --depth 1 https://github.com/anthropics/skills.git /tmp/anthropics-skills
cp -r /tmp/anthropics-skills/skills/pdf ~/.agents/skills/pdf

Codex’s built-in $skill-installer can also install Skills from remote repositories; the old ~/.codex/skills/ directory may still be compatible with scanning, but the official documentation recommends migrating to ~/.agents/skills/.

Typical Usage Examples¶

After enabling the Skill, you can describe the task in natural language, and the Agent will generate and execute code according to the official guide. The following are representative snippets from SKILL.md to help understand how the Skill teaches the Agent “how to do it”.

Read PDF and Extract Text¶

from pypdf import PdfReader

reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

text = ""
for page in reader.pages:
    text += page.extract_text()

Merge Multiple PDFs¶

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)

Extract Tables with pdfplumber¶

import pdfplumber
import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        for table in page.extract_tables():
            if table:
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)

Scanned Document OCR¶

You need to install dependencies pytesseract, pdf2image, and system-level Tesseract first:

import pytesseract
from pdf2image import convert_from_path

images = convert_from_path("scanned.pdf")
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

Quick Processing via Command Line¶

The Skill also includes commonly used CLI tools suitable for the Agent to call the shell directly:

# Extract text (preserve layout)
pdftotext -layout input.pdf output.txt

# Merge PDFs
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# Decrypt
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

# Extract embedded images
pdfimages -j input.pdf output_prefix

In Cursor or Claude Code, you can initiate a task like this:

Use the pdf skill to merge the 5 PDFs of this month under the reports/ directory into one file, and extract all tables from the second one and save them as Excel.

After loading the Skill, the Agent will select the appropriate library, install missing dependencies, and execute the script.

Applicable Scenarios and Notes¶

Who and what scenarios it is suitable for:
- Developers who need to repeatedly perform PDF batch processing (merging archives, batch extraction, format conversion) in AI programming assistants
- Developers doing office automation, RPA prototypes, who hope the Agent selects libraries according to a fixed process instead of searching documents from scratch every time
- Users already using the document-skills plugin in Claude Code who want to reuse the same set of PDF knowledge in local Cursor/Codex

Notes:
1. License: The pdf Skill is licensed under Anthropic’s proprietary license (Proprietary), please read LICENSE.txt before commercial use or secondary distribution.
2. Environment Dependencies: OCR, table extraction, and command-line tools require additional installation of system packages (Tesseract, poppler-utils, qpdf, etc.), and the Agent needs to confirm the environment before execution.
3. Scan Quality: OCR accuracy depends on scanning resolution and language packs, and complex layouts may still require manual proofreading.
4. Form Complexity: Edge cases such as interactive forms and XFA forms are subject to forms.md, do not assume that all PDFs can be filled with one click.
5. Demo Nature: The official README reminds that the Skills in the repository are mainly for demonstration and education, and should be fully tested before being used for critical tasks in a production environment.

Summary¶

The pdf Skill organizes common PDF operations—reading, splitting, merging, converting, filling, encrypting, OCR—into a step-by-step guide that Agents can follow, and marks the selection of Python libraries and CLIs. For developers who often deal with PDFs, installing the Skill once allows you to describe requirements in natural language afterwards, without having to look up the usage of pypdf or poppler every time.

Official repository address: https://github.com/anthropics/skills/tree/main/skills/pdf