# 官方docx件拆解：新建改稿两条路 ## 概述 本期是Skills生态拆解系列第2轮，按轮次设定做单件深度拆解。这次开的是Anthropic官方`document-skills`家族里的docx件——2025年10月Agent Skills发布时的门面担当，也是整个生态里被复用、被抄袭、被反向工程最多的文档类Skill之一。本文把它拆到SKILL.md逐段级别：门牌（frontmatter）怎么写、正文里那条「新建与改稿分岔路」为什么是神来之笔、tracked changes（修订痕迹）为什么必须裸写OOXML、哪些知识被外置到了reference文件里。拆完提炼出四个可以直接抄回自己Skill里的设计模式。核心发现先给一句话：**这个件的全部精髓，在于它拒绝让一条技术路线通吃所有文档任务——新建走代码，改稿走裸XML，读内容走pandoc，三条路在SKILL.md开头就钉死了路标。** ## 它是谁：四件套里的老大哥 先交代出身。docx件住在Anthropic官方仓库`anthropics/skills`里，同门一共四个：docx、pptx、xlsx、pdf，合称document-skills家族。这四个件有两重身份： - **对普通用户**：Claude网页版/桌面版里的「文件创建」功能，底层就是这套件在干活。你在claude.ai里说「帮我做个Word」，走的就是这条路。 - **对开发者**：Claude Code里以插件形式安装，本地跑，依赖你机器上的Node.js、Python等工具链。 同门四个件里，pdf件此前已单独拆过一轮（门牌与渐进披露机制），这次不重复那个角度。选docx是因为它有一个兄弟们都不具备的特质：**它是四件套里唯一一个「创建」和「编辑」必须走完全不同技术路线的件**。xlsx可以用openpyxl一条路走到底，pptx有python-pptx伺候，而docx的新建和修改，是两个世界。 这个天然矛盾，逼出了整个Skills生态里教科书级别的一份SKILL.md。 ## 开包看货：一个件的物理构成 先看目录。docx件的文件夹大致是三块东西（以仓库当前版本为准）： | 文件/目录 | 角色 | 什么时候进上下文 | |---|---|---| | SKILL.md | 正文，工作流指令 | 触发时整份读入 | | frontmatter（SKILL.md头部YAML） | name + description门牌 | **常驻上下文，永远在场** | | references/ | OOXML格式说明、修订标记语法等 | 模型按需去读 | | scripts/ | 解包、打包、格式转换的现成脚本 | 模型按需去执行 | 这就是Skills官方设计的「渐进披露」三层结构：门牌永远在场，正文触发才读，附录用到才翻。关于这套门牌机制，此前PDF件拆解已经细讲过，本文不再展开，只强调一个数字账：docx件的门牌description只有几行，但它决定了在几千个Skill同场竞技时，模型会不会在用户说「改一下这份合同」的瞬间想到它。门牌是全场最贵的几行字。 真正值得逐段拆的是正文。往下看。 ## 第一刀：frontmatter——描述里埋的全是扳机 docx件的description，大意是：全面覆盖docx文档的创建、编辑与分析——支持修订痕迹（tracked changes）、批注、格式保留、文本提取；适用于创建新文档、或对既有文档做修改/批注/红线修订的任何场景。 注意它埋了哪些扳机词： 1. **扩展名词**：`.docx`。用户消息里出现文件名时，这是最强触发信号。 2. **场景动词对**：create / edit / analyze，一张口就覆盖三类意图。 3. **杀手锏词**：tracked changes。这个词是法律、咨询、出版行业的行话（红线修订），一个懂行的用户嘴里的自然语言就是「帮我redline一下」。把它直接写进门牌，等于在垂直行业里挂了定向招牌。 4. **否定排除 implied**：描述没有吹「处理一切文档」，而是钉死在「专业文档（professional documents）」——这是个聪明的降误触设计，纯文本、markdown、CSV不该惊动它。 写法上它是第三人称、陈述句，不写实现细节。这是官方skill-creator反复强调的纪律：**门牌写「什么时候用我」，正文才写「怎么用我」**。大量社区件的描述写成功能罗列（「支持XX！支持YY！」），触发率反而差——模型匹配的是任务意图，不是功能清单。 ## 第二刀：正文开头——先立岔路口，再发工具 SKILL.md正文的第一件事，不是介绍docx格式，而是**立决策树**。逻辑大致是： ```mermaid flowchart TD A["用户请求涉及 docx"] --> B{"先判任务类型"} B -->|"从零新建"| C["用 docx-js 写 JS 代码生成"] B -->|"编辑已有文件"| D{"要不要修订痕迹"} B -->|"只需读内容"| E["pandoc 转出 markdown 再读"] C --> F["node 执行脚本产出文件"] D -->|"不要"| G["解包 OOXML 直改 XML"] D -->|"要"| H["裸写 w:ins 与 w:del 修订标记"] G --> I["重新打包成 docx"] H --> I E --> J["以文本形式回答即可"] ``` 这个开头是全文最值钱的设计。为什么？因为docx生态的工具库里全是坑： - **新建**用python-docx也可以，但样式控制繁琐；用pandoc从markdown转，格式精细度不够。官方件选了docx-js——用JavaScript代码描述文档结构，然后生成。好处是**文档即代码**：改个参数重跑一遍就出新版本，样式全部可复算，不会出现「这次生成和上次格式不一样」的玄学。 - **编辑**如果用python-docx一类的库去「读进来改一改再存」，很容易丢格式——库不支持的高级样式、兼容性标记，存盘时就蒸发了。所以正文明令：编辑既有文件一律解包（unzip）、直接改`word/document.xml`、再打包。**XML是唯一无损通道**。仓库还配好了解包/打包脚本，模型不用现场回忆zip命令的细节参数。 - **只读**根本不该解包。内容提取用pandoc转markdown最省事，几十KB的正文直接进上下文回答问题。 三条路对应三种任务，SKILL.md开头就把路口钉死。这不是啰嗦，是纠错：没有这段，模型在「编辑」任务上大概率顺手抄起python-docx就是干，然后用户收到一份格式稀碎的文件。 **可抄模式一：任务有多种技术路线时，把决策树放在SKILL.md物理开头，别让模型自己选路。** ## 第三刀：修订痕迹——最见功力的一段 如果用户要的是「改这份合同，但要保留修订痕迹让律师同事审」，前面的路全断了： - docx-js是生成器，不做修订； - python-docx对tracked changes基本没有像样支持； - pandoc转换会直接丢掉修订元数据。 主流库没有一个能完整写出OOXML的修订标记。官方件的解法非常硬核：**绕过所有库，按OOXML规范裸写修订XML**——用``包裹插入的内容，``包裹删除的内容，直接写进document.xml。这件事在通用编程里属于「没人愿意手干」的脏活，但恰恰是模型擅长的：OOXML修订标记的语法规则是有限、明确、可查的（所以这部分语法说明被放进了references文件，按需翻阅，不占正文篇幅），模型按规则生成XML比人类手写快得多也稳得多。 这一段还有一层容易被忽略的产品哲学：**为什么默认建议tracked changes而不是悄悄改完？**因为文档修订场景的真正用户流程是「AI起草改动 → 人类逐条审阅 → 人类接受或拒绝」。裸改等于剥夺了审阅权，在合同、论文、公文场景是不可接受的。这个件把「保留修订痕迹」写成一等公民路径，等于把「AI别越权」这个价值观焊进了技术路线。 **可抄模式二：当所有现成库都缺一块能力时，别硬凑库，直接写格式底层的标记。Skill里可以教模型干「人类嫌脏、机器擅长」的活。** ## 第四刀：知识外置——正文讲路由，附录讲语法 回头看文件构成就明白了docx件的分工哲学： - **SKILL.md正文**只讲「什么任务走什么路、用什么工具、注意什么坑」——全是决策和控制流； - **references/**放着OOXML格式细节：修订标记语法、批注结构、节/样式的工作方式——全是知识和语法； - **scripts/**放着可执行工具：解包、打包、转换——全是确定性动作。 正文因此能保持在一份「可以整份读入也不心疼」的篇幅内（官方建议SKILL.md正文控制在几百行以内），而OOXML这种动辄上千行的格式规范被外置成按需查阅的附录。模型走到「裸写修订标记」这一步时才去翻语法参考，翻完就写。 这套分工对应一个提示词工程的基本盘：**控制流要常驻，知识要惰性加载**。很多社区件把格式教程全文塞进SKILL.md，结果触发一次烧一次token，还稀释了关键指令的注意力权重。docx件是反面教材的反面。 **可抄模式三：把「如果…就…」留在正文，把「什么是…」扔进references，把「照着跑」做成scripts。** ## 什么时候用它，什么时候别用 **适用**： - 对既有docx做保真修改——尤其是格式复杂、库一碰就碎的正式文件； - 合同/协议/公文的红线修订，需要人审的协作流； - 从结构化描述或markdown批量生成正式文档（周报、方案、简历）； - 从docx里提取内容做问答或再加工。 **不适用**： - 纯内容提取——直接`pandoc file.docx -o out.md`一行命令的事，惊动整个件属于杀鸡用牛刀； - 追求视觉设计的海报、宣传单——那是canvas-design和pptx件的领地，Word的排版模型天然不适合自由设计； - 加密、损坏或扫描件转出来的脏docx——OOXML直改救不了文件本身的问题。 ## 评分表（对照通用评测维度） | 维度 | 权重 | 评分 | 短评 | |---|---|---|---| | 功能完整度 | 25% | ★★★★★ | 建/改/读/修订四路全通，批注处理也有覆盖 | | 设计质量 | 25% | ★★★★★ | 分岔路由+知识外置，官方门面级写法 | | 实战效果 | 20% | ★★★★☆ | 格式保真和红线修订是真实生产力；重度排版仍需人工兜底 | | 上手难度 | 15% | ★★★★☆ | Claude应用内零配置；本地CLI需自备Node/Python环境 | | 社区活跃度 | 15% | ★★★★☆ | 官方仓库持续维护，随产品迭代升级 | 安装与使用（可复制）： ```bash # 通用装法：克隆官方仓库，把 docx 目录整个拷进个人技能目录 git clone https://github.com/anthropics/skills.git # 仓库内用 find 定位 docx 目录（可能在 document-skills/ 或 example-skills/ 下） find skills -type d -name docx cp -r <找到的docx目录> ~/.claude/skills/ # Claude Code 插件装法（据仓库 README）：会话内执行 /plugin marketplace add anthropics/skills # 然后按 /plugin 面板提示安装 document-skills # 市场热度速查 npx skills find docx ``` 装好后不用背任何命令，对话里直接说「把这份合同改成乙方付款周期30天，保留修订痕迹」即可触发。Claude网页版用户无需安装，文件创建功能内置。 ## 排行榜：谁该装 1. **法务/咨询/销售运营**——红线修订场景天花板，五星必装； 2. **每周产Word格式交付物的打工人**（方案、周报、标书）——一次配置长期回本； 3. **Claude Code重度用户**——配合同门xlsx/pptx件组成本地文档流水线； 4. **只想读docx的人**——不必装，学它的pandoc命令就够了； 5. **纯设计需求者**——绕行，去隔壁canvas-design。 ## 结语：这个件教会生态的三件事 把docx件拆到底，它其实只示范了三件事：**在多条技术路线面前替模型做选择，而不是赌模型选对；在库的能力边界外敢教模型裸写底层格式；在正文篇幅和知识完备性之间用附录做交换。**这三件事没有一件依赖docx本身——写代码评审件、写数据清洗件、写部署件的人，抄走的都该是这套骨架，而不是那些XML标签。 ## 参考来源 1. [anthropics/skills — GitHub官方Skills仓库](https://github.com/anthropics/skills) — document-skills家族（docx/pdf/pptx/xlsx）所在地，本文拆解对象的原始出处，具体文件以仓库当前版本为准 2. [Introducing Agent Skills — Anthropic](https://www.anthropic.com/news/skills) — 2025年10月Agent Skills发布公告，Skills机制与文件创建功能的官方说明 3. [Equipping agents for the real world with Agent Skills — Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — 渐进披露三层结构与SKILL.md写法约束的官方工程阐述 4. [Claude Code文档：Skills](https://code.claude.com/docs/en/skills) — Skills目录结构（~/.claude/skills）、frontmatter字段与插件安装方式的官方文档 > [!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 等场景全覆盖。