# 官方 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 | docx | pptx | xlsx | |---|---|---|---|---| | 功能完整度 25% | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | | 设计质量 25% | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★ | | 实战效果 20% | ★★★★☆ | ★★★★☆ | ★★★★ | ★★★★ | | 上手难度 15% | ★★★★★ | ★★★★ | ★★★☆ | ★★★★ | | 社区活跃度 15% | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | 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 的核心机制：元数据常驻，正文按需，脚本按需执行）： ```mermaid 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 ``` 表单任务的内部闭环： ```mermaid flowchart LR S["收到填表任务"] --> T["脚本列出全部表单字段"] T --> U{"字段可交互填充？"} U -->|是| V["fill_form.py 写入键值"] U -->|否| W["按坐标用 reportlab 叠写"] V --> X["check_borders 校验边框对齐"] W --> X X --> Y["视觉复核输出稿"] ``` ## 安装命令 ```bash # 方式一：手动安装（任何 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 ``` 依赖安装（脚本运行需要）： ```bash pip install pypdf pdfplumber reportlab ``` 装完无需配置。直接说“把这份 PDF 里的表格提取出来”即可触发；本环境属于内置插件（`example-skills:pdf`），开箱即用。 ## 适用与不适用 **适用**：文本/表格提取、多文件合并拆分、官方表单批量填写（申请表、报关单、问卷）、扫描件的内容理解（视觉通道）、按模板生成报告型 PDF。 **不适用**：加密或带权限限制的 PDF 的破解（技能不做、也不应做）；超大体积扫描件的全文 OCR（外部 OCR 引擎更稳，视觉通道按页读有成本）；像素级印刷排版（LaTeX/InDesign 仍是正解）；带法律签章文件的再加工（有合规风险，需人工复核）。 ## 排行榜 | 榜单 | 排名 | 说明 | |---|---|---| | 综合推荐 | 1. pdf 2. docx 3. xlsx 4. pptx | pdf 的决策树最干净 | | 二次开发参考价值 | 1. pdf 2. docx 3. pptx 4. xlsx | 阅读阶梯+脚本优先，最值得抄 | | 新手友好度 | 1. pdf 2. xlsx 3. docx 4. pptx | 依赖最少、失败路径最明确 | | 社区模仿率 | pdf / docx 并列 | 各聚合站文档类目的公共原型 | ## 照着写一个：五条可复制模式 1. **双句式 description**：第一句罗列能力动词，第二句以 "When Claude..." 写触发条件。写完自测：用三种不同说法描述同一个需求，看能否都命中。 2. **阶梯化正文**：任何“处理 X”类技能，先问失败路径——默认方案、复杂方案、兜底方案各是什么，按此顺序写，别按工具文档的顺序写。 3. **易错步骤脚本化**：凡是字段名、坐标、编码这类“猜了就错”的操作，写成脚本让模型只看输出。代码不进上下文，token 成本趋近于零。 4. **依赖前置声明**：靠前位置列出运行依赖并要求先检查，把 `ModuleNotFoundError` 挡在执行路径之外。 5. **验证回路收尾**：写完（或填完）必须有一步校验——渲染成图看一眼、或跑校验脚本。没有验证回路的生成型 Skill，等于让模型闭卷交卷。 ## 参考来源 1. [anthropics/skills — 官方 Skills 仓库](https://github.com/anthropics/skills) — document-skills/pdf 的 SKILL.md 与 scripts 目录为本文第一手分析对象（行级引用以仓库当前版本为准） 2. [Anthropic Engineering: Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — 渐进披露三层机制与“脚本不进上下文”的 token 经济学出处 3. [Claude Code 文档：Skills](https://code.claude.com/docs/en/skills) — description 双句式规范、SKILL.md 体积建议与安装方式 4. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — 官方+社区精选目录，文档处理类目收录情况 5. [skillsmp.com](https://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 等场景全覆盖。