file-reading

# Reading Uploaded Files ## Why this skill exists When a user uploads a file in claude.ai, Claude Desktop, or Cowork, the file is written to `/mnt/user-data/uploads/<filename>` and you are told the path in an `<uploaded_files>` block. **The content is not in your context.** You must go read it. The naive thing — `cat /mnt/user-data/uploads/whatever` — is wrong for most files: - On a PDF it prints binary garbage. - On a 100MB CSV it floods your context with rows you will never use. - On a DOCX it prints the raw ZIP bytes. - On an image it does nothing useful at all. This skill tells you the right first move for each type, and when to hand off to a deeper skill. ## General protocol 1. **Look at the extension.** That is your dispatch key. 2. **Stat before you read.** Large files need sampling, not slurping. ```bash stat -c '%s bytes, %y' /mnt/user-data/uploads/report.pdf file /mnt/user-data/uploads/report.pdf ``` 3. **Read just enough to answer the user's question.** If they asked "how many rows are in this CSV", don't load the whole thing into pandas — `wc -l` gives a fast approximation (it counts newlines, not CSV records, so it may over-count if quoted fields contain embedded newlines). 4. **If a dedicated skill exists, go read it.** The table below tells you when. The dedicated skills cover editing, creating, and advanced operations that this skill does not. ## Dispatch table | Extension | First move | Dedicated skill | | --------------------------------- | ---------------------------------------------------- | ----------------------------------------- | | `.pdf` | Content inventory (see PDF section) | `/mnt/skills/public/pdf-reading/SKILL.md` | | `.docx` | `pandoc` to markdown | `/mnt/skills/public/docx/SKILL.md` | | `.doc` (legacy) | Convert to `.docx` first — pandoc cannot read it | `/mnt/skills/public/docx/SKILL.md` | | `.xlsx`, `.xlsm` | `openpyxl` sheet names + head | `/mnt/skills/public/xlsx/SKILL.md` | | `.xls` (legacy) | `pd.read_excel(engine="xlrd")` — openpyxl rejects it | `/mnt/skills/public/xlsx/SKILL.md` | | `.ods` | `pd.read_excel(engine="odf")` — openpyxl rejects it | `/mnt/skills/public/xlsx/SKILL.md` | | `.pptx` | `python-pptx` slide count | `/mnt/skills/public/pptx/SKILL.md` | | `.ppt` (legacy) | Convert to `.pptx` first — python-pptx rejects it | `/mnt/skills/public/pptx/SKILL.md` | | `.csv`, `.tsv` | `pandas` with `nrows` | — (below) | | `.json`, `.jsonl` | `jq` for structure | — (below) | | `.jpg`, `.png`, `.gif`, `.webp` | Already in your context as vision input | — (below) | | `.zip`, `.tar`, `.tar.gz` | List contents, do **not** auto-extract | — (below) | | `.gz` (single file) | `zcat \| head` — no manifest to list | — (below) | | `.epub`, `.odt` | `pandoc` to plain text | — (below) | | `.rtf` | `pandoc` (needs 3.1.7+) or soffice via docx skill | — (below) | | `.txt`, `.md`, `.log`, code files | `wc -c` then `head` or full `cat` | — (below) | | Unknown | `file` then decide | — | --- ## PDF **Never** `cat` a PDF — it prints binary garbage. Quick first move — get the page count and check if text is extractable: ```bash pdfinfo /mnt/user-data/uploads/report.pdf pdftotext -f 1 -l 1 /mnt/user-data/uploads/report.pdf - | head -20 ``` Then peek at the text content: ```python from pypdf import PdfReader r = PdfReader("/mnt/user-data/uploads/report.pdf") print(f"{len(r.pages)} pages") print(r.pages[0].extract_text()[:2000]) ``` For anything beyond a quick peek — figures, tables, attachments, forms, scanned PDFs, visual inspection, or choosing a reading strategy — go read `/mnt/skills/public/pdf-reading/SKILL.md`. It covers content inventory, text extraction vs. page rasterization, embedded content extraction, and document-type-aware reading strategies. For PDF form filling, creation, merging, splitting, or watermarking, go read `/mnt/skills/public/pdf/SKILL.md`. --- ## DOCX / DOC The `docx` skill covers editing, creating, tracked changes, images. Read it if you need any of those. For a quick look: ```bash pandoc /mnt/user-data/uploads/memo.docx -t markdown | head -200 ``` Legacy `.doc` (not `.docx`) must be converted first — see the `docx` skill. --- ## XLSX / XLS / spreadsheets The `xlsx` skill covers formulas, formatting, charts, creating. Read it if you need any of those. For a quick look at `.xlsx` / `.xlsm`: ```python from openpyxl import load_workbook wb = load_workbook("/mnt/user-data/uploads/data.xlsx", read_only=True) print("Sheets:", wb.sheetnames) ws = wb.active for row in ws.iter_rows(max_row=5, values_only=True): print(row) ``` `read_only=True` matters — without it, openpyxl loads the entire workbook into memory, which breaks on large files. Do not trust `ws.max_row` in read-only mode: many non-Excel writers omit the dimension record, so it comes back `None` or wrong. If you need a row count, iterate or use pandas. **Legacy `.xls`** — openpyxl raises `InvalidFileException`. Use: ```python import pandas as pd df = pd.read_excel("/mnt/user-data/uploads/old.xls", engine="xlrd", nrows=5) ``` **`.ods` (OpenDocument)** — openpyxl also rejects this. Use: ```python import pandas as pd df = pd.read_excel("/mnt/user-data/uploads/data.ods", engine="odf", nrows=5) ``` --- ## PPTX ```python from itertools import islice from pptx import Presentation p = Presentation("/mnt/user-data/uploads/deck.pptx") print(f"{len(p.slides)} slides") for i, slide in enumerate(islice(p.slides, 3), 1): texts = [s.text for s in slide.shapes if s.has_text_frame] print(f"Slide {i}:", " | ".join(t for t in texts if t)) ``` `p.slides` is not subscriptable — `p.slides[:3]` raises `AttributeError`. Use `islice` or `list(p.slides)[:3]`. **Legacy `.ppt`** — python-pptx only reads OOXML. Convert to `.pptx` first via LibreOffice; see `/mnt/skills/public/pptx/SKILL.md` for the sandbox-safe `scripts/office/soffice.py` wrapper (bare `soffice` hangs here because the seccomp filter blocks the `AF_UNIX` sockets LibreOffice uses for instance management). For anything beyond reading, go to `/mnt/skills/public/pptx/SKILL.md`. --- ## CSV / TSV **Do not** `cat` or `head` these blindly. A CSV with a 50KB quoted cell in row 1 will wreck your `head -5`. Use pandas with `nrows`: ```python import pandas as pd df = pd.read_csv("/mnt/user-data/uploads/data.csv", nrows=5) print(df) print() print(df.dtypes) ``` Approximate row count without loading (over-counts if the file has RFC-4180 quoted newlines — the same quoted-cell case this section warned about above): ```bash wc -l /mnt/user-data/uploads/data.csv ``` Full analysis only after you know the shape: ```python df = pd.read_csv("/mnt/user-data/uploads/data.csv") print(df.describe()) ``` TSV: same, with `sep="\t"`. --- ## JSON / JSONL Structure first, content second: ```bash jq 'type' /mnt/user-data/uploads/data.json jq 'if type == "array" then length elif type == "object" then keys else . end' /mnt/user-data/uploads/data.json ``` (`keys` errors on scalar JSON roots — a bare `"hello"` or `42` is valid JSON per RFC 7159 — so guard the branch.) Then drill into what the user actually asked about. JSONL (one object per line) — do **not** `jq` the whole file; work line by line: ```bash head -3 /mnt/user-data/uploads/data.jsonl | jq . wc -l /mnt/user-data/uploads/data.jsonl ``` --- ## Images (JPG / PNG / GIF / WEBP) **You can already see uploaded images.** They are injected into your context as vision inputs alongside the `<uploaded_files>` pointer. You do not need to read them from disk to describe them. The disk copy is only needed if you are going to **process** the image programmatically: ```python from PIL import Image img = Image.open("/mnt/user-data/uploads/photo.jpg") print(img.size, img.mode, img.format) ``` For OCR on an image (text extraction, not description): ```python import pytesseract print(pytesseract.image_to_string(img)) ``` Note: the client resizes images larger than 2000×2000 down to that bound and re-encodes as JPEG before upload, so the disk copy may not be the user's original bytes. For most processing this doesn't matter; if the user is asking about original-resolution pixel data, flag it. --- ## Archives (ZIP / TAR / TAR.GZ) **List first. Extract never — unless the user explicitly asks.** Archives can be huge, contain path traversal, or nest forever. ```bash unzip -l /mnt/user-data/uploads/bundle.zip tar -tf /mnt/user-data/uploads/bundle.tar ``` GNU tar auto-detects compression — `tar -tf` works on `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz` alike. Don't hard-code `-z`. If the user wants one file from inside, extract just that one: ```bash unzip -p /mnt/user-data/uploads/bundle.zip path/inside/file.txt ``` **Standalone `.gz`** (not a tar) compresses a single file — there is no manifest to list. Just peek at the decompressed content: ```bash zcat /mnt/user-data/uploads/data.json.gz | head -50 ``` --- ## EPUB / ODT ```bash pandoc /mnt/user-data/uploads/book.epub -t plain | head -200 ``` For long ebooks, pipe through `head` — you rarely need the whole thing to answer a question. --- ## RTF Pandoc's RTF reader was added in 3.1.7 (Oct 2023). Debian Bookworm ships 2.17, so try pandoc first but expect it may fail: ```bash pandoc /mnt/user-data/uploads/notes.rtf -t plain | head -200 ``` If you see `Unknown input format rtf`, convert via LibreOffice using the sandbox-safe wrapper — see `/mnt/skills/public/docx/SKILL.md` for `scripts/office/soffice.py` (do not call bare `soffice`; see the PPTX section above for why). --- ## Plain text / code / logs Check the size first: ```bash wc -c /mnt/user-data/uploads/app.log ``` - **Under ~20KB**: `cat` is fine. - **Over ~20KB**: `head -100` and `tail -100` to orient. If the user asked about something specific, `grep` for it. Load the whole thing only if you genuinely need all of it. For log files, the user almost always cares about the end: ```bash tail -200 /mnt/user-data/uploads/app.log ``` --- ## Unknown extension ```bash file /mnt/user-data/uploads/mystery.bin xxd /mnt/user-data/uploads/mystery.bin | head -5 ``` `file` identifies most things. `xxd` head shows magic bytes. If `file` says "data" and the hex doesn't match anything you recognize, ask the user what it is instead of guessing.