MiniMax Office Skill 实战:让 AI 生成「能交付」的文档

为什么要看这个 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 安装

# 方式一：通过 plugin marketplace 安装（推荐）claude plugin marketplace add https://github.com/MiniMax-AI/skillsclaude 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 安装

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# 脚本）。

# PDF skill 提供了一键环境检查cd /tmp/minimax-skills/skills/minimax-pdfbash 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 对象：

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（封面 + 目录 + 架构总览）。

生成结果：布局清晰，风格统一，卡片式架构页视觉效果不错。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 包处理（因为它本质上就是）：

.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 公式。

<!-- 正确：用公式 --><c r="B10"><f>SUM(B2:B9)</f><v></v></c><!-- 错误：硬编码计算结果 --><c r="B10"><v>790000</v></c>

以及财务色彩标准：蓝色 = 手工输入，黑色 = 公式计算，绿色 = 跨表引用。这套配色是财务建模领域的行业惯例。

实测

测试场景：生成一份季度收入报表，包含四个季度的数据、SUM 汇总公式、冻结首行、财务色彩。

验证结果：

• 公式正确计算：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 里有大量教学性注释，某些解析器可能被 <sheets> 标签内部的注释干扰。建议清理注释后再打包。
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）：

# 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。

封面的设计感是实打实的——深色背景、Playfair Display 字体、点阵纹理装饰，这个质量纯靠 Python 绘图库达不到。正文包含 callout 框、数据表格、柱状图、饼图，图表由 matplotlib 本地渲染，无需外部服务。

PDF Skill 的入门体验在四个 Skill 中是最好的：

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 设计模式提炼

拆完四个 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 仓库

包含 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 生成结构化、可交付产物的场景——代码生成、配置文件生成、数据管线编排——都能从中借鉴。

点击「阅读原文」查看 Blog 完整版（含所有参考链接和仓库地址）。