<!-- title: 官方pdf件拆解：最便宜的先上 -->

# 官方pdf件拆解：最便宜的先上

## 概述

本栏目此前已拆过官方文档家族的 docx（新建/改稿两条路）和 xlsx（公式不自己算），本期补上家族里使用频率最高、也最常被低估的一件：**官方 pdf 技能**（anthropics/skills 仓库的 document skills 之一）。拆解口径延续往期：SKILL.md 逐段讲、附属文件逐个过、设计意图往提示词工程层面挖。核心发现先给结论：这件的最大看点不是“能处理 PDF”，而是它把**成本意识写成了硬规则**——先上最便宜的工具，贵的方法全部排在后面兜底；以及填表单前强制走一步**只读探针**，把“模型直接动手改文件”这种最容易翻车的路径堵死。对想写自己第一件 Skill 的读者，这是一份近乎教科书的模板。

> 本期口径说明：写作环境未联网，未能重新抓取仓库做逐字校对。文中引用的 frontmatter 描述为该件公开版本的原文（以仓库当前版本为准），正文规则为按原文转述；Star 数等时效性数字一律从略，请以仓库实时页面为准。

## 五维评分

| 维度 | 权重 | 评分 | 一句话点评 |
|------|------|------|-----------|
| 功能完整度 | 25% | ★★★★★ | 抽文本、抽表格、填表单、新建、合并拆分，五大件全覆盖 |
| 设计质量 | 25% | ★★★★★ | 成本阶梯 + 先探后写 + 渐进披露，官方教科室范本 |
| 实战效果 | 20% | ★★★★☆ | 原生文本 PDF 极稳；扫描件和复杂盖章表单仍需人盯 |
| 上手难度 | 15% | ★★★★★ | 随 Claude Code 预装，零配置，说人话即触发 |
| 社区活跃度 | 15% | ★★★★☆ | 官方维护、随客户端持续迭代，是社区拆解引用最多的范本之一 |
| **加权总分** | 100% | **4.8 / 5** | 功能与设计双满分的守门员，扣分在扫描件边界 |

## 一、件在哪里：一个文件，三层结构

先看它的体量。pdf 技能在仓库里就是一个文件夹，典型结构三层：

```
pdf/
├── SKILL.md          # 门牌 + 操作规则（模型必读层）
├── reference.md      # 库用法细节（按需加载层）
└── scripts/
    ├── fill_pdf_form.py        # 表单写入脚本
    └── extract_form_field_info.py  # 字段探针脚本（名称以仓库当前版本为准）
```

这个三层结构和 Claude 官方工程博客里讲 Agent Skills 设计理念时给的图是一致的：SKILL.md 的元数据常驻上下文，正文在触发时才加载，reference 和 scripts 在真正干活时才读取。这就是渐进披露（progressive disclosure）——**门牌永远占座，工具间按需开门**。pdf 件是这套哲学落到“最常见文档格式”上的标准实现。

预装入口也有讲究。以本机 Claude Code 会话为例，技能清单里能看到 `pdf` 和 `example-skills:pdf` 两个入口——前者是客户端内建的文档技能，后者是 skills 仓库作为插件包提供的同名件。也就是说官方给了一条**双通道**：普通用户开箱即用，想改源码魔改的人走仓库装。

## 二、SKILL.md 逐段拆解

### 2.1 frontmatter：门牌即路由

SKILL.md 开头的 YAML 元数据里，真正决定生死的是 `description`。pdf 件的描述原文如下（以仓库当前版本为准）：

> Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form, or process, generate, or extract text and tables from PDFs. Handles text extraction, form filling, document creation, and content parsing.

拆开看，这一小段有三层设计：

**第一层：名词全覆盖。** extract text、tables、new PDFs、merging/splitting、forms——五个名词把 PDF 能干的活全部点名。路由器（模型决定用不用这件 Skill）只能看到门牌，看不到正文，所以门牌上的名词就是 SEO 关键词，一个都不能省。

**第二层：动词短语写场景。** "When Claude needs to fill in a PDF form, or process, generate, or extract..."——注意这不是功能罗列，而是**触发句式**：把用户可能说出的动词（fill、process、generate、extract）直接嵌进门牌。用户说“帮我把这两个 PDF 合并”，路由器在 description 里能检索到 merging/splitting，匹配成立。

**第三层：尾句兜底复述。** 最后一句 Handles... 又把前面说过的东西复述一遍。看似冗余，实际是给向量检索和模糊匹配多留几次命中机会。官方最佳实践里建议 description 写满写具体，上限 1024 字符——pdf 件是“写到接近上限”的示范。

另外 frontmatter 里的 `license` 字段指向 LICENSE.txt，这是仓库通用写法，保证每件 Skill 单独被拷走时许可信息不丢。这个细节值得抄：**你的 Skill 可能被任何人复制到任何地方，许可跟着门牌走**。

### 2.2 正文规则一：成本阶梯

正文的骨架是一组处理规则，按官方原文转述，大意为：

1. **读 PDF，永远先上最便宜的**：先用 `pdftotext` 这类命令行工具抽纯文本——快、便宜、够用于绝大多数“我要看内容”的场景；
2. **要表格结构，再升级 `pdfplumber`**：Python 库调用比命令行贵，但能保住表格的行列关系；
3. **扫描件降级到视觉通道**：文本层抽出来是乱码或为空，说明是扫描图像，此时转成图片让模型用视觉读——这是整条链里最贵的一档，放在最后。

这个“最便宜的先上”阶梯，解决的是 Agent 时代一个真金白银的问题：**模型默认会挑最熟悉的方法，而不是最便宜的方法**。没有这条规则，模型遇到任何 PDF 都可能直接上 Python 库甚至视觉通道，token 成本翻几倍。把成本排序写成硬规则，等于把“节流”从使用者的自觉变成了系统的默认行为。这是本期最值得抄的一条写法：**不止告诉模型“做什么”，还要告诉它“按什么顺序试、失败了再升级”**。

### 2.3 正文规则二：填表单，先探路后写入

表单是 PDF 处理里最容易翻车的场景：字段名猜错、覆盖了不该覆盖的值、填完不校验。pdf 件的规则设计成一个两段式流水线：

- **第一步，只读探针**：先跑 `extract_form_field_info.py`（探针脚本，名称以仓库当前版本为准），把表单里所有字段的名称、类型、选项列出来，**先给用户看，确认每个字段填什么**；
- **第二步，批量写入**：确认后用 `fill_pdf_form.py` 一次性写入，写完回读字段值校验。

这个设计的精髓在第一步的“只读”二字。它把危险操作（写文件）和探索操作（读结构）物理隔离——探针脚本不可能破坏文件，所以可以放心让模型自主执行；写入脚本则被规则明确排在“用户确认”之后。这对应了 Agent 安全设计里的一条铁律：**把不可逆操作排在可逆操作确认之后，并把隔离做进工具层，而不是靠提示词求模型小心**。

### 2.4 正文规则三：新建、合并、拆分，各配专库

剩余三类任务各配了专门工具（按原文转述大意）：新建 PDF 用 `reportlab` 画；合并、拆分、页级操作用 `pypdf`。注意这里没有给模型自由发挥的空间——没有“你可以选择任意库”，而是**一个任务一个指定库**。原因很实际：多一个选项，模型就多一次选错的机会，而且产出不可复现。Skill 写法里的取舍非常清楚：确定性优先于灵活性。

### 2.5 三个规则共同的结构

把三段规则放一起看，SKILL.md 正文其实是三张小路由表的叠加：

```mermaid
flowchart TD
    A["收到PDF任务"] --> B["先上最便宜的读法"]
    B --> C["pdftotext 抽文本"]
    C --> D{"要保留表格吗"}
    D -->|要| E["pdfplumber 抽表格"]
    D -->|不要| F{"接下来干什么"}
    E --> F
    F -->|填表单| G["只读探针列字段"]
    G --> H["用户确认内容"]
    H --> I["脚本写入并回读校验"]
    F -->|扫描件| L["转图片视觉阅读"]
    F -->|新建| M["reportlab 生成"]
    F -->|合并拆分| N["pypdf 页级操作"]
```

全文没有一个“请务必小心”“注意质量”之类的空话，每一条都是可执行、可判定的指令。这也是官方件和大量社区件拉开差距的地方：**社区件爱写态度，官方件只写流程**。

## 三、第二层：reference.md，细节的下沉

SKILL.md 正文刻意保持短小（官方最佳实践建议正文控制在数百行以内），库的 API 细节、参数表、边界行为全部下沉到 reference.md。触发这件 Skill 时，模型先读 SKILL.md 决定“走哪条路”；真正要写代码调 pdfplumber 或 pypdf 时，才去读 reference.md 查具体用法。

这层设计省的是两笔钱：一是上下文窗口——几百行 API 细节如果常驻，每次会话都在烧 token；二是注意力——上下文里塞满用不上的细节，模型反而容易抓错重点。对读者的启示：**你的 SKILL.md 如果超过一屏还塞满了 API 用法，就该拆 reference 了**。判断标准很简单：这段话是“选路的规则”还是“路上的细节”？前者留正文，后者下沉。

## 四、第三层：scripts/，脚本即接口

两份 Python 脚本是这件 Skill 最容易被忽视、却最能体现设计意图的部分。它们的定位是**把确定性操作从模型手里收走**：

- 字段探针脚本：读取表单结构是纯机械操作，一个 30 行的 Python 脚本永远比模型的自由发挥可靠，且结果可复现；
- 写入脚本：`fill_pdf_form.py` 接收“字段-值”对批量写入，把“逐字段编辑”这种模型最容易出错的操作变成一次确定性调用。

社区里大量 Skill 的写法是让模型现场写代码干活，pdf 件的示范是：**能固化成脚本的，就固化成脚本；SKILL.md 里只写“什么时候调哪个脚本”**。脚本即接口，模型从“操作员”退回“调度员”。这也是为什么这件 Skill 的实战表现稳——它的下限是被脚本钉住的，模型发挥空间被限制在最该发挥的地方（理解用户意图、组织字段内容）。

## 五、可抄的五个写法模式

把上面拆出的设计提炼成五条，写自己的 Skill 时可以直接套：

1. **门牌写全触发动词**：description 里把用户会说的动词和名词全部嵌进去，写满但别废话，上限 1024 字符；
2. **成本阶梯写成硬规则**：按“便宜→贵”排序给方法编号，明写“先用一，失败再上二”，把节流变成系统默认；
3. **先探后写，只读先行**：一切写文件的操作，前面必须有一个只读的探针步骤，确认后再动手；
4. **一任务一库，不留选择**：指定工具名，不给模型选型自由，换来确定性和可复现；
5. **细节下沉 reference，机械操作下沉 scripts**：SKILL.md 只留选路规则，正文永远一屏能读完。

官方文档四件的分工，顺带用一张图收拢（括号内为本栏目往期拆解标题）：

```mermaid
mindmap
  root((官方文档四件))
    docx
      新建改稿两条路
    xlsx
      公式不自己算
    pptx
      官方一件三身
    pdf
      最便宜的先上
```

## 六、适用与不适用

**适用**：原生文本 PDF 的内容抽取与问答（最稳的主场）；AcroForm 电子表单填写（报销单、申请表、政府表格）；批量合并拆分、页序调整；从结构化数据生成简单排版的新 PDF。

**不适用 / 要降低预期**：扫描质量差的图片型 PDF——视觉通道能读，但盖章、手写、倾斜都会掉精度；需要高保真还原原版式输出 PDF 的场景——reportlab 是“画新版”，不是“改旧版”；加密或带权限锁的文件；动辄上千页的服务器级批处理——那是专门服务的活，别让会话里的 Agent 硬扛。

一句话：**它是“会话内的 PDF 瑞士刀”，不是“PDF 生产流水线”**。

## 七、安装与使用

多数 Claude Code 用户无需安装——文档四件随客户端预装，直接说人话触发：

```text
帮我把这份 PDF 里的表格抽成 Markdown
把 出场登记表.pdf 里的表单字段列出来，我确认后再填
这三个 PDF 合并成一个，按日期排序
```

想看源码或魔改，从仓库手动装：

```bash
git clone --depth 1 https://github.com/anthropics/skills /tmp/anthropic-skills
mkdir -p ~/.claude/skills
cp -r /tmp/anthropic-skills/pdf ~/.claude/skills/   # 仓库内路径以实际目录为准
```

社区目录侧可用 `npx skills find pdf` 搜索市场上其他 PDF 类第三方件作对照——但就“表单填写 + 成本阶梯”这个组合，目前社区件里还没有看到结构上更优的替代。

## 八、推荐排行榜

**按人群推荐度**：
1. 财务 / 行政 / 法务——天天填表的人群，探针 + 确认流水线就是为他们设计的，首推；
2. 研究者 / 学生——文献内容抽取、批量合并，文本 PDF 场景几乎满分；
3. 开发者——合并拆分日志式 PDF、生成简单报表，顺手但替代品也多；
4. 纯扫描件处理者——能用，但建议搭配人工复核，别当 OCR 生产工具用。

**按“值得抄的程度”排**（给 Skill 作者）：
1. 成本阶梯写法——任何涉及多工具选型的 Skill 都该抄；
2. 先探后写模式——所有要改文件的 Skill 都该抄；
3. 门牌动词覆盖法——所有 Skill 都该抄，零成本。

官方文档四件里，docx 讲了“两条路”，xlsx 讲了“不算公式”，pdf 这件补上的最后一课是：**把钱和风险都写进规则里**。三件拆完，官方文档家族的写法体系也就齐了。

## 参考来源

1. [anthropics/skills 官方仓库](https://github.com/anthropics/skills) — pdf 等官方 Skill 所在仓库，SKILL.md 原文、reference.md 与 scripts/
2. [Introducing Agent Skills（Anthropic 官方发布）](https://www.anthropic.com/news/skills) — Skills 机制的官方定义与开放标准说明
3. [Equipping agents for the real world with Agent Skills（Anthropic Engineering）](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — 渐进披露等设计理念的官方工程阐述
4. [Claude Code 文档：Skills](https://docs.claude.com/en/docs/claude-code/skills) — 预装技能、frontmatter 字段规范与最佳实践（文档站路径以最新版本为准）

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)