# Heavy File Ingestion

Use when a user asks to read, analyze, summarize, or extract from a heavyweight file...

- Repository: https://github.com/NateBJones-Projects/OB1 (4752 stars)
- Category: Documents
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add NateBJones-Projects/OB1 --skill heavy-file-ingestion -g -a claude-code -y`
Codex: `npx skills add NateBJones-Projects/OB1 --skill heavy-file-ingestion -g -a codex -y`
Cursor: `npx skills add NateBJones-Projects/OB1 --skill heavy-file-ingestion -g -a cursor -y`
Gemini CLI: `npx skills add NateBJones-Projects/OB1 --skill heavy-file-ingestion -g -a gemini-cli -y`

## Description

Use when a user asks to read, analyze, summarize, or extract from a heavyweight file such as PDF, DOCX, PPTX, XLSX, CSV, or TSV. Convert the file into markdown or CSV first, generate a lightweight index, and only spend model tokens on the compressed artifact. Trigger on requests like "read this PDF", "look through this spreadsheet", "summarize this deck", or any time raw file ingestion would waste tokens.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.
1. **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.
1. **Match the converter to the file type.**
   - PDFs and documents: markdown artifact
   - Presentations: markdown slide outline
   - Spreadsheets: CSV per sheet plus a markdown manifest
1. **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.
1. Run the converter script instead of reading the original file directly:

```bash
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:

The rest: https://github.com/NateBJones-Projects/OB1/blob/HEAD/skills/heavy-file-ingestion/SKILL.md