前言¶

做开发或运维，PDF 几乎是绕不开的格式：合同扫描件要 OCR 成可搜索文本，多张发票要合并成一份归档，报表里的表格要抽出来进 Excel，还有带密码的 PDF、要填写的表单、要加水印的内部文档……每次碰到这些需求，往往要在浏览器插件、Python 脚本和命令行工具之间来回切换，还得自己查 API 文档。

如果你已经在用 Cursor、Claude Code 或 Codex 这类 AI 编程助手，Anthropic 官方维护的 pdf Skill 可以把上述流程收拢成一套可复用的工作方式：Agent 读到 Skill 里的操作指南后，会按场景选用 pypdf、pdfplumber、reportlab 等 Python 库，或 pdftotext、qpdf 等命令行工具来完成任务。本文基于官方仓库核实后整理，介绍这个 Skill 的定位、能力与安装用法。

这是什么¶

pdf 是 Anthropic 在 anthropics/skills 仓库中提供的 Agent Skill，遵循 Agent Skills 开放标准，可在 Cursor、Claude Code、Codex CLI 等支持该标准的工具中使用。

它的核心定位很直接：只要用户提到 .pdf 文件，或要做 PDF 相关操作，Agent 就应加载此 Skill，并按其中的 Processing Guide 执行。Skill 的 YAML frontmatter 写明了触发范围——读取与提取文本/表格、合并拆分、旋转页面、加水印、创建 PDF、填写表单、加密解密、提取图片、对扫描件做 OCR 等。

需要说明的是，pdf 与 docx、pptx、xlsx 同属 Anthropic 的「文档类 Skill」，是 Claude 文档能力在仓库中的参考实现。官方 README 注明：这些文档 Skill 为 source-available（源码可参考），许可为 Proprietary，并非 Apache 2.0 开源；使用前请阅读目录下的 LICENSE.txt。

核心功能与亮点¶

Skill 主体在 SKILL.md，表单填写详见 forms.md，高级用法与 JavaScript 库（如 pdf-lib）见 reference.md。目录结构如下：

skills/pdf/
├── SKILL.md       # 主指南与常用代码片段
├── forms.md       # PDF 表单填写专项说明
├── reference.md   # 进阶参考（pypdfium2、pdf-lib 等）
├── scripts/       # 可选辅助脚本
└── LICENSE.txt

官方 Quick Reference 按任务类型给出了推荐工具，主要能力如下：

几个值得注意的官方细节：

1. ReportLab 上下标：不要用 Unicode 上下标字符（如 H₂O），内置字体会显示黑块；应使用 <sub>、<super> 标签。
2. 表单填写：Skill 明确要求先读 forms.md，不要凭猜测填字段。
3. 渐进式加载：主文件只放常用操作，复杂场景按需读 reference.md，节省 Agent 上下文。

安装与启用¶

pdf Skill 本质是带 SKILL.md 的文件夹，各工具的安装方式略有差异。

Claude Code¶

官方推荐通过 Plugin 安装整包文档 Skill：

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

安装后，在对话中直接说明需求即可，例如：「Use the PDF skill to extract the form fields from path/to/file.pdf」。Agent 会根据 Skill 描述自动匹配，也可在支持 / 命令的环境中显式调用。

Claude.ai 付费计划用户也可在网页端按 Using skills in Claude 上传或启用自定义 Skill。

Cursor¶

Cursor 启动时会自动扫描以下目录（项目级优先于用户级）：

将官方 skills/pdf 目录复制到上述路径之一即可，例如：

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

也可在 Cursor 侧边栏 Customize → Rules → Add Rule → Remote Rule (Github) 中填入仓库地址导入。Agent 会根据对话上下文自动选用 pdf Skill，或在 Agent 聊天中输入 / 搜索 pdf 手动调用。

Codex CLI¶

Codex 遵循 Agent Skills 标准，默认扫描：

安装示例：

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 内置 $skill-installer 也可从远程仓库安装 Skill；旧版 ~/.codex/skills/ 目录仍可能被兼容扫描，但官方文档已推荐迁移到 ~/.agents/skills/。

典型用法示例¶

启用 Skill 后，用自然语言描述任务即可，Agent 会按官方指南生成并执行代码。以下是 SKILL.md 中的代表性片段，便于理解 Skill 教 Agent「怎么做」。

读取 PDF 并提取文本¶

from pypdf import PdfReader

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

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

合并多份 PDF¶

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)

用 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)

扫描件 OCR¶

需先安装依赖 pytesseract、pdf2image，以及系统级 Tesseract：

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"

命令行快速处理¶

Skill 也收录了常用 CLI，适合 Agent 直接调用 shell：

# 提取文本（保留版式）
pdftotext -layout input.pdf output.txt

# 合并 PDF
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# 解密
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

# 提取内嵌图片
pdfimages -j input.pdf output_prefix

在 Cursor 或 Claude Code 中，你可以这样发起任务：

用 pdf skill 把 reports/ 目录下本月的 5 个 PDF 合并成一个文件，并从第二份里提取所有表格保存为 Excel。

Agent 加载 Skill 后会选择合适库、安装缺失依赖并执行脚本。

适用场景与注意事项¶

适合谁、什么场景：

• 需要在 AI 编程助手里反复做 PDF 批处理（合并归档、批量提取、格式转换）的开发者
• 做办公自动化、RPA 原型，希望 Agent 按固定流程选库而不是每次从零搜索文档
• 已在 Claude Code 使用 document-skills 插件，想在本机 Cursor/Codex 复用同一套 PDF 知识

注意事项：

1. 许可：pdf Skill 为 Anthropic 专有许可（Proprietary），商用或二次分发前请阅读 LICENSE.txt。
2. 环境依赖：OCR、表格提取、命令行工具需要额外安装系统包（Tesseract、poppler-utils、qpdf 等），Agent 执行前需确认环境。
3. 扫描件质量：OCR 准确率取决于扫描分辨率与语言包，复杂版式可能仍需人工校对。
4. 表单复杂度：交互式表单、XFA 表单等边缘情况以 forms.md 为准，不宜假设所有 PDF 都能一键填写。
5. 演示性质：官方 README 提醒，仓库中的 Skill 主要用于演示与教育，生产环境应充分测试后再用于关键任务。

小结¶

pdf Skill 把 PDF 常见操作——读、拆、合、转、填、加密、OCR——整理成 Agent 可遵循的分步指南，并标注了 Python 库与 CLI 的选型。对经常和 PDF 打交道的开发者来说，装一次 Skill，后续用自然语言描述需求即可，不必每次重新查 pypdf 或 poppler 的用法。

官方仓库地址：https://github.com/anthropics/skills/tree/main/skills/pdf