# 拆官方docx件：先解包再缝回去 > Skills 生态定期观察，本轮第2轮：单件深拆。本次对象是 Anthropic 官方 Skills 仓库里的文档处理头牌，docx。本文观察基于 anthropics/skills 仓库公开内容的写作时点快照，具体文件清单与命令以仓库当前版本为准。 ## 概述 拆一个 Skill，最忌讳只看 SKILL.md 那一层皮。docx 这个官方件恰好是最好的反面教材：它的 SKILL.md 短到让你怀疑这是不是个空壳，但往下挖两层，有参考文档、有 Python 脚本、有一条「新建走 JavaScript、编辑走裸 XML」的诡异分叉。这一期把它拆到脚本参数级，看官方是怎么把「改一个字不动全文排版」这种脏活工程化的。核心结论先给：**这个件的能力不在提示词里，在 unpack.py 和 pack.py 这两个脚本里**；它教 Claude 的不是「怎么写 Word」，而是「Word 是个压缩包，手术要在 XML 上做」。 ## 它是谁：生态位与出处 docx 技能出自 Anthropic 官方仓库 `anthropics/skills`（github.com/anthropics/skills），与 pdf、pptx、xlsx 组成「文档四件套」，后来被归拢到仓库的 document-skills 目录下作为一组插件分发。这个仓库是官方 Skills 的样板间，Star 数在数万量级（实时数据以仓库页面为准），几乎所有第三方 Skills 教程都拿它当参考答案。 文档四件里，docx 是出场率最高的那一个：合同、简历、周报、标书、论文格式修改，人类办公场景里 Word 文档的存量远大于 PPT 和 Excel。这也是为什么它值得单独拆一期——它要处理的问题是所有 Skill 里最脏的：**带复杂格式的存量二进制文档**。 先给一张生态定位图，看它在整个官方体系里的位置： ```mermaid flowchart TD A["anthropics/skills 官方仓库"] --> B["文档四件套"] A --> C["创作类"] A --> D["工程类"] B --> E["docx 本期主角"] B --> F["pdf"] B --> G["pptx"] B --> H["xlsx"] C --> I["skill-creator"] C --> J["canvas-design"] D --> K["mcp-builder"] D --> L["webapp-testing"] ``` ## 仓库地图：三层结构，皮薄馅大 以写作时点的仓库快照为口径，docx 件的目录大致是这样三层： | 层 | 文件 | 角色 | |------|------|------| | 门面 | SKILL.md | 触发 + 工作流调度，百行上下 | | 弹药 | docx-js.md / ooxml.md 两份参考 | 按需加载的深度文档 | | 手脚 | scripts/unpack.py、scripts/pack.py | 解包与回填的确定性操作 | 这个三层结构本身就是官方推荐范式的活教材：**SKILL.md 负责判断，参考文档负责知识，脚本负责动作**。Claude 平时只有那句 description 驻留在上下文里；任务命中才展开 SKILL.md；需要写生成代码时才去读 docx-js.md；需要动存量文档时才碰 ooxml.md 和两个脚本。Token 是按需付费的弹药，不是自来水和平价畅饮。 ## SKILL.md 逐段拆 ### 第一段：frontmatter 里的 description，一句话钓两类鱼 docx 的 description 大意是：全面覆盖文档的创建、编辑与分析，并列出场景清单——从零新建文档、修改已有文档内容、处理修订（tracked changes）、添加批注，以及一切 .docx 相关任务。 这段话的设计值钱在哪？它用编号场景列表把「动词」全埋进去了。用户找 Skill 说的是动词：「帮我**写**一份周报」「帮我**改**这份合同」「给这页**加批注**」。description 里的五个编号，恰好一一对应这五个动词。很多第三方 Skill 的 description 只写「A Word document tool」，名词有了，动词没有，结果就是装了没人叫。官方这行 description 是触发词设计的教科书：**描述里写用户的动词，不写你的技术栈**。 ### 第二段：Workflow 开头的分叉，一票决定走哪条技术路线 SKILL.md 正文的第一件大事不是讲知识，是让 Claude 做一道判断题：**这个任务是新建文档，还是改已有文档？**两条路走的技术栈完全不同： - **新建**：用 docx-js（JavaScript 生态的 docx 生成库）写脚本从零生成。生成前先读 docx-js.md 参考。 - **编辑**：绝不用库去改，而是先用 unpack.py 把 docx 解包成 XML 文件，直接改 XML，再用 pack.py 打回去。涉及修订留痕时另读 ooxml.md。 这个分叉是整个 Skill 最反直觉、也最能体现功力的地方。直觉做法是全程用一个库（比如 python-docx）读写通吃。官方明确不走这条路，理由很实在：**用库改存量文档，等于把文档解析再重建一遍，任何库都没法无损还原 Word 全部格式特性，重建必有损耗**——样式、主题、批注、域代码，丢哪个都是事故。而直接改 XML 是外科手术，只动目标节点，周围组织原样保留。 新建则反过来：反正没有存量要保护，用库从零生成比手写 XML 干净得多，还天然规避了手写标签写错导致文档打不开的风险。 ### 第三段：Reading 流程，读文档也讲究姿势 编辑之前得先读懂文档内容。SKILL.md 给的姿势是把 docx 转成 Markdown 来读，而不是让模型直接啃 XML。这里又是一个「分场景换工具」的细节：**读内容用转换工具，改结构用解包脚本**，两件事用的是两条管线。混着用（比如直接读解包后的 document.xml 找正文）Token 消耗会爆炸，因为 OOXML 里一个段落要裹好几层标签。 ### 第四段：Editing 流程，六步手术法 编辑路径在 SKILL.md 里被拆成清晰的流水线：解包、定位目标 XML、按需读参考、动手改、回填打包、交付。其中「处理修订留痕」（就是 Word 里那个审阅模式）被单独拎出来强调——这不是改内容，而是往 XML 里插入特定标记节点：新增的内容包一层插入标记，删除的内容包一层删除标记（内容本身还在，只是被标记为已删），Word 打开就会正常显示红字修订和拒绝/接受按钮。这是 docx 件里技术含量最高的一段，也让它成了目前 Skills 生态里少见的「能做出 Word 原生修订效果」的自动化方案。 ## 脚本层：两个 Python 文件扛住全部脏活 ### unpack.py：解包 + 整容 docx 本质是个 zip 包，里面躺着一组 XML：文档主体、样式、编号、页眉页脚、主题、批注各占一个文件。unpack.py 做两件事：解压，然后把所有 XML **重排成带缩进的易读格式**——原始 OOXML 经常是几十万字符挤一行的，不整容没法改。 ### pack.py：卸妆 + 回填 这是全 Skill 最精妙的一个文件。它要做的不只是压缩回 zip，还要**先撤销 unpack 阶段加的缩进空白**。为什么？因为 OOXML 的部分位置对空白敏感：标签之间被 pretty-print 塞进去的换行和空格，回填后可能直接混进正文，用户打开文档发现每段之间多了诡异空格，或者文档干脆报损坏。unpack 时为了人眼可读加的每一处空白，打包前必须一粒不剩地擦掉。 这对写 Skill 的人是个当头棒喝：**中间态的人性化和最终态的正确性经常冲突，需要一个专门的脚本负责「卸妆」**。把这个坑用脚本封死，比在提示词里写八遍「注意移除空白」可靠得多——确定性操作交给代码，是 Skills 工程的第一戒律。 ```mermaid flowchart TD A["用户提出 docx 需求"] --> B{"新建还是改存量"} B -->|新建| C["读 docx-js 参考"] C --> D["写 Node 脚本生成"] D --> E["输出新文档"] B -->|编辑| F["unpack.py 解包整容"] F --> G["pandoc 转 MD 读内容"] G --> H{"要留修订痕迹吗"} H -->|要| I["读 ooxml.md 插修订标记"] H -->|不要| J["直接改 XML 节点"] I --> K["pack.py 卸妆回填"] J --> K K --> E ``` ## 四条可抄的设计模式 **模式一：用一道判断题开头，而不是用知识开头。** SKILL.md 先让 Claude 分清新旧文档，再决定加载哪套参考。反面写法是把 docx-js 和 OOXML 知识全塞进 SKILL.md 正文，结果每次触发都烧一遍 Token。判断在先，加载在后。 **模式二：description 埋动词清单。** 前面说过，不重复。补一句：编号列表形式还有个隐藏收益——Claude 能把用户请求映射到编号，直接跳到对应工作流段落。 **模式三：有损区交给库，无损区交给手术。** 新建（没有存量可毁）用高级库图省事，编辑（存量不可毁）下潜到 XML 图精确。工具没有高下，只有适用层。你写自己的 Skill 时先问：这个操作错了会毁掉用户什么？ **模式四：脏活写脚本，不写提示词。** 解压、缩进、卸妆、回填全是代码干的。提示词只负责「该走哪条路」的判断。凡是你发现自己要在提示词里反复叮嘱某个机械步骤，那就是该写脚本的信号。 ## 评测表 按本栏目五维度给 docx 打分，并放入替代方案作对照（替代方案评分为本文口径，供选型参考）： | 维度 | 权重 | 官方 docx 件 | 裸用 python-docx | 裸用 pandoc | |------|------|------|------|------| | 功能完整度 | 25% | ★★★★★ | ★★★☆☆ | ★★☆☆☆ | | 设计质量 | 25% | ★★★★★ | —（非 Skill） | —（非 Skill） | | 实战效果 | 20% | ★★★★☆ | ★★★☆☆ | ★★☆☆☆ | | 上手难度 | 15% | ★★★★★（装即用） | ★★★☆☆ | ★★★☆☆ | | 社区活跃度 | 15% | ★★★★★ | ★★★★☆ | ★★★★★ | 功能完整度给满的理由：新建、编辑、修订留痕、批注四条管线齐活，尤其修订留痕是生态里近乎独一份。实战效果扣一星：长文档、几百页标书级别的操作，XML 会大到需要分片处理，实测有翻车空间；重度复杂表格嵌套也偶有需要人工补刀的情况。 ## 适用与不适用 **适用**：按模板改合同关键条款且不许动排版；给别人的文档留修订记录供对方审阅；批量改样式、改页眉、换封面；从零生成结构规范的报告。 **不适用**：只想读文档内容（一条 pandoc 命令就够，别惊动手术台）；需要把 Word 转成 PDF 排版输出（那是 pdf 件的活）；对 PPT/Excel 的类似需求（装对应的 pptx/xlsx 件，别用 docx 硬转）；以及需要实时协作编辑的场景——它产出的是文件，不是在线协作文档。 ## 安装命令 方式一，官方插件市场（Claude Code 内执行，名称以仓库 README 为准）： ```bash /plugin marketplace add anthropics/skills /plugin install document-skills@anthropic-skills ``` 方式二，手动安装单个 Skill： ```bash git clone https://github.com/anthropics/skills.git cp -r skills/document-skills/docx ~/.claude/skills/docx ``` 装完重启会话，说一句「帮我改这份合同的甲方名称，别动格式」，能触发就通了。 ## 分场景推荐排行 1. **留痕修改存量文档**：docx 件全场第一，无对手 2. **从零生成规范文档**：第一梯队，与裸写 docx-js 相比多了格式护栏 3. **批量格式改造**：第一梯队，解包改样式是降维打击 4. **纯阅读提取**：不值得装，pandoc 更轻 5. **在线协作编辑**：不适用，出门左转各家 API 一个收尾观察：生态里办公类 Skill 上了千个，绝大多数是「调库生成」一个套路，肯下潜到 OOXML 手术层做存量编辑的屈指可数。docx 件示范的这件事——**把文档当压缩包，而不是当对象**——是这期最值得带走的一句话。 ## 参考来源 1. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，docx 件本体（document-skills/docx），本文拆解对象 2. [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic 工程博客，Agent Skills 渐进式披露机制的设计说明 3. [Claude Docs: Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) — SKILL.md 结构与脚本引用的官方文档 4. [skills.sh](https://skills.sh) — Skills 生态榜单站，可查 docx 件的安装量与热门度 5. [docx（OOXML）开放规范](https://agentskills.io) — Agent Skills 开放规范站，Skill 打包格式的标准出处 > [!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 等场景全覆盖。