Heavy File Ingestion

Problem

Agents waste money and context when they read heavyweight files raw. This skill turns bulky documents into cheaper working artifacts first, then tells the main agent how much reasoning power the file actually deserves.

Trigger Conditions

• The user asks to read or analyze a PDF, slide deck, spreadsheet, or word-processing file
• The file is large, structured, or expensive enough that raw ingestion is a bad trade
• The user wants a markdown working copy, CSV extraction, or a quick map of the file before analysis
• The agent needs a deterministic first pass before choosing whether a model fallback is worth the cost

Core Policy

1. Convert before reading. Do not dump raw heavyweight files into model context if a deterministic converter can create a cheaper artifact.
2. Index before reasoning. Read the generated index.md or index.json first. It should tell you what is in the file, how clean the extraction was, and whether escalation is justified.
3. Match the converter to the file type.
   • PDFs and documents: markdown artifact
   • Presentations: markdown slide outline
   • Spreadsheets: CSV per sheet plus a markdown manifest
4. Escalate by cost tier, not instinct.
   • Tier 1: deterministic converter plus index
   • Tier 2: cheap model on the extracted artifact only if quality flags say the deterministic pass lost structure
   • Tier 3: expensive model only after the file has already been compressed into markdown, CSV, or a sampled subset

Process

1. Identify the file path, extension, and rough size.
2. Run the converter script instead of reading the original file directly:

uv run \
  --with pdfplumber \
  --with python-docx \
  --with python-pptx \
  --with openpyxl \
  python skills/heavy-file-ingestion/scripts/convert_heavy_file.py /absolute/path/to/file.ext

1. If you already have markitdown installed and want to prefer it for PDF or DOCX conversion, rerun with: