--- title: "MiniMax Office Skill 实战：让 AI 生成「能交付」的文档" author: deletexiumu pubDatetime: 2026-03-28T00:30:00+08:00 featured: false draft: false tags: - Claude Code - AI 工具 - 教程 description: "MiniMax 开源了 4 个 Office Skill（PPT/Excel/Word/PDF），我装进 Claude Code 实测了三种格式、拆了源码看架构，记录效果、踩坑和可复用的 Skill 设计模式。" --- ![MiniMax Office Skill 实战封面](/blog/minimax-office-skill-practice/cover.jpg) ## 为什么要看这个 Repo 3 月 22 日，MiniMax 开源了一个 Skills 仓库（MIT 协议），开源后数日内 GitHub 星标快速涨到 6K+。仓库里有 14 个 Skill，其中 Office 部分覆盖了 PPT、Excel、Word、PDF 四种格式。 社区的热度我看到了，但转述没意义。我把四个 Office Skill 装进 Claude Code，拆了源码看架构，三种格式各跑了一遍实测（Word 需要 .NET SDK 8.0+，本次基于源码分析）。这篇文章记录两件事： 1. **实测每种格式的生成效果**——能用到什么程度，哪些场景翻车 2. **拆源码看 Skill 怎么写才算生产级**——从四个 Skill 里提炼出可复用的设计模式 PPT、Excel、PDF 章节的结论来自一手实测，代码和截图均可复现；Word 章节为源码分析，外部用户评价仅作旁证。 --- ## 安装与环境准备 ### 仓库结构 MiniMax Skills 仓库包含 14 个独立 Skill，Office 相关的有四个： | Skill | 用途 | 技术栈 | 额外依赖 | |-------|------|--------|----------| | `pptx-generator` | PPT 生成与编辑 | PptxGenJS (Node.js) | Node.js | | `minimax-xlsx` | Excel 生成与编辑 | 纯 Python + XML | Python 3 | | `minimax-docx` | Word 文档生成 | .NET OpenXML SDK | **.NET SDK 8.0+** | | `minimax-pdf` | PDF 生成 | ReportLab + Playwright | Python 3 + Node.js | ### Claude Code 安装 ```bash # 方式一：通过 plugin marketplace 安装（推荐） claude plugin marketplace add https://github.com/MiniMax-AI/skills claude plugin install minimax-skills # 如需手动克隆（调试或离线场景） git clone https://github.com/MiniMax-AI/skills.git /tmp/minimax-skills # 然后参考仓库 README 中各平台的集成说明 ``` 安装后在 Claude Code 的对话中提及 "PPT"、"Excel" 等关键词，如果 Skill 正确加载，agent 会自动按照 SKILL.md 的流程工作。 ### Cursor 安装 ```bash git clone https://github.com/MiniMax-AI/skills.git ~/.cursor/minimax-skills ``` 然后在 Cursor 设置中将 skill 目录添加为上下文来源。 ### 依赖检查 四个 Skill 的运行时依赖差异很大：PPT 只需要 Node.js，Excel 只需要 Python，门槛最低。PDF 需要 Python + Node.js + Playwright（会下载 Chromium），体积较大但自动化程度高——`make.sh fix` 一行命令搞定。Word 是唯一需要 .NET SDK 8.0+ 的，部署成本最高（只装 Runtime 不够，工作流使用 `dotnet run` 编译运行 C# 脚本）。 ```bash # PDF skill 提供了一键环境检查 cd /tmp/minimax-skills/skills/minimax-pdf bash scripts/make.sh check # 检查依赖 bash scripts/make.sh fix # 自动安装缺失依赖 ``` 踩坑提醒：如果 `~/.claude/skills` 本身是 symlink（比如通过 iCloud 同步），手动安装时生成的 symlink 可能因双层引用导致路径解析失败。遇到 "unknown skill" 错误时，检查 symlink 指向是否正确。 --- ## PPT 实战与源码拆解 ### 源码架构 PPTX Skill 的 SKILL.md 有 249 行，外加 5 个 reference 文件（约 1,500 行）。它的核心不是"怎么调 API"，而是一套完整的设计系统： **Design System（设计系统）**：定义了 5 色调色板——`primary`、`secondary`、`accent`、`light`、`bg`，所有幻灯片必须从这五个 token 取色。换一套色板，整个 PPT 的风格跟着变。 **Slide Taxonomy（页面分类）**：把幻灯片分成 5 种标准类型——封面（Cover）、目录（TOC）、章节分隔（Section Divider）、内容（Content）、总结（Summary）。每种类型有独立的布局规范和代码模板。 **Style Recipes（风格配方）**：4 种视觉风格——Sharp（直角、高对比）、Soft（微圆角、柔和）、Rounded（大圆角）、Pill（胶囊形）。风格配方控制所有形状的圆角、边框、阴影参数。 **Theme Contract（主题契约）**：强制所有 slide JS 文件接受同一个 `theme` 对象： ```javascript const theme = { primary: "22223b", // 最深色，用于标题 secondary: "4a4e69", // 次深色，用于正文 accent: "9a8c98", // 强调色 light: "c9ada7", // 浅色装饰 bg: "f2e9e4" // 背景色 }; ``` 这个设计的好处是：换风格 = 换一个 theme 对象，所有幻灯片自动适配。 **并行生成**：SKILL.md 明确标注支持子代理每次最多 5 张幻灯片并行生成，每个子代理拿到 theme 对象和 slide type 规范后独立工作。 **QA 流程**：生成完毕后必须跑 QA 检查，`pitfalls.md` 里列了常见错误清单（颜色格式、字体回退、页码徽章遗漏等）。 ### 实测 测试场景：生成 3 页产品介绍 PPT（封面 + 目录 + 架构总览）。 ![PPT 封面效果](/blog/minimax-office-skill-practice/slide-1.png) ![PPT 目录页效果](/blog/minimax-office-skill-practice/slide-2.png) ![PPT 架构页效果](/blog/minimax-office-skill-practice/slide-3.png) 生成结果：布局清晰，风格统一，卡片式架构页视觉效果不错。Theme Contract 确实起了作用——三页之间的配色完全一致，不像没有 Skill 时 AI 会在不同页面随意换色。 技术栈用的是 PptxGenJS 4.0.1，每页一个 JS 文件，最后由 `compile.js` 合并输出。这个"每页一个文件"的设计天然适合并行生成。 ### 发现 **效果好的场景**：结构化内容（产品介绍、技术架构、季度汇报）+ 需要品牌统一风格的场景。Design System 的约束让 AI 不会在配色上失控。 **效果差的场景**：有开发者在实测后指出，对于步骤复杂、顺序敏感的任务，agent 容易漂移——"the agent starts doing whatever it likes"（@accelerate27）。这不是 Skill 本身的问题，而是长序列任务中 LLM 的注意力衰减。PPT 页数越多，后面的页面越容易偏离最初的设计规范。 **已知问题**：LibreOffice 渲染中文字体时可能出现方块，PowerPoint 和 Keynote 正常。这是字体嵌入的问题，不影响实际使用。 --- ## Excel 实战与源码拆解 ### 源码架构 XLSX Skill 的设计决策是整个仓库里最激进的：**完全跳过 Python Excel 库，直接操作 XML**。 理由很明确：openpyxl 在读取再写回 .xlsx 文件时，会静默丢失 VBA 宏、数据透视表、迷你图等高级功能。这个丢失是无声的——文件能打开，数据看起来正常，但高级功能已经没了。发给客户才发现问题，为时已晚。 MiniMax 的做法是把 .xlsx 当作 zip 包处理（因为它本质上就是）： ![Excel XML 直操作流程](/blog/minimax-office-skill-practice/xlsx-flow.jpg) ``` .xlsx 文件 ↓ 解压 XML 文件集合（xl/worksheets/sheet1.xml, xl/styles.xml, ...） ↓ 定向编辑目标 XML 节点 ↓ 重新打包 .xlsx 文件 ``` 为此，他们构建了 10 个独立的 Python 工具脚本，核心包括： | 脚本 | 功能 | |------|------| | `xlsx_reader.py` | 结构发现（sheet 列表、单元格内容） | | `xlsx_unpack.py` / `xlsx_pack.py` | 解压与打包 .xlsx | | `xlsx_add_column.py` | 添加列（自动复制相邻列的公式、格式、样式） | | `xlsx_insert_row.py` | 插入行（自动偏移后续行、更新 SUM 公式） | | `xlsx_shift_rows.py` | 行偏移（内部被 insert_row 调用） | | `formula_check.py` | 公式静态验证 | | `libreoffice_recalc.py` | 动态重算验证（需要 LibreOffice） | | `shared_strings_builder.py` | 共享字符串表构建 | | `style_audit.py` | 样式审查 | 还有一条硬规则写在 SKILL.md 里：**所有衍生值必须是 Excel 公式**。 ```xml SUM(B2:B9) 790000 ``` 以及财务色彩标准：蓝色 = 手工输入，黑色 = 公式计算，绿色 = 跨表引用。这套配色是财务建模领域的行业惯例。 ### 实测 测试场景：生成一份季度收入报表，包含四个季度的数据、SUM 汇总公式、冻结首行、财务色彩。 ![Excel 生成结果](/blog/minimax-office-skill-practice/xlsx-result.png) 验证结果： - 公式正确计算：150000 + 180000 + 210000 + 250000 = 790000 ✅ - 财务色彩标准：手工输入值为蓝色字体 ✅ - `formula_check.py` 验证通过 ✅ - LibreOffice 和 Excel 都能正常打开 ✅ 一个意外收获：我尝试用 openpyxl 读取 MiniMax 模板生成的文件，结果 `styles.xml` 解析失败（Fill 解析出错）。这恰好验证了 MiniMax 选择绕开 openpyxl 的决策——MiniMax 使用了更丰富的 OOXML 样式定义，而 openpyxl 只支持其子集。文件在 Excel 和 LibreOffice 中完全正常。 ### 踩坑 有用户（@xingkaixin）在 berryxia 的帖子下留言："尝试了多次，就没有成功做出一个可以成功打开的 Excel 文件。"这类问题的可能原因： 1. **XML 模板中的注释干扰**：MiniMax 模板的 XML 里有大量教学性注释，某些解析器可能被 `` 标签内部的注释干扰。建议清理注释后再打包。 2. **解压-打包流程中间步骤遗漏**：XML 直操作的流程比调库复杂，任何一步出错（比如 `[Content_Types].xml` 缺失）都会导致文件损坏。 3. **环境问题**：Python 版本或脚本路径配置不对。 XML 直操作是一把双刃剑：天花板高，但地板也低。 --- ## Word 实战与源码拆解 ### 源码架构 DOCX Skill 是四个 Office Skill 里规模最大的：274 行 SKILL.md + 18 个 reference 文件（共 15,297 行）。Samples 目录共有 16 个 `.cs` 文件，其中 AestheticRecipeSamples 系列文件承载了 13 套审美配方，另有 11 个功能主题样例文件（表格、图片、页眉页脚、修订标记等）。 **选型决策**：放弃社区最常用的 python-docx，选择 .NET OpenXML SDK。 python-docx 轻量好用，但在嵌套表格、多级目录、页眉页脚精确控制、修订记录这些场景上力不从心。MiniMax 的判断是：**文档质量比部署便利更重要**。代价是需要 .NET SDK 8.0+ 环境，部署复杂度显著上升。 **三条管线**： ``` 用户任务 ├─ 没有输入文件 → Pipeline A: CREATE（从零创建） └─ 有输入 .docx ├─ 替换/填充/修改内容 → Pipeline B: FILL-EDIT └─ 重新排版/套模板 → Pipeline C: FORMAT-APPLY ``` **13 个审美配方**（AestheticRecipeSamples 系列文件）：每个配方对应一种权威文档风格，包含精确的字号、行距、边距、字体参数： - **ModernCorporate** — 现代企业风格 - **AcademicThesis** — 学术论文 - **ExecutiveBrief** — 执行摘要 - **ChineseGovernment** — GB/T 9704 公文标准 - **MinimalModern** — 极简现代风格 - **IEEE Conference** — IEEE 会议论文 - **ACM sigconf** — ACM 论文格式 - **APA 7th / MLA 9th / Chicago** — 各大引用格式 - **Springer LNCS / Nature / HBR** — 权威期刊风格 这些不是"大概像"的模板，而是从官方风格指南中提取的精确参数值。 **验证管线**是强制的（Scenario C）： ```bash # 1. 合并运行（消除碎片化的 run） $CLI merge-runs --input doc.docx # 2. XSD 结构检查 $CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd # 3. 业务规则检查 $CLI validate --input doc.docx --business ``` XSD 验证失败时，先自动修复元素顺序（`fix-order`），再重验。两次都失败才回退到预览人工确认。 **OpenXML 元素顺序敏感**：这是 DOCX Skill 反复强调的一点。`w:p` 里必须 `pPr` 在前、runs 在后；`w:tbl` 里必须 `tblPr` → `tblGrid` → `tr`。顺序错了文件直接损坏，Word 拒绝打开。 **CJK 排版**：单独的 `cjk_typography.md`，覆盖了中文字号映射（初号=42pt、小初=36pt...）、RunFonts 的东亚/ASCII/复杂文种分别指定、GB/T 9704 公文排版标准。 ### 实测说明 由于 .NET SDK 未安装，本次未做实际生成测试。但从源码和 C# 样例文件的质量来看，这是四个 Skill 中投入最大的一个。有用户（@bailanluo）实测后评价："docx 的 skill 明显优于市场上其他公开方案，其可控度比 python-docx 高多了......AI 协助你的 docx 完成度更高。" 如果你的场景涉及中文公文、学术论文、或需要精确控制页眉页脚和修订记录，这个 Skill 值得投入 .NET SDK 的部署成本。 --- ## PDF 实战与源码拆解 ### 源码架构 PDF Skill 的亮点是双引擎架构： | 组件 | 引擎 | 负责 | |------|------|------| | 封面 | HTML + CSS → Playwright 渲染 | 视觉设计（渐变、字体、布局） | | 正文 | Python ReportLab | 结构化内容（段落、表格、图表） | | 合并 | pypdf | 拼接封面和正文为完整 PDF | 分工的原因是：纯 Python 方案很难做出有设计感的封面。HTML+CSS 在视觉表达上远超 Python 绘图库。而正文部分恰好相反——ReportLab 对段落、表格、分页的控制精度比 HTML 转 PDF 更高。两个引擎各做擅长的部分。 **15 种文档类型**，每种有独立的封面模板和视觉风格： | 类型 | 封面风格 | 视觉特征 | |------|----------|----------| | `report` | fullbleed | 深色背景 + 点阵纹理 + Playfair Display | | `proposal` | split | 左面板 + 右侧几何图形 + Syne | | `resume` | typographic | 放大首字 + DM Serif Display | | `academic` | typographic | 浅色背景 + 古典衬线 + EB Garamond | | `terminal` | terminal | 近黑背景 + 网格线 + 等宽字体 + 霓虹绿 | | ... | ... | ... | **Token 设计系统**：从文档类型衍生出颜色、字体、间距等 design token，贯穿封面和正文所有页面。`palette.py` 负责生成这套 token。 ### 实测 运行 `make.sh demo`（report 类型，fullbleed 封面），生成了 8 页 PDF（1 封面 + 7 正文），205KB。 ![PDF 封面效果](/blog/minimax-office-skill-practice/pdf-cover.png) ![PDF 正文效果](/blog/minimax-office-skill-practice/pdf-body.png) ![PDF 图表效果](/blog/minimax-office-skill-practice/pdf-chart.png) 封面的设计感是实打实的——深色背景、Playfair Display 字体、点阵纹理装饰，这个质量纯靠 Python 绘图库达不到。正文包含 callout 框、数据表格、柱状图、饼图，图表由 matplotlib 本地渲染，无需外部服务。 PDF Skill 的入门体验在四个 Skill 中是最好的： ```bash bash scripts/make.sh check # 检查环境 bash scripts/make.sh fix # 自动修复依赖 bash scripts/make.sh demo # 跑一个完整 demo ``` 三行命令从零到看见效果。其他三个 Skill 缺少这种快速体验入口。 ### 注意区分 社区有人反馈"PDF 转 MD，整篇都给我瞎编"——这里需要区分：PDF **生成**和 PDF **解析/转换**是两回事。这个 Skill 做的是生成，不是 OCR 或格式转换。把已有 PDF 转成 Markdown 是另一个问题域，跟这个 Skill 的能力范围无关。 --- ## Skill 设计模式提炼 ![四大设计模式](/blog/minimax-office-skill-practice/design-patterns.jpg) 拆完四个 Skill 的源码，几个跨 Skill 的共性模式浮出水面。这些模式不只适用于 Office Skill，对任何需要 AI 生成结构化输出的 Skill 都有参考价值。 ### 1. 约束先行（Constraint-First） 四个 Skill 都在生成逻辑之前定义了严格的输出约束： - **PPTX**：Theme Contract + Slide Taxonomy → 颜色和布局在动手前就锁死 - **XLSX**：公式硬规则 + 财务色彩标准 → 数据完整性在动手前就有保障 - **DOCX**：元素顺序规则 + XSD Schema → 文档结构在动手前就有规范 - **PDF**：Token 设计系统 + 15 种类型模板 → 视觉风格在动手前就确定 这跟写 prompt 时"先给 AI 定规矩再让它干活"是同一个思路，但做到了系统级别。 ### 2. 评估闭环（Evaluate-Fix Loop） 每个 Skill 都内建了验证步骤，形成"执行 → 评估 → 修复"的三阶段闭环： - **PPTX**：QA Process（pitfalls.md 检查清单） - **XLSX**：`formula_check.py`（静态验证）+ `libreoffice_recalc.py`（动态重算验证，可用时强制） - **DOCX**：XSD validation → business rules → preview（三层验证） - **PDF**：`merge.py` 合并时做最终 QA 检查（`make.sh check` 负责环境依赖检查） "通过"的标准不是"文件能打开"，而是"结构正确、样式合规、数据准确"。 ### 3. 底层可控（Low-Level Control） 宁可增加系统复杂度，也要保证底层管线可控： - **XLSX**：跳过 openpyxl，直接操作 XML——因为高层库会静默丢失数据 - **DOCX**：用 .NET OpenXML SDK 而非 python-docx——因为后者的抽象层挡住了必要的控制 - **PDF**：双引擎分工——因为没有单一引擎能同时做好视觉和结构 这个模式的代价是学习曲线陡峭、调试困难。但对于"能交付"这个目标，可控性比便利性重要。 ### 4. Reference 分离 知识库与流程严格分离： | Skill | SKILL.md 行数 | 详细文档总行数 | |-------|:---:|:---:| | pptx-generator | 249 | ~1,500 | | minimax-xlsx | 138 | ~3,280 | | minimax-docx | 274 | **15,297** | | minimax-pdf | 192 | 381 (design/) | SKILL.md 只放路由逻辑和核心流程（都控制在 300 行以内），详细的格式规范、API 参考、代码样例全部放进 `references/` 目录。DOCX 的参考文档达到 15,297 行——如果全塞进 SKILL.md，agent 的上下文窗口会被严重挤占，性能急剧下降。 --- ## 拓展：其他 Office Skill 推荐 MiniMax 不是唯一选择。市面上还有几个 Office Skill 方案： ### Anthropic 官方 Skills 仓库 [anthropics/skills](https://github.com/anthropics/skills) 包含 docx、pptx、xlsx、pdf 四个 Skill。定位是通用的文件处理工具，覆盖面广但设计系统不如 MiniMax 成熟。有用户评价其 PPT Skill 是"more of a general 'handle pptx files' tool"。 ### tfriedel/claude-office-skills 社区打包版，把常用 Office 操作整合到一起。适合轻量级场景，不追求专业排版。 ### 传统 Python 库方案 直接用 python-pptx、openpyxl、python-docx、ReportLab 等库，不通过 Skill 而是在代码中调用。灵活度最高，但没有设计系统的约束，生成质量依赖 prompt 工程。 ### 选型建议 | 场景 | 推荐方案 | |------|----------| | 需要专业排版、品牌一致性 | MiniMax Skills | | 轻量级文件处理、格式转换 | Anthropic 官方 Skills | | 高度定制化、已有代码基础 | 直接用 Python 库 | | 中文公文、学术论文 | MiniMax DOCX Skill（唯一提供 GB/T 9704 和 IEEE/ACM 模板的） | | 快速体验、最低门槛 | MiniMax PDF Skill（`make.sh demo` 三行命令见效果） | --- ## 结尾 MiniMax 这套 Skill 给我的核心启发是：**生产级 Skill 不只是写 prompt，是建系统**。Design System 约束输出边界，评估闭环保证质量底线，底层可控避免库的黑盒吞掉关键细节，Reference 分离让 agent 不被信息淹没。 这套思路不限于 Office 场景。任何需要 AI 生成结构化、可交付产物的场景——代码生成、配置文件生成、数据管线编排——都能从中借鉴。 仓库地址：[MiniMax-AI/skills](https://github.com/MiniMax-AI/skills) --- ## 参考文档 [MiniMax Skills 仓库](https://github.com/MiniMax-AI/skills) [Anthropic 官方 Skills 仓库](https://github.com/anthropics/skills) [PptxGenJS 文档](https://gitbrent.github.io/PptxGenJS/) [MiniMax 官方 X 帖](https://x.com/MiniMax_AI/status/2035609361826111780) [berryxia 深度分析](https://x.com/berryxia/status/2036970499927138762) --- ## 相关阅读 - [Skill 设计手册：Anthropic 内部数百个 Skill 的经验总结](/posts/claude-code-skill-design-guide/) — MiniMax 的 Skill 架构正是这套设计原则的实践案例 - [用 AI 生成年度述职 PPT 完整教程](/posts/ai-ppt-generation/) — 如果你想用 AI 做 PPT，这篇讲了更多实操细节 - [Claude Code 实用插件与工具分享](/posts/claude-code-plugins-tools/) — MiniMax Skills 是其中一类工具，这篇覆盖了更多