官方 pdf Skill 深度拆解：一个 SKILL.md 里的三层渐进披露设计

概述

本期是系列第2轮，按规划做单个热门 Skill 的逐文件拆解。选中的是 Anthropic 官方 document-skills 家族里的 pdf 技能——Skills 生态里出镜率最高的一件：官方文档拿它当示例、聚合站（skillsmp.com、mcpservers.org/agent-skills、skills.sh）的文档处理类目里它常年霸榜，也是无数第三方 Skill 抄作业的原型。此前周报与家族横评（如 PPT 四件）已覆盖过横向视角，本期只解剖这一件，拆到 SKILL.md 的行级设计：frontmatter 怎么写才能被正确路由、正文为什么按“阶梯”组织、表单逻辑为什么下沉成脚本、三层渐进披露如何省 token。文末给出可直接复制的安装命令和一份“照着写一个”的模式清单。

家族定位：四件文档技能里的“教科书样本”

官方仓库 anthropics/skills 里，文档四件套（pdf / docx / pptx / xlsx）是同一套设计哲学的四种实现。本文写作环境（Claude Code）里它们以内置插件 example-skills:pdf 等形式出现，属于开箱自带。先给家族横评表，再单独深拆 pdf：

pdf 拿综合第一的理由：它是四件里“决策树”写得最干净的一个——阅读、创建、填表、合并四类任务的入口互不干扰，且阅读路线做了三级降级设计，边界场景（扫描件、无文本层 PDF）处理得最明确。

文件布局：一个目录，三种角色

document-skills/pdf/
├── SKILL.md            # 路由层 + 决策树（模型读）
└── scripts/            # 可执行脚本（模型只调用，不细读）
    ├── fill_form.py    # 表单字段填充
    └── check_borders.py# 表单边框/对齐校验

这个布局本身就是设计声明：SKILL.md 负责“何时做、按什么顺序做”，scripts 负责“精确怎么做”。代码不进上下文，只有执行结果回灌——这是官方工程博客里明确阐述的 token 经济学：脚本让确定性操作零 token 成本，模型只消费输出摘要。相比之下，大量社区 Skill 把 Python 教程整段粘进 SKILL.md，一次触发烧掉几千 token，高下立判。（注：脚本清单以仓库当前版本为准，官方仍在迭代。）

逐段拆解 SKILL.md

第一段：frontmatter——唯一的“路由器”

官方文档引用过的 description 原文（以仓库最新版为准）：

Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, filling forms, merging/splitting documents, and handling PDF operations. When Claude needs to fill in a PDF form, or programmatically process, generate, or analyze PDF documents.

这两句话是精心设计的，值得逐成分解：

• 第一句 = 能力清单。六个动名词短语（extracting text / tables、creating、filling forms、merging/splitting、handling operations）把用户可能说出的动词一网打尽。用户说“帮我把这几个 PDF 合并”，路由层靠的是动词匹配，不是文件名匹配。
• 第二句 = 触发条件，以 "When Claude needs to..." 开头。这是官方推荐的双句式：前句答“能干什么”，后句答“什么时候该想起我”。大量社区 Skill 只写第一句，结果是用户描述稍微拐个弯就触发失败——描述写得再华丽，路由层匹配不上就是死件。
• 语种选择：description 用英文写。模型对英文关键词的语义召回最稳，即使用户用中文说“填个 PDF 表格”，经内部语义对齐后仍能命中。此前周报讨论过“描述写哪种语言”的问题，官方四件套给出了统一的工程答案：英文 + 动词全覆盖。

name 字段就是 pdf——一个词，不带命名空间修饰。技能名短，是为了在系统提示词里常驻时几乎不占空间。

第二段：正文开篇——先讲策略，不讲 API

SKILL.md 正文没有从“pypdf 是什么”开始，而是先立总纲：PDF 处理没有万能库，按任务选工具。这句话决定了整个文件的形状——它是一棵决策树，不是一本教程。段落层级大致为：Overview → 依赖检查 → 阅读/提取 → 表单 → 创建 → 合并拆分。每个小节都是“任务类型 → 推荐工具 → 一段最小代码”的三段式。

第三段：阅读阶梯——三级降级设计

这是全文最值得抄的部分。SKILL.md 把“从 PDF 里拿内容”写成一条有优先级的路径：

1. 默认 pypdf：纯文本提取、元数据、页级操作（合并/拆分/旋转），轻、快、依赖少；
2. 复杂版面换 pdfplumber：多栏、表格、需要坐标信息时——pypdf 拿不到版面语义；
3. 扫描件/图像型 PDF 走视觉通道：没有文本层时，把页面转成图片，交给 Claude 的视觉能力直接读。

三级降级的精髓在于：失败是被预期的，且每级都写明了下一级是什么。多数社区 Skill 只写“用 pypdf 提取”，一旦用户扔来一个扫描合同，模型就开始瞎编文本。官方版本把“文本提取不出来”这个最常见故障的出路预先铺好，模型不用临场发挥。这是“防呆设计”在阅读路径上的直接体现。

第四段：表单工作流——脚本优先的教科书

填表单是 PDF 场景里最容易翻车的任务（字段名不可见、坐标系混乱、字体嵌入），SKILL.md 的处理方式是整段外包给脚本：

• 先用脚本列出目标 PDF 的表单字段清单（字段名、类型、可选项），让模型基于真实数据决策，而不是猜测字段名；
• 再调 fill_form.py 传入键值对完成写入；
• check_borders.py 负责校验：表单字段周围有没有可见边框——没有边框的表单，填进去的文本容易错位或不可读，脚本据此决定是否需要额外的绘制处理。

注意这个分工人设：模型只做“填什么值”的业务判断，“怎么把值写进去且不写坏”全部代码化。字段名猜测这种高幻觉风险动作，被一个脚本调用消灭了。这正是 Round 1 周报里提到的社区流派“把易错步骤固化为脚本”的源头范本。

第五段：创建与依赖声明

新建 PDF 走 reportlab（程序化排版的社区标准），SKILL.md 给出最小可用示例而非完整教程。另一个容易被忽略的设计：文件靠前位置就声明了依赖（pypdf、pdfplumber、reportlab），并提示先检查环境再动手。没有这条，模型经常写到一半才发现 ModuleNotFoundError，然后进入“装包—重试—再报错”的循环，一次任务烧掉大量轮次。依赖前置 = 把可预见的失败移出执行路径。

工作流程图

三层渐进披露的加载逻辑（Skills 的核心机制：元数据常驻，正文按需，脚本按需执行）：

flowchart TD
    A["会话启动"] --> B["第0层：仅载入 name 与 description"]
    B --> C{"用户请求涉及 PDF？"}
    C -->|是| D["第1层：载入 SKILL.md 正文"]
    C -->|否| E["保持静默，不占上下文"]
    D --> F{"任务类型？"}
    F -->|填表单| G["第2层：调用 fill_form.py"]
    F -->|复杂版面| H["换 pdfplumber 提取"]
    F -->|扫描件| I["转图片走视觉通道"]
    F -->|新建文件| J["reportlab 生成"]
    G --> K["脚本输出回灌，代码本身不进上下文"]
    H --> K
    I --> K
    J --> K

表单任务的内部闭环：

flowchart LR
    S["收到填表任务"] --> T["脚本列出全部表单字段"]
    T --> U{"字段可交互填充？"}
    U -->|是| V["fill_form.py 写入键值"]
    U -->|否| W["按坐标用 reportlab 叠写"]
    V --> X["check_borders 校验边框对齐"]
    W --> X
    X --> Y["视觉复核输出稿"]

安装命令

# 方式一：手动安装（任何 Claude Code 版本通用）
git clone https://github.com/anthropics/skills.git
cp -r skills/document-skills/pdf ~/.claude/skills/pdf

# 方式二：项目级安装（随仓库分发给团队）
mkdir -p .claude/skills
cp -r /path/to/skills/document-skills/pdf .claude/skills/pdf

# 方式三：Claude Code 内以插件市场方式启用
#   在交互界面输入：
/plugin marketplace add anthropics/skills

依赖安装（脚本运行需要）：

pip install pypdf pdfplumber reportlab

装完无需配置。直接说“把这份 PDF 里的表格提取出来”即可触发；本环境属于内置插件（example-skills:pdf），开箱即用。

适用与不适用

适用：文本/表格提取、多文件合并拆分、官方表单批量填写（申请表、报关单、问卷）、扫描件的内容理解（视觉通道）、按模板生成报告型 PDF。

不适用：加密或带权限限制的 PDF 的破解（技能不做、也不应做）；超大体积扫描件的全文 OCR（外部 OCR 引擎更稳，视觉通道按页读有成本）；像素级印刷排版（LaTeX/InDesign 仍是正解）；带法律签章文件的再加工（有合规风险，需人工复核）。

排行榜

照着写一个：五条可复制模式

1. 双句式 description：第一句罗列能力动词，第二句以 "When Claude..." 写触发条件。写完自测：用三种不同说法描述同一个需求，看能否都命中。
2. 阶梯化正文：任何“处理 X”类技能，先问失败路径——默认方案、复杂方案、兜底方案各是什么，按此顺序写，别按工具文档的顺序写。
3. 易错步骤脚本化：凡是字段名、坐标、编码这类“猜了就错”的操作，写成脚本让模型只看输出。代码不进上下文，token 成本趋近于零。
4. 依赖前置声明：靠前位置列出运行依赖并要求先检查，把 ModuleNotFoundError 挡在执行路径之外。
5. 验证回路收尾：写完（或填完）必须有一步校验——渲染成图看一眼、或跑校验脚本。没有验证回路的生成型 Skill，等于让模型闭卷交卷。

参考来源

1. anthropics/skills — 官方 Skills 仓库 — document-skills/pdf 的 SKILL.md 与 scripts 目录为本文第一手分析对象（行级引用以仓库当前版本为准）
2. Anthropic Engineering: Equipping agents for the real world with Agent Skills — 渐进披露三层机制与“脚本不进上下文”的 token 经济学出处
3. Claude Code 文档：Skills — description 双句式规范、SKILL.md 体积建议与安装方式
4. mcpservers.org/agent-skills — 官方+社区精选目录，文档处理类目收录情况
5. skillsmp.com — 2300+ Skills 可搜索目录，用于确认 pdf 技能的热度与模仿率观察

说明：本文写作会话中网络抓取工具受限，无法实时复核 Star 数等易变数据，正文已回避精确数字；结构性描述基于官方仓库与官方文档的公开内容，行级引用请以仓库最新版本为准。

[!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 等场景全覆盖。