Office Document Assistant#

Read, extract, summarize, and compare common office documents:

• PDF
• Word ( .docx, .doc)
• Excel ( .xlsx, .xls)
• PowerPoint ( .pptx, .ppt)

Use this skill when the user wants the contents of a document explained, summarized, searched, or extracted into a simpler structure.

When to Use#

Use this skill when the user:

• uploads a .pdf / .doc / .docx / .xls / .xlsx / .ppt / .pptx
• asks to summarize a document
• asks to extract dates, amounts, contacts, conclusions, specifications, risks, or action items
• asks for page-by-page / slide-by-slide structure
• asks what a spreadsheet or slide deck is saying
• asks to compare two or more documents after extracting their text

When Not to Use#

Do not position this skill as a high-fidelity layout or visual analysis system.

It is not ideal for:

• precise preservation of original layout, formatting, or pagination
• detailed chart / diagram / image interpretation
• password-protected or encrypted files
• OCR-heavy image understanding beyond basic text recovery
• advanced spreadsheet analytics or formula auditing
• tracked-changes / redline reconstruction in Office documents

Core Workflow#

1. Confirm the document path.
2. Run the bundled script:
   • python3 {skill_dir}/scripts/extract_office_text.py <file> --json
3. Inspect the JSON fields:
   • type
   • extraction
   • warning
   • truncated
   • text
4. Separate clearly in your response:
   • directly extracted content
   • your summary / inference based on that content
5. If extraction is empty or weak:
   • for PDF, check OCR availability first
   • for legacy Office formats, check conversion tools
6. If the user asks for a summary, default to:
   • one-sentence overview
   • 3–8 key points
   • extra sections only when clearly present (dates, people, risks, data, conclusions, contacts)
7. If the user asks for extraction, prefer structured fields over long prose.

Supported Formats and Strategy#

PDF#

• First extract embedded text with pypdf.
• If extracted text is too short, fall back to OCR.
• OCR prefers chi_sim+eng, then chi_sim, then eng.
• OCR pipeline requires both pdftoppm and tesseract.
• If an official first-class PDF tool is exposed in the environment and the task is high-value or multi-PDF, you may prefer that tool; otherwise use this skill's script.

Word#

• .docx: extract paragraphs and tables directly.
• .doc: try antiword, then catdoc, then LibreOffice conversion to .docx.

Excel#

• Extract sheet names and the first rows of each sheet.
• Best for quickly understanding workbook structure and core fields.
• When explaining, focus on what each sheet represents, key columns, important figures, and obvious anomalies.

PowerPoint#

• Extract slide text from shapes.
• Extract speaker notes when present.
• Summaries should usually be slide-by-slide or theme-based, not a giant raw dump.

Tools and Dependencies#

Document clearly what is required versus optional.

Required runtime#

• python3

Required Python packages#

• pypdf — embedded text extraction from PDFs
• python-docx — .docx extraction
• openpyxl — .xlsx extraction
• python-pptx — .pptx extraction

Optional but strongly recommended system tools#

• poppler-utils — provides pdftoppm for PDF → image conversion before OCR
• tesseract-ocr — OCR engine
• tesseract-ocr-chi-sim — Simplified Chinese OCR language pack
• libreoffice — conversion fallback for legacy .doc, .xls, .ppt
• antiword — direct .doc extraction fallback
• catdoc — additional .doc extraction fallback

What each tool is used for#

• pypdf: try text-layer extraction from PDFs first
• pdftoppm: rasterize PDF pages when OCR is needed
• tesseract: recover text from scanned/image PDFs
• python-docx: read paragraphs and tables from .docx
• openpyxl: read sheets and rows from .xlsx
• python-pptx: read slide text and notes from .pptx
• libreoffice: convert older Office formats into newer parseable formats
• antiword / catdoc: lightweight extraction options for .doc

Minimum useful setup#

If only modern documents matter, the minimum practical setup is:

• python3
• Python packages: pypdf, python-docx, openpyxl, python-pptx

Recommended full setup#

For the most robust behavior across real-world files, install:

• python3
• Python packages: pypdf, python-docx, openpyxl, python-pptx
• system tools: poppler-utils, tesseract-ocr, tesseract-ocr-chi-sim, libreoffice, antiword, catdoc

Dependency check#

Use the bundled checker to quickly see what is missing in the current environment:

bash

python3 {skill_dir}/scripts/check_deps.py

Common Commands#

bash

python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.pdf" --json
python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.docx" --json
python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.xlsx" --json
python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.pptx" --json

Useful flags:

bash

# limit PDF pages scanned/extracted
python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.pdf" --page-limit 10 --json

# limit rows per sheet when probing spreadsheets
python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.xlsx" --row-limit 30 --json

# cap output text size
python3 {skill_dir}/scripts/extract_office_text.py "/path/to/file.pdf" --max-chars 30000 --json

Output Style#

Default to a compact answer:

• one-sentence summary
• 3–8 key points
• then expand only if the user asks for:
  • detailed summary
  • page-by-page / slide-by-slide notes
  • field extraction
  • document comparison

Failure Handling#

• If PDF text is empty, suspect scanned pages or missing OCR tools.
• If Chinese OCR is weak, check whether tesseract-ocr-chi-sim is installed.
• If .doc / .xls / .ppt extraction fails, check libreoffice, antiword, and catdoc.
• If tables look messy, explain that this is text-first extraction rather than full layout reconstruction.
• If a file is encrypted or unreadable, say so plainly and stop guessing.

References#

Read these only when needed:

• references/capabilities.md — capability boundaries and what each format can/can't do well
• references/troubleshooting.md — dependency checks and common failure modes