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.

   bashCopy code
   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.

extract-text

For docx, odt, epub, xlsx, pptx, rtf, and ipynb the first move is extract-text <file>. It emits markdown for docx/odt/epub (headings, bold, lists, links, tables), tab-separated rows under ## Sheet: headers for xlsx, text under ## Slide N headers for pptx, fenced code cells for ipynb, and plain text for rtf. Pass --format <fmt> when the extension is wrong or absent (e.g., --format xlsx on an .xlsm). If it errors on a file, pandoc <file> -t plain is a fallback; for xlsx/pptx, fall back to the dedicated skill's Python-based approach (openpyxl / python-pptx).

Dispatch table

PDF

Never cat a PDF — it prints binary garbage.

Quick first move — get the page count and check if text is extractable:

bashCopy code
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:

pythonCopy code
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:

bashCopy code
extract-text /mnt/user-data/uploads/memo.docx | 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 an .xlsx:

bashCopy code
extract-text /mnt/user-data/uploads/data.xlsx | head -100

For .xlsm, add --format xlsx (same zip structure; only the extension differs). When you need a structured preview in Python:

pythonCopy code
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:

pythonCopy code
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:

pythonCopy code
import pandas as pd
df = pd.read_excel("/mnt/user-data/uploads/data.ods", engine="odf", nrows=5)

PPTX

bashCopy code
extract-text /mnt/user-data/uploads/deck.pptx | head -200

Legacy .ppt — 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:

pythonCopy code
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):

bashCopy code
wc -l /mnt/user-data/uploads/data.csv

Full analysis only after you know the shape:

pythonCopy code
df = pd.read_csv("/mnt/user-data/uploads/data.csv")
print(df.describe())

TSV: same, with sep="\t".

JSON / JSONL

Structure first, content second:

bashCopy code
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:

bashCopy code
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:

pythonCopy code
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):

pythonCopy code
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.

bashCopy code
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:

bashCopy code
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:

bashCopy code
zcat /mnt/user-data/uploads/data.json.gz | head -50

EPUB / ODT

bashCopy code
extract-text /mnt/user-data/uploads/book.epub | head -200

For long ebooks, pipe through head — you rarely need the whole thing to answer a question.

RTF / IPYNB

bashCopy code
extract-text /mnt/user-data/uploads/notes.rtf | head -200
extract-text /mnt/user-data/uploads/notebook.ipynb | head -200

Plain text / code / logs

Check the size first:

bashCopy code
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:

bashCopy code
tail -200 /mnt/user-data/uploads/app.log

Unknown extension

bashCopy code
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.