How to use the Universal Document Reader agent skill (doc-reader)

What an agent skill is and what doc-reader adds

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to use a particular capability. The doc-reader skill is one such folder. Once it is available to your agent, the agent can call the read_document tool on a file path you give it.

The tool picks the right reader from the file extension, so you do not need to name a format. It supports PDF, Word (.docx), Excel (.xlsx/.xls), PowerPoint (.pptx), images via OCR (optical character recognition), CSV/TSV, plain text, JSON/YAML/TOML, HTML/XML and most source-code files. Every format comes back in the same JSON envelope with a status, file name, format, character count, truncated flag and text.

Install the doc-reader skill

You can install the skill in one of three ways. Download the ZIP from the skill's page on this site and unzip it into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it limited to one project. Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the ZIP there.

The download contains a single file, SKILL.md. Check that the unzipped folder contains SKILL.md at its top level so the agent can find it.

Note that the read_document tool itself must be available in the host agent. The skill file describes the tool; it does not replace it.

• Personal: unzip into ~/.claude/skills/
• Per project: unzip into .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills → upload the ZIP

Ask for a file to be read with natural requests

You do not need special syntax. Mention the file and what you want done with it. The agent calls read_document with the file path. Files should be in the folder the host agent can access; the source uses an uploads/ path in its examples.

For long PDFs you can ask for a page range. The pages parameter applies only to PDFs and is ignored for other formats.

• "Read uploads/paper.pdf and summarise the methodology and conclusion."
• "Read pages 1-10 of annual_report.pdf and list the main risks."
• "Review contract.docx and flag the termination, liability, payment and IP clauses."
• "Show me the sheets in sales.xlsx."
• "Read config.yaml and tell me which settings control the database connection."

Set up OCR for scanned pages and images

Text-based PDFs and Word files need no OCR. Scanned PDF pages and image files (.png, .jpg, .jpeg, .gif, .bmp, .webp, .tiff) do. Without an OCR engine, image and scanned files return empty text with a note field, and the agent should tell you rather than guess.

The local engine is rapid, which uses the rapidocr_onnxruntime Python package and runs offline. Install it with pip. The cloud engine is llm-vision, which sends page images to your configured vision-capable LLM provider and reuses your existing LANGCHAIN_PROVIDER and API key settings. Choose the engine with VIBE_TRADING_OCR_ENGINE: auto (default, local engines only), rapid, llm-vision, or none. You can override the OCR model with VIBE_TRADING_OCR_LLM_MODEL without changing the agent's main model.

• auto: local engines only, pages never leave the machine
• rapid: local RapidOCR
• llm-vision: cloud, pages are sent to your LLM provider
• none: OCR disabled

Read the results and understand the limits

Responses are capped: content longer than 15,000 characters is truncated, and the truncated flag tells you so. For PDFs, use the pages parameter to read slices. PDF responses also report total_pages, pages_read, ocr_pages, ocr_engine, ocr_quality and skipped_pages, which help you judge whether OCR worked.

Excel previews show the first 100 rows of each sheet. That is enough for a quick look but not for full analysis. Archives (.zip, .tar and similar) and executables are blocked at upload and must be unpacked locally first. Source code comes back raw and is not reformatted.

• Text cap: about 15,000 characters per response
• Excel: 100 rows per sheet in the preview
• Blocked: executables (.exe, .dll, .so) and archives (.zip, .tar)
• Unknown extensions are read as best-effort UTF-8 or GBK text

Check safety before using the skill

This skill runs scripts and can use the network. Read the SKILL.md and decide whether that fits your setup before installing. The tool reads files you point it at, so only give it documents you are comfortable having processed.

If you use the llm-vision OCR engine, the page images are sent to a cloud LLM provider. For confidential documents, stay on auto or rapid so pages never leave your machine, or check your confidentiality rules first. Keep API keys in your environment configuration rather than in documents you share with the agent.

• Runs scripts: yes
• Uses network: yes, only when the llm-vision engine is selected
• Do not use llm-vision for sensitive documents if rules forbid sending pages to a cloud provider

Tips for better results

Name the file path exactly and say what you want back. Asking for a summary, a list of clauses, or the sheet names gives the agent a clear target. If a PDF returns little text, check ocr_quality and skipped_pages before assuming the file is empty.

For spreadsheets where you need every row, do not rely on the preview. The source names the companion analyze_trade_journal tool for trade journal analysis; for other data, use another method that reads the full file.

• Give the exact file path and the output you want
• Use pages for long PDFs
• Check ocr_quality if scanned text looks wrong or missing
• Do not expect full data from large spreadsheets