file-reading skill

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/ and you are told the path in an 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.

stat -c '%s bytes, %y' /mnt/user-data/uploads/report.pdf
   file /mnt/user-data/uploads/report.pdf

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

1. Read just enough to answer the user's question. If they asked

you when. The dedicated skills cover editing, creating, and advanced operations that this skill does not.

1. If a dedicated skill exists, go read it. The table below tells

extract-text

For docx, odt, epub, xlsx, pptx, rtf, and ipynb the first move is extract-text . 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 when the extension is wrong or absent (e.g., --format xlsx on an .xlsm). If it errors on a file, pandoc -t plain is a fallback; for xlsx/pptx, fall back to the dedicated skill's Python-based approach (openpyxl / python-pptx).

Dispatch table

Where a dedicated skill is named below, invoke it by name if you have a Skill tool, or Read its SKILL.md (listed in your available skills, or in the same skills directory as this file).

PDF

Never cat a PDF — it prints binary garbage.

Quick first move — get the page count and determine whether the PDF has an extractable text layer:

pdfinfo /mnt/user-data/uploads/report.pdf
pdffonts /mnt/user-data/uploads/report.pdf

pdffonts tells you whether text extraction will work before you try it:

scan or raster export. pdftotext and PdfReader.extract_text() will return nothing useful. Go straight to page rasterization or OCR — see the pdf-reading skill → "Scanned documents".

• No fonts listed (empty table, just the header) → the PDF is a

• Fonts listed → there is a text layer; extract it:

pdftotext -f 1 -l 1 /mnt/user-data/uploads/report.pdf - | head -20

The reason to check pdffonts first is user-facing: running pdftotext on a scan produces an empty result, and in a visible transcript that reads as a failed first attempt before you fall back to OCR. The two-line diagnostic above costs one tool call and avoids that — you arrive at the right method on the first try, which is what a user perceives as "it just read my file."

That also shapes how to open your reply. The diagnostic commands are plumbing, not content; lead with what the user asked about. On a scanned receipt that might be "This is a 3-page scanned invoice; the amount due on page 2 is $1,845.00," and on a digitally-authored report it might be "The Q3 report runs 28 pages; revenue on p. 4 is $12.3M, up 9% YoY." What you're steering away from is the "I'll examine the PDF" / "Let me check if this is extractable" preamble — the answer to their question is the first thing they should see.

For anything beyond a quick peek — figures, tables, attachments, forms, scanned PDFs, visual inspection, or choosing a reading strategy — go read the pdf-reading skill. 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 the pdf skill.

DOCX / DOC

The docx skill covers editing, creating, tracked changes, images. Read it if you need any of those. For a quick look:

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:

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:

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)

readonly=True matters — without it, openpyxl loads the entire workbook into memory, which breaks on large files. Do not trust ws.maxrow 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:

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:

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

PPTX

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

Legacy .ppt — convert to .pptx first via LibreOffice; see the pptx skill 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 the pptx skill.

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:

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

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

Full analysis only after you know the shape:

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

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

JSON / JSONL

Structure first, content second:

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