拆pdf：跑得最勤的一页纸

本栏拆过社区里形形色色的明星件：会拍片会的、会造公司的、会给游戏改内存的。这一次拆一件最不像“明星”的——Anthropic 官方 Skills 仓库（anthropics/skills）里的 pdf 技能。它没有新星榜上的爆发曲线，没有营销式的一句话简介，却可能是整个 Skills 生态里被实际执行次数最多的技能之一：官方工程博客介绍 Agent Skills 架构时明确说过，这批文档技能同时驱动着 Claude 应用里的文件处理功能。你在 Claude 里随手丢一个 PDF 说“帮我填了”，背后干活的就是它。越是被跑得多的件，越值得拆——因为它经得起量。

一、档案：文档四件套里的老大哥

pdf 件住在 anthropics/skills 仓库的 document-skills/ 目录下，同门一共四个：pdf、docx、pptx、xlsx，江湖人称文档四件套。它们和 skill-creator、canvas-design 这些 example 技能同仓不同架——document-skills 是“编制内”的生产件，example-skills 更偏示范教学。

先给本文的评测结论表。四件套同门同源、设计同构，放在一起评才有参照系（评分为本文主观判断，五星制）：

pdf 拿满分的原因很简单：PDF 这个格式的用户诉求相对收敛——抽取、合并、拆分、填表、简单生成——它把这些诉求全部接住了。pptx 分数最低不是因为写得差，而是幻灯片的“美化”本身没有客观标准，天花板天然更高。

二、门牌：两行 frontmatter，一句顶一万句

项目	内容
所属仓库	github.com/anthropics/skills
路径	document-skills/pdf
形态	SKILL.md 说明书 + 配套资源文件（以仓库当前版本为准）
核心依赖	Python 生态的 PDF 处理库（pypdf、pdfplumber 一类）
同门	docx / pptx / xlsx
定位	PDF 的读、写、拆、合、填表

技能	功能完整度	设计质量	实战效果	上手难度	社区活跃度	综合
pdf	★★★★★	★★★★★	★★★★★	★★★★★	★★★★★	5.0
docx	★★★★★	★★★★★	★★★★☆	★★★★★	★★★★★	4.8
xlsx	★★★★☆	★★★★★	★★★★☆	★★★★☆	★★★★★	4.6
pptx	★★★★☆	★★★★☆	★★★★☆	★★★★☆	★★★★★	4.4

任何 SKILL.md 都以 YAML frontmatter 开头，pdf 件也不例外。真正的设计全部压缩在 description 这一个字段里，大意如下（逐字以仓库当前版本为准）：

这段话值得逐句拆，因为它是全技能唯一“常驻”在模型上下文里的部分。Claude 启动时并不会把所有技能的正文都装进脑子——那会把上下文撑爆——装进去的只有每个技能的 name 和 description，相当于货架上的门牌。等用户说出的话和某块门牌对上了，正文才会被加载。所以 description 的每一个词都是路由开关：

第一句是能力清单，全是动词加宾语。 “抽取文本与表格、创建、合并/拆分、处理表单”——没有一句背景介绍，没有“强大的”“优雅的”这类形容词。因为路由匹配靠的是关键词撞车：用户说“把这两个 PDF 合一下”，“合并”这个词必须在门牌上，撞不上就是漏单。

第二句是触发时机，句式固定为 "When Claude needs to..."。 这是官方件的标志性写法：前一句列能力，后一句把能力翻译成“用户会怎么提需求”。用户很少说“我要做 PDF manipulation”，他们说“帮我填个表”“把这些发票内容提出来”。第二句就是用来接住口语的。

给想写自己技能的读者，这里能直接抄走三个招式：一是 description 只写能力动词和触发场景，形容词一个不要；二是把“用户的原话”写进门牌里，而不是写你希望用户说的话；三是控制长度，门牌是常驻成本，每个技能都多写两百字，一百个技能就是两万字白白占着上下文。

三、正文：不是教程，是作业本

门牌命中之后，SKILL.md 正文才被读进来。pdf 件的正文结构是一份标准的“分任务速查手册”，节名示意如下：

---
name: pdf
description: （能力清单 + 触发时机，见上）
---
# PDF 处理

## 概览与依赖声明
（先装什么库、用什么工具链）

## 读取：抽取文本与表格
## 创建：生成新 PDF
## 合并与拆分
## 填写表单
（每节：短说明 + 可直接运行的 Python 片段）

它的写法有三个反直觉之处，恰好是多数社区技能没学会的地方。

第一，开头就是依赖，不寒暄。 正文第一件事是告诉模型：这个环境里需要 pypdf、pdfplumber 这类 Python 库，没有就先装。这一步看起来多余——模型不是知道 pypdf 吗？但“知道”和“环境里有”是两回事。依赖前置声明等于把运行环境写进合同，避免模型兴冲冲写出代码、一跑才发现库不存在。

第二，每节给的是代码，不是 API 讲解。 这是全篇最精妙的设计决策。PDF 处理库的 API 变迁是重灾区：PyPDF2 改名 pypdf，接口随之变动，模型训练语料里新旧版本混杂，凭记忆默写 API 极容易写出一个不存在的方法——这就是所谓的幻觉 API。SKILL.md 直接把“定版写法”的代码片段放在那里，模型的任务从“默写”变成“抄写”。抄写不会错，默写才会。社区里大量技能喜欢在正文里讲道理、讲理念，pdf 件几乎不讲道理，它只给作业本。

第三，按任务分节，而不是按库分节。 手册的组织方式是“用户想干什么”（读文本、填表单、拆文件），而不是“库的能力有哪些”（pypdf 能干什么、pdfplumber 能干什么）。用户的需求在前，实现工具在后。这个顺序决定了路由之后模型能不能一步翻到答案：用户要填表单，模型直接跳到填表单那一节，中间不需要任何推理。

四、骨架：三层渐进式披露

把门牌和正文合起来看，pdf 件是官方“渐进式披露”（progressive disclosure）架构的标准样板。整个技能的信息分三层加载，每一层都比上一层更贵、也更按需：

flowchart TD
    A["用户: 帮我填这份PDF表单"] --> B["常驻层: 技能门牌清单"]
    B --> C{"description<br/>命中?"}
    C -->|命中| D["加载层: 读入SKILL.md正文"]
    C -->|未命中| E["按普通对话处理"]
    D --> F["翻到填表单任务节"]
    F --> G["执行层: 生成并运行<br/>Python代码处理文件"]
    G --> H["输出填好的PDF"]
    H --> I["向用户交付结果"]

sequenceDiagram
    participant U as 用户
    participant C as Claude
    participant S as pdf件
    participant P as Python
    U->>C: 填好这份报关单
    C->>S: 门牌命中, 读入正文
    S-->>C: 返回填表单步骤与代码
    C->>P: 运行代码读取字段名
    P-->>C: 字段清单
    C->>P: 写入数据并另存新PDF
    P-->>U: 交付填好的文件

这套架构解决的是 Skills 生态的命门：上下文经济。假设你装了一百个技能，每个正文平均五千 token，如果全部常驻，五万 token 的预算还没干活就烧光了。渐进式披露把常驻成本压到每技能几十字的门牌，正文和脚本只在命中时进场。官方把这套机制写进了工程博客和文档，等于给整个生态定了一个行文范式——后来 skills.sh、skillsmp 上架的社区件，凡是门牌写得又臭又长的，都是没读懂这一课。

第二层收益是确定性。模型直接“输出一个填好的 PDF”是不可能的——它只能输出文本。pdf 件的路径是让模型输出代码，由代码去操作文件。代码可以重跑、可以调试、可以校验，输出文本则一次定生死。把“生成”变成“执行”，是把大模型的不确定性外包给了确定性的工具链。这也是为什么文档四件套全部选择了“说明书写代码”而不是“说明书写咒语”的路线。

五、边界：它接不住的四种活

拆解一个技能，光说它多能干是营销，说清它接不住什么才是评测。以实践经验和当前版本的设计取向看，四类活要另请高明：

扫描件。 PDF 分两种：文字型和图片型。扫描仪吐出来的是后者，文字是“画”在页面上的像素，pypdf 这类库读出来只有一张图。要抽取就得先过 OCR，而 pdf 件没有内置 OCR 引擎，效果取决于你的环境里装没装相应工具。手里全是扫描合同的用户，先补齐 OCR 工具链再谈。

加密与权限件。 带口令或带权限限制的 PDF，第一步就会卡在解密上。这是格式本身的安全设计，任何技能都绕不过，只能用户自己提供密码。

高保真版式还原。 把 PDF 转成 Word、转成 HTML 还想保持版式一模一样——这是整个 PDF 行业的公共难题，不是这一个技能的短板。它擅长的是结构化操作（抽取、拆合、填字段），不是视觉复刻。

平铺表单。 PDF 表单也分两种：带字段定义的 AcroForm（ Acrobat 里那种能点击输入的）和“看起来像表单的图片”，后者字段根本不存在，只能以盖章方式把文字叠印到坐标上。前者 pdf 件接得干干净净，后者属于上面的扫描件问题。

六、安装：两条路，一条保底

# 保底安装法：直接从官方仓库克隆
git clone https://github.com/anthropics/skills.git
mkdir -p ~/.claude/skills
cp -r skills/document-skills/pdf ~/.claude/skills/pdf

# 项目级安装（只对当前项目生效）则放进项目目录：
# cp -r skills/document-skills/pdf ./.claude/skills/pdf

重启 Claude Code 生效。同门的另外三件，把路径里的 pdf 换成 docx / pptx / xlsx 即可。官方仓库同时支持通过 Claude Code 的插件市场安装（/plugin 相关命令，具体标识以仓库 README 当前说明为准），但手动克隆这条路的优点是不依赖任何中间层，且你能顺手把四件套全部读一遍——对想学写技能的人，这四份 SKILL.md 就是最好的教材。

装完之后验证方式也简单：对 Claude 说“把这两个 PDF 合并”，如果它开始写 Python 调 pypdf 而不是让你手动操作，说明门牌命中、正文进场了。

七、推荐排行榜：文档四件套怎么选

四件套建议整体安装，反正门牌只占几十个词，正文不命中不加载——这正是渐进式披露架构送给用户的后顾无忧。

结语：这一页纸教的三件事

pdf 件拆完，沉淀下来的是三条可以直接复用的设计律。第一，门牌即路由：description 是你唯一的广告位，用用户的话写，别用自己的话写。第二，正文即作业本：与其教模型道理，不如给它定版的可运行代码，把“生成”降级成“抄写”。第三，成本分层：常驻的越少越好，昂贵的越晚进场越好。

生态里每天都有新星技能一夜千星，但多数新星的文章写法，还停留在“讲理念、堆咒语”的阶段。官方这页没有星光的说明书，反而是最值得每个技能作者逐行抄写的一篇。跑得最勤的件，往往字最少。