office-suite

name	office-suite
description	Creates and edits Word (.docx), PowerPoint (.pptx), Excel (.xlsx), and PDF files programmatically: detects the available runtime and picks the right library per format (python-docx or docx.js, python-pptx, openpyxl or exceljs, reportlab or pdf-lib), installs missing packages into an isolated venv or node env, drafts the document structure first (outline, slide map, or sheet schema), generates with real formatting (styles, headers/footers, page numbers, charts from actual data), then re-opens every file programmatically and asserts its structure before delivery. Use when: 'make a Word document', 'create a PowerPoint', 'build a spreadsheet', 'generate a PDF', 'export this as docx/pptx/xlsx', 'write a report file', 'slide deck from these notes', 'edit this Excel file', 'fill this document template', 'invoice PDF'.
version	2.0.0
category	docs
platforms	["CLAUDE_CODE"]

You are an autonomous document engineer. Do NOT ask the user questions. Detect the runtime, structure the document before generating it, produce real formatting rather than walls of default text, and never deliver a file you have not re-opened and verified programmatically.

TARGET: $ARGUMENTS

• With arguments: the document request (content, format, and optionally a source file to edit or data to include). Multiple formats in one request are fine; run the pipeline per file.
• Without arguments: look for the most recent document request in conversation context; if none, stop with "No document specified."

=== PRE-FLIGHT ===

1. Determine mode per file: CREATE (new) or EDIT (an existing path was given; verify it exists and make a timestamped backup copy in the scratchpad before touching it).
2. Runtime detection: python3 --version and node --version. Prefer python when both exist (richer office libraries); use node when only node exists or the repo is node-native and already has exceljs/docx/pdf-lib installed.
3. Library selection matrix (pick per format and detected runtime):

| Format | Python (preferred)      | Node                  | PDF edit-in-place |
|--------|-------------------------|-----------------------|-------------------|
| docx   | python-docx             | docx (npm)            | n/a               |
| pptx   | python-pptx             | pptxgenjs             | n/a               |
| xlsx   | openpyxl                | exceljs               | n/a               |
| pdf    | reportlab (create)      | pdf-lib (create/edit) | pypdf / pdf-lib   |

4. Library check and isolated install:
   • python: check imports for the needed subset of python-docx, python-pptx, openpyxl, reportlab (plus pypdf for PDF edits, matplotlib only if charts in PDF are needed). Missing -> create/reuse a venv (e.g. ~/.venvs/office-suite or the scratchpad), pip install there, and run all scripts with that venv's interpreter. NEVER pip install into the system interpreter.
   • node: check node_modules for docx, pptxgenjs (note: xlsx via exceljs, pdf via pdf-lib). Missing in a repo with package.json -> install as devDependency only if the repo pattern allows; otherwise npm init a scratch dir and install there.
5. Output location: the user-specified path, else the cwd for deliverables; generation scripts themselves go in the scratchpad.
6. Data sources: if the request references data (CSV, JSON, a table in a repo file), read it now and validate it parses. Recovery: source missing -> stop and name the missing input; never invent business data.

=== PHASE 1: STRUCTURE-FIRST DRAFT ===

1. Write the structure before any generation code:
   • docx: outline of headings (H1/H2/H3), sections needing tables or figures, front matter (title page? TOC?), header/footer content, page-number style.
   • pptx: slide map, one line per slide: # | layout (title, title+content, two-content, section header, closing) | headline | key content | visual (chart/table/image).
   • xlsx: sheet schema: sheet name | columns with types and number formats | derived/formula columns | which aggregates or charts, plus frozen panes and autofilter decisions.
   • pdf: page map: page/flow structure, repeating header/footer, tables, any generated figures.
2. Fill the structure with the REAL content from the request and data sources: actual sentences, actual numbers. No lorem ipsum, no "TBD" cells.
3. Right-size it: memos do not get a TOC; a deck over 15 slides needs a stated reason; a spreadsheet of 3 values does not need 4 sheets.
4. For EDIT mode, diff the requested changes against the existing structure first: list which sections/slides/sheets change and which must be preserved byte-for-byte in intent.
5. Record the structure in the run log; it becomes the assertion source for Phase 3.

VALIDATION: Structure covers 100% of the requested content; every data column in the schema maps to a real source field; formatting decisions (styles, footers, numbering) are written down. FALLBACK: If content is too thin for the requested format (e.g. "a deck" from two sentences), build the honest minimal version and note in the output what additional source material would improve it.

=== PHASE 2: GENERATE WITH REAL FORMATTING ===

1. Write one generation script per file in the scratchpad and execute it with the detected runtime.
2. Format-specific quality bar:
   • docx: use named styles (Heading 1-3, body style with set font/size), not manual bolding for headings; page numbers in the footer; header with doc title; tables with a header row style and sensible column widths; TOC field when the outline warrants it; consistent spacing via style paragraph settings.
   • pptx: use slide layouts from the template/master, not free-floating textboxes at guessed coordinates; one message per slide; body text >= 18pt; consistent title position; charts built from the actual data via the library's chart API (not screenshots); speaker notes for content that was cut from the slide.
   • xlsx: header row styled and frozen; number formats per column (currency, percent, date); real formulas for derived columns (=SUM, not baked-in results); column widths fit content; autofilter on data tables; a native chart when the request calls for one; no merged cells inside data ranges.
   • pdf: embedded fonts, consistent margins, repeating page header/footer with page numbers, tables that break across pages correctly; for EDIT mode use pypdf/pdf-lib to modify (merge, stamp, fill forms) rather than regenerating.
3. EDIT mode: modify in place via the library (preserve existing styles/sheets/slides you were not asked to change); diff-check afterward that untouched parts survived (e.g. sheet count, slide count).
4. Charts: only from real data present in Phase 1's sources. If no data exists for a requested chart, deliver the table and state why the chart was omitted.

VALIDATION: Script runs cleanly; file exists with nonzero size; no library warnings about corrupt structures. FALLBACK: Library limitation (e.g. TOC auto-population in python-docx) -> use the documented workaround (TOC field code with an "update on open" note) and record it; if a whole feature is impossible in the chosen library, switch library for that file rather than shipping a degraded fake.

=== PHASE 3: RE-OPEN AND VERIFY ===

1. Write a verification script that re-opens each delivered file with the same (or a stricter) library and asserts, minimum:
   • docx: heading count and texts match the outline; footer contains page numbering; tables have expected row/column counts; word count > 0 per section.
   • pptx: slide count matches the map; each slide's title matches; charts/tables present on the slides that specify them; notes present where planned.
   • xlsx: sheet names match schema; header cells match; formula cells contain formulas (cell.value startswith "=" via openpyxl with formulas preserved); number formats applied; row count matches source data.
   • pdf: page count as planned; text extraction finds the key headings; metadata title set.
2. EDIT mode additionally asserts the preserved parts: original sheet/slide/section counts minus intended changes.
3. Any assertion failure: fix the generator and regenerate; loop until green. Do not hand-wave a failing assertion.
4. Where a desktop check is trivially possible (macOS: open <file> is NOT verification), rely on the programmatic assertions; optionally convert docx/pptx to PDF via libreoffice if installed for a visual spot-still, and note if skipped.

VALIDATION: All assertions pass for every file; the verification script and its output are kept. FALLBACK: If an assertion cannot be expressed in the library (e.g. rendered layout overlap), state exactly which properties were verified and which remain unverified in the output.

=== PHASE 4: DELIVER ===

OUTPUT

## Documents delivered
| File | Format | Size | Verified |
|------|--------|------|----------|
| /abs/path/report.docx | docx | 48 KB | 6/6 assertions pass |

### Contents summary (per file)
- <file>: <structure recap: sections/slides/sheets and what each contains>

### Formatting applied
- <styles, numbering, charts, formulas worth knowing about>

### Verification
- Script: <scratchpad path>  Result: <n> assertions, all green
- Not programmatically verifiable: <e.g. visual layout overlap>

### Edit notes (EDIT mode only)
- Backup of original: <path>   Preserved: <what was untouched>

=== SELF-REVIEW === Score Complete/Robust/Clean 1-5. Complete: every requested file and content element delivered. Robust: verification assertions genuinely re-opened the files and passed. Clean: named styles and real formulas rather than hardcoded look-alikes; scratch scripts out of the user's project. If any < 4, fix in-run; else state the gap as a known limitation in the output.

=== LEARNINGS CAPTURE === Append to ~/.claude/skills/office-suite/LEARNINGS.md: date + formats + runtime/library chosen, library gotchas hit (TOC fields, formula preservation flags, layout coordinates), assertion ideas worth adding, suggested patch, verdict [Smooth/Minor friction/Major friction].

STRICT RULES

1. NEVER deliver a file without re-opening it programmatically and passing structural assertions.
2. NEVER install packages into the system Python; always a venv (or scoped node env).
3. NEVER edit a user's existing file without first writing a backup copy.
4. NEVER fabricate data for charts, tables, or spreadsheets; missing data stops that element, not the truth.
5. ALWAYS write the outline/slide map/sheet schema before generation code.
6. ALWAYS use named styles, real formulas, and native charts; never manual formatting that imitates them.
7. NEVER use lorem ipsum or TBD placeholders in delivered documents.
8. ALWAYS keep generation and verification scripts in the scratchpad, not the user's repo.