# 拆官方pdf件：官方写法六条配方 ## 概述 这是本栏目第 8 轮定期观察。前七轮把热门件拆了一圈：去味的、造PPT的、部署的、审查的，基本扫完。本期不追新榜（想看实时热度的，文末给了四个目录站入口），回头补一门基础课——把官方文档件里本栏目唯一没单独拆过的 **pdf 件**拉出来解剖。目的不是评它好不好用，而是把它当官方的“考场范文”：官方四件（docx/xlsx/pptx/pdf）共用同一套写法骨架，拆透一件，就等于拿到了官方写 SKILL.md 的固定配方。本期产出是一张「六条配方卡」，照着抄，30 分钟能写出你的第一件 Skill。 --- ## 为什么是官方件，为什么是 pdf 先交代生态坐标。Skills 聚合目录 skillsmp.com 自述收录已超 2300 件，skills.sh、skillsdirectory.com、mcpservers.org/agent-skills 各自维护着热门榜——社区件的写法五花八门：有的全靠一段描述撑场面，有的塞进一百节课的内容量，有的正文写得比散文还抒情。水平参差的同时，一个事实常被忽略：**官方仓库 anthropics/skills 里躺着一批“标准答案”**，而且大部分人电脑里已经装了——如果你在 Claude Code 里装过官方示例插件，技能清单里那组 `example-skills:pdf`、`example-skills:docx`、`example-skills:xlsx`、`example-skills:pptx`，就是它们。 本栏目此前拆过同门的 docx（坑位刻成 CRITICAL）和 xlsx（交付写成合同），pptx 和 pdf 一直没单独动过。这次选 pdf，理由有三： 1. **它最小**。四件里功能面最窄（不处理 Office 那些复杂的样式继承），正文干净，适合第一次逐行读； 2. **它最能体现“分工表”写法**。PDF 处理天然分裂成读、写、改三种互斥操作，官方被迫在正文里写清“什么情况用哪个工具”——这正是社区件最缺的东西； 3. **它是四件里唯一“纯脚本驱动”的**。PDF 没有像 docx/xlsx 那样需要精细保留的富格式，几乎所有操作都走 Python 库，最能示范“确定性动作下沉到 scripts/”这条官方铁律。 --- ## pdf 件是什么，怎么装 **定位**：官方 PDF 处理件，覆盖四类高频操作——表单填写、文本与表格提取、多件合并/拆分、从零生成新 PDF。它不碰 OCR 重活，扫描件这种“没有文字层”的输入会被明确划出边界。 **安装**（二选一）： ```bash # 方式一：从官方仓库手动安装 git clone https://github.com/anthropics/skills.git cp -r skills/document-skills/pdf ~/.claude/skills/pdf # 方式二：插件用户直接在 Claude Code 里 /plugin 搜索官方示例包 # 本机环境即以 example-skills 插件形式内置 pdf/docx/xlsx/pptx 等官方件 ``` > 仓库目录结构以 anthropics/skills 当前版本为准；若路径有调整，进仓库看 README 即可定位。 --- ## 解剖：官方件的公共骨架 先看骨架，这是六条配方的地基。官方文档件通用三层结构，pdf 件同款： ``` pdf/ ├── SKILL.md # 门牌 + 工作流：模型进场必读的那一页 ├── scripts/ # 确定性动作：填表单、抽取、合并，直接执行的脚本 └── references/ # 深知识：格式细节、字段规范，用到才加载 ``` 这套结构对应的加载模型，官方叫**渐进披露（progressive disclosure）**，分三层发生： | 层 | 加载内容 | 时机 | 大小感受 | |---|---|---|---| | 第一层 | name + description（frontmatter） | 每次会话常驻 | 一两行 | | 第二层 | SKILL.md 正文 | 触发该 Skill 时 | 一页纸以内 | | 第三层 | scripts/ 与 references/ | 执行到对应步骤才读 | 不设上限 | 为什么这么设计？因为上下文窗口是全场最贵的资源。描述行常驻意味着**每多写一个字，所有会话都在付利息**；而 references 里的东西平时一个 token 都不占。官方把这个账算在了文件结构里——社区件常见反例是把 800 行教程全塞进 SKILL.md，等于强制每个用户进场先交 800 行学费。 --- ## 官方配方六条 以下六条是拆完骨架后提炼的写法规矩，每条给“官方怎么做 → 为什么 → 你怎么抄”。 ### 配方一：描述行写触发场景，不写功能口号 官方件的 frontmatter 极简，name + description 两行，但 description 的写法有讲究：它不是功能介绍，是**触发器**——把“用户会怎么提到这件事”写进去（如“当需要填写 PDF 表单、提取 PDF 内容、合并 PDF 文件时使用”）。模型靠这句话决定要不要唤醒你，写“强大的 PDF 工具”没有用，写“用户提到 PDF 表单、提取、合并时”才有用。本栏目此前有一篇专讲描述行决定生死的文章，此处只提醒一句：抄官方时先抄这一行的心态——**描述是写给模型的选择器，不是写给用户的广告**。 ### 配方二：正文只装流程，不装知识 SKILL.md 正文里官方放的是“做什么、按什么顺序做”，而“PDF 规范里字段怎么编码”这类稳定知识全部下沉到 references/。判断标准很简单：**会变的写正文，不会变的写参考**。你抄的时候可以做个物理动作——把草稿里所有“背景知识”段落剪贴出去，正文剩下的如果还能跑通流程，就对了。 ### 配方三：确定性动作写成脚本，别写成段落 这是 pdf 件最值得学的一条。合并两个 PDF 有唯一正确做法（调库、传参、保存），这种事写一百字散文让模型现场发挥，不如给一个能直接跑的脚本。官方把这类动作放进 scripts/，正文中只留一句“执行某某脚本完成某某步骤”。好处三重：省 token、可复用、出错范围可控。**正文是写给模型的，脚本是写给机器的——混着写是最常见的新手错误。** ### 配方四：多工具先给分工表，再谈操作 PDF 处理要动用多个 Python 库，官方的做法不是散文式介绍每个库，而是给一张决策表：读版面文本和表格用 pdfplumber，做合并拆分和表单字段操作用 pypdf，从零生成新 PDF 用 reportlab（以仓库当前版本为准）。三个“什么情况→用什么”，模型照表执行，不会拿着生成库去干提取的活。你的 Skill 只要涉及“多选一”，照抄这张表的格式：**两列，左边条件，右边动作。** ### 配方五：把禁止事项写成硬约束，越痛写得越重 同门 docx 件把踩过的坑刻成大写 CRITICAL（第 3 轮拆过），pdf 件同款思路：易错点（比如“别对加密 PDF 硬解”）用显著标记顶格写。这不是官方有仪式感，是血泪教训的格式化——模型对散落的“注意”会视而不见，对顶格大写不会。你抄的时候，规则是：**踩过一次坑，就升级一条硬约束，别让它退化为正文里的一句备注。** ### 配方六：留好失败出口 官方件不假设世界完美：扫描件没有文字层怎么办、大文件怎么分页处理、字段抽不出来怎么报告——这些“走不下去的路”在正文里有明确指引。社区件几乎不写这个，于是一遇边界就即兴发挥。你的第一件也照此办理：**每条工作流步骤后面问自己一句“这步失败了模型该干嘛”，有答案再发布。** --- ## 30 分钟照方抓药：你的第一件 拿六条配方直接走一遍。目标：写一个「发票 PDF 归档器」。 **第 1 步（配方一）**——建目录，写门牌： ```markdown --- name: invoice-sorter description: 批量整理发票PDF：按供应商分类、抽取金额与日期、重命名归档并生成周报。 当用户提到发票整理、报销归档、批量处理发票PDF时使用。 --- ``` **第 2 步（配方二、四）**——正文只写流程，第一段就是分工表： ```markdown # 工作流 1. 扫描输入目录，列出全部PDF，跳过非PDF文件并登记 2. 判断文件类型：有文字层 → 走提取；无文字层（扫描件）→ 记入待OCR清单，不处理 3. 文本提取用 pdfplumber，只取供应商、金额、日期三个字段 4. 按执行 scripts/sort_invoices.py 完成重命名与归档 5. 汇总生成 invoices_report.md，向用户报告处理数、跳过数、失败数 ``` **第 3 步（配方三）**——归档逻辑封装成 `scripts/sort_invoices.py`，正文不解释 Python 怎么写。 **第 4 步（配方五、六）**——文末追加两行硬约束：`金额字段缺失时禁止猜测，标记为待人工确认`；`禁止修改原始文件，只做复制归档`。 **第 5 步**——找一个真实发票目录跑三遍，每跑一遍把新踩的坑升级成硬约束。跑完这三遍，你的第一件就出厂了。 --- ## 评测表 **pdf 件五维评定**（本栏目基于官方件结构与社区反馈的设计视角评定，非量化实测）： | 维度 | 评分 | 一句话点评 | |---|:---:|---| | 功能完整度 | ★★★★☆ | 表单/提取/合并/生成全覆盖，OCR 明确划出边界 | | 设计质量 | ★★★★★ | 分工表+脚本化+渐进披露，官方写法教科书 | | 实战效果 | ★★★★☆ | 常规 PDF 任务稳定，重排版式提取仍依赖原文质量 | | 上手难度 | ★★★★☆ | 装完即用；自定义脚本需会一点 Python | | 社区活跃度 | ★★★★ | 官方仓库维护，随 Claude Code 版本迭代 | **官方四件写法侧重对照**： | 件 | 管什么 | 写法上最值得抄 | |---|---|---| | docx | Word 读写 | 踩坑记录升级成 CRITICAL 硬约束 | | xlsx | Excel | 交付前验证清单，合同式收尾 | | pptx | 幻灯片生成 | 模板与排版规则分离（本栏目未单独拆过，以官方仓库说明为准） | | pdf | 表单/提取/合成 | 工具分工表 + 三层渐进披露骨架 | --- ## 官方配方的决策流 ```mermaid flowchart TD A["想清楚触发场景"] --> B["写frontmatter描述"] B --> C{"正文会超过一页吗"} C -->|不会| D["流程全写进SKILL.md"] C -->|会| E["知识下沉references目录"] D --> F{"动作是确定性的吗"} E --> F F -->|是| G["封装成scripts脚本"] F -->|否| H["写成编号工作流"] G --> I["多选一处补分工表"] H --> I I --> J["写明失败出口与硬约束"] J --> K["真实任务跑三遍再发布"] ``` --- ## 推荐排行榜 **榜一：官方配方性价比排行**（按见效速度） 1. 描述行写触发场景——十分钟改完，直接决定你的件会不会被叫起来 2. 工具分工决策表——两列表格，消灭一半的模型即兴发挥 3. 编号工作流——把“怎么做”变成照单执行 4. 确定性动作脚本化——省 token，也省排查时间 5. 失败出口——边界场景不再翻车 6. 三层楼拆分——件长大到一页装不下时再做，别一开始就过度工程 **榜二：写第一件前该读的三份材料** 1. 官方 pdf 件——最小最干净的工程范本，本篇主角 2. 官方 skill-creator——官方写法自述，等于配方官方说明书（注意你环境里可能同时装着好几份同名件） 3. planning-with-files——社区爆款的文件化思路对照（2026 年 5 月本专栏存档记录为 17,700+ 星，现值以仓库为准） --- ## 参考来源 1. [anthropics/skills 官方 Skills 仓库](https://github.com/anthropics/skills) — 官方文档四件与示例件所在地，本文骨架与配方依据，目录结构以仓库当前版本为准 2. [本专栏第 1 轮存档（output/2026-05-16/skills-ecosystem-1600.md）](https://github.com/anthropics/skills) — 2026 年 5 月生态数据与 Planning With Files、Humanizer、Impeccable 等原始测评记录 3. [planning-with-files](https://github.com/OthmanAdi/planning-with-files) — 存档中 5 月单件星标最高的社区件，本文“文件化思路”对照案例 4. [skills.sh](https://skills.sh) — Skills 生态热门榜自查入口，实时热度以站内为准 5. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — 官方与社区件的精选目录，可交叉验证各件收录情况 > [!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 等场景全覆盖。