Microsoft Office Skill

Create, read, edit, and template Word (.docx), PowerPoint (.pptx), and Excel (.xlsx, .csv) files offline with small Python CLIs built on python-docx, python-pptx, and openpyxl. Office itself is never needed. It does not open legacy binary formats (.doc, .ppt, .xls) and does not render pages without LibreOffice.

When to Use

Pick the format, then read its reference with skill_view before working:

Deeper notes: references/revisions-and-comments.md (Word review markup) and references/restructuring.md (Excel reference shifting).

• Not for .doc/.ppt/.xls: convert first with soffice --headless --convert-to docx|pptx|xlsx old-file when LibreOffice is installed.
• Not for .odt/.odp/.ods, or WYSIWYG layout work.

Prerequisites

• Python 3.10+ with python-docx, python-pptx, and openpyxl (import names docx, pptx, openpyxl).

• Pick the interpreter with terminal. Use python when it already imports the libraries (the Hermes Docker image ships them). Otherwise, when hermes is on PATH, let Hermes build its shared, pinned documents environment under the Hermes home: it survives container restarts, never touches the Hermes install itself, and is safe to run from several agents at once. When it is not (the terminal runs in a Docker sandbox, which has no Hermes), the block builds a venv in the sandbox home with the same pinned versions. Use this exact block in every document skill so they all share one environment:

  python -c "import docx, pptx, openpyxl" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then
    PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"
  else
    PY="$HOME/.cache/hermes-docs-venv/bin/python"
    "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (
      # Safe to run from several agents at once: each caller builds a private venv,
      # a symlink publishes the first finished one atomically, the others delete theirs;
      # a published build is replaced and deleted only while it still fails to import.
      mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1
      old="$(readlink hermes-docs-venv)"  # the published build, if any (another agent may have just published it)
      python3 -m venv "$stage" &&
        "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.2 pdfplumber==0.11.10 pypdfium2==5.14.0 &&
        "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&
        if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv
        elif [ "$(readlink hermes-docs-venv)" = "$old" ] && ! "$old/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null; then
          ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&
            case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac
        fi 2>/dev/null
      [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"
    )
  fi
  export PY
  "$PY" scripts/docx_create.py --help

  Run every helper with "$PY". In PowerShell (Hermes runs on that host, so it is on PATH): $env:PY = hermes pm environment documents --extra documents --extra documents-pdf. Never pip install into the interpreter that runs Hermes or into the hermes pm environment one; Hermes owns both.

• Optional: LibreOffice (soffice) for PDF export, Excel recalculation, and slide rendering, plus poppler (pdftoppm or pdftocairo) for slide PNGs. The helpers that need them report what is missing and exit 0.

How to Run

Every helper lives in scripts/, is an argparse CLI with --help, prints JSON to stdout, and exits non-zero on failure. Run them with terminal from the skill directory. Author JSON specs with write_file; read results with read_file or straight from stdout.

"$PY" scripts/docx_create.py spec.json out.docx
"$PY" scripts/pptx_create.py deck.json out.pptx
"$PY" scripts/xlsx_create.py spec.json report.xlsx

Quick Reference

The per-format reference has the full flag table.

Procedure

1. Identify the format from the file extension or the ask, and load its reference (skill_view with file_path=references/<format>.md).
2. Set PY with the Prerequisites block once per session.
3. Create, edit, or read with that format's helpers; pass an output path to keep the original whenever the helper supports one.
4. Verify the result as the reference's Verification section says, then give the user the exact output path.

Converting to PDF

When LibreOffice is installed, convert headlessly:

soffice --headless --convert-to pdf --outdir out/ file.docx   # also .pptx, .xlsx
soffice --headless --convert-to csv --outdir out/ report.xlsx # first sheet only

Check first with command -v soffice || command -v libreoffice. Fonts not on the host are substituted, so render-check decks before shipping. There is no pure-Python path to PDF for any of these formats: if soffice is missing, say so rather than approximating. For other sheets use xlsx_to_csv.py --sheet NAME.

Pitfalls

• Never unzip-and-edit the XML. These files are zip packages; raw text substitution corrupts them. Edit through the helpers (or the libraries) and use patch/write_file only for JSON inputs.
• Text is split into runs. Word and PowerPoint fragment text at edit boundaries; the replace helpers merge equal-format runs first, but a match across differently formatted runs takes the first run's formatting.
• Nothing computes fields or formulas. Word TOC/page fields and Excel formulas are filled in by the office app on open (or by xlsx_recalc.py).
• Encoding. Write specs as UTF-8; the helpers read UTF-8 explicitly.
• Format-specific traps are in each reference.

Verification

• Re-read every output with the format's read helper and check the expected content is there and the old content is gone.
• Word: docx_validate.py out.docx exits 0 after revision, comment, or field surgery.
• PowerPoint: render with pptx_render.py and check each PNG with vision_analyze when the render tools exist.
• Excel: xlsx_read.py --formulas lists written formulas; run xlsx_recalc.py when cached values matter.
• The bundled tests are the full contract: "$PY" -m pytest tests/ -q (needs pytest in that interpreter).