Skip to content

minimax-ai/document-skills

v0.1.0Apache-2.0

Workbench Skills for creating, reading, editing, and checking DOCX, PDF, PPTX, and XLSX documents with standard open-source tooling.

GitHub

Document Skills

The problem

Users keep asking coding agents for document deliverables — a Word report, a PDF handout, a slide deck, a data workbook — and get unreliable results: ZIP files rewritten by hand and corrupted, spreadsheets where formulas were typed as text, slide decks that no viewer opens, PDFs that are a stack of screenshots instead of text. Office and PDF documents are container formats with strict internal contracts, and an agent without format knowledge breaks them silently.

This Plugin installs four namespaced workbench Skills — document-skills-docx, document-skills-pdf, document-skills-pptx, and document-skills-xlsx — that route each task to the right standard tool (python-docx, python-pptx, openpyxl, pypdf, ReportLab, PyMuPDF), enforce the container contracts (valid ZIP, correct content types, calculated dimensions), and verify output before it is handed back. The namespaced IDs avoid overriding host-provided Skills with generic names such as docx, pdf, pptx, or xlsx.

Try it

Use the document-skills plugin: open sales-2024.xlsx, add a sheet "Summary" with per-region
totals computed by formula, a bar chart of the top 5 products, and currency formatting.

Expected result: the agent loads the workbook with openpyxl, inspects sheet names, headers, and dtypes, writes SUMIF/COUNTIF formulas (not pasted values), adds a native BarChart anchored to the new sheet, applies number formats, and reports the cell ranges it changed.

Use the document-skills plugin: create a PDF one-pager "Q3 launch checklist" from this outline
with a title block and a two-column checklist that fits exactly one A4 page.

Expected result: the agent generates the page with ReportLab flowables on an A4 canvas, measures the checklist blocks, and confirms with pypdf that the output is exactly 1 page with extractable text — not a screenshot.

What the Skills do

Shared spine (all four Skills follow it):

  1. Classify the request as create, read, edit, or review.
  2. Check tool availability first and report missing dependencies instead of improvising.
  3. Follow format-specific rules (packages below).
  4. Run the post-generation verification checklist; fix and re-verify until it passes.
  5. Report the output path, the page/sheet/slide inventory, and any remaining caveats.

Per format:

  • document-skills-docx — create with python-docx from a heading outline; use python-docx first for routine structural edits (paragraphs, tables, images, styles, and text runs), and reserve direct OOXML surgery for fields, tracked changes, or package features python-docx cannot express; extract text with python-docx or pandoc -t markdown; postcheck with python-docx re-open and soffice --headless --convert-to PDF smoke test when LibreOffice is present. Depth references: CJK typography (east-asian font slots, 字号 table, char-based indents, GB/T 9704 page geometry) and scene patterns (academic paper, resume, official document, contract).
  • document-skills-xlsx — openpyxl for reading, editing, styling, and native charts; formulas as formulas, never as pasted results; data_only=True only for reading cached values; date/number formats applied explicitly; recalculation contract documented (openpyxl writes formulas, the Skill sets fullCalcOnLoad so even manual-calc workbooks recalculate when a viewer opens them). Depth references: conditional formatting rules, structured tables, and honest pivot-style aggregation (openpyxl cannot create pivot tables; the reference gives the formula-sheet, frozen-values, and user-template routes).
  • document-skills-pptx — python-pptx to build decks (7 common slide patterns: title, agenda, bullet, two image+text, table, chart, quote/closing); edit only named, existing shapes, never blind rewriting of the whole XML; text measured against shape width with font-size reduction rules; presentation-level verification via python-pptx re-open plus a rendered PDF smoke test when LibreOffice is available.
  • document-skills-pdf — creation prefers ReportLab (real, selectable text with flowable structure) over HTML-to-print paths; extraction (text, coordinates, tables, images) and rasterization use PyMuPDF, while pypdf is reserved for page-level transforms such as split, merge, rotate, watermark, encryption, and forms; an explicit one-tool-per-job table prevents accidental API mixing. Note: ReportLab output is not tagged PDF/UA — when the user needs an accessible (screen-reader-ready) PDF, the PDF Skill says to report that limitation honestly instead of claiming accessibility.

Verification-first output

Every Skill ends with the same rule: do not hand back a file you have not re-opened. The checklists are specific (re-open the archive, confirm the sheet count and formula presence, confirm the slide count, confirm page count and text extraction) and the Skills require reporting what was verified versus what was assumed.

The tests/ directory ships one runnable fixture script per format covering the snippets with the worst silent-failure modes (PDF AcroForm clone-and-fill, watermark write, encrypted extraction, CMYK conversion, soft masks; PPTX run-preserving edits, table-cell locating, actual content extraction, grouped shapes, script-aware per-master themes; XLSX dialect sniffing, array formulas, streamed extension checks, structural-reference audits; DOCX bounded package review, content controls, per-run glyph checks, guarded replacement, and a LibreOffice-rendered numbering restart). Each script is self-contained and exits non-zero on failure.

These heavyweight integration fixtures are intentionally not part of the repository-wide npm run check. To run the same gate locally from this plugin directory:

python -m pip install -r tests/requirements-fixtures.txt
node --test tests/fixtures.integration.mjs

LibreOffice (soffice) must be available for the rendering checks. The path-filtered .github/workflows/document-skills.yml workflow installs the pinned Python environment and LibreOffice, then runs this fixture gate only when the document-skills plugin or its workflow changes.

Requirements

  • Python 3.9+ with python-docx, python-pptx, openpyxl, pypdf, reportlab, pymupdf (pip install python-docx python-pptx openpyxl pypdf reportlab pymupdf).
  • Optional: LibreOffice (soffice) for PDF smoke tests of DOCX/PPTX output; pandoc for markdown extraction from DOCX.
  • Works on Windows, macOS, and Linux. All commands are given in cross-platform form; the Skills say how to resolve the skill directory path on each platform.

Data and network

  • No network access. All processing is local file conversion and generation.
  • No credentials required.
  • The Skills only read and write document files the user points at; temporary files go to the system temp directory and are cleaned up.

License

Apache-2.0. See LICENSE.