microsoft-office – skill Tài liệu & Office cho agent AI

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:

| File | Reference | Typical asks |

| --- | --- | --- |

| .docx | references/word.md | reports, letters, contracts, {{token}} templates, tracked changes, comments |

| .pptx | references/powerpoint.md | pitch decks, brand-template decks, chart refreshes, speaker notes, slide PNGs |

| .xlsx, .csv | references/excel.md | styled multi-sheet workbooks, formulas, charts, CSV conversion, row/column restructures |

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.
      mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1
      old="$(readlink hermes-docs-venv)"  # an earlier build that no longer imports, if any
      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" ]; 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

| Task | Word | PowerPoint | Excel |

| --- | --- | --- | --- |

| Create from JSON spec | docx_create.py | pptx_create.py | xlsx_create.py, csv_to_xlsx.py |

| Read back | docx_read.py --text/--structure | pptx_read.py --outline | xlsx_read.py --sheets/--json |

| Edit | docx_edit.py | pptx_edit.py | xlsx_edit.py, xlsx_restructure.py |

| Fill a template | docx_template.py | pptx_from_template.py | — |

| Review / check | docx_revisions.py, docx_comments.py, docx_validate.py | pptx_render.py (slide PNGs) | xlsx_recalc.py, xlsx_to_csv.py |

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).