Agent skill

Universal Document Reader

Reads PDF, Word, Excel, PowerPoint, image (OCR), CSV, text, config and source files through one read_document tool that returns extracted text in a uniform JSON envelope.

MITAuto-check: notesDocuments & Office

Install Universal Document Reader

skills CLI

$ npx skills add HKUDS/Vibe-Trading --skill doc-reader -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install HKUDS/Vibe-Trading doc-reader --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .claude/skills && cp -r skills-src/agent/src/skills/doc-reader .claude/skills/doc-reader && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "doc-reader" agent skill from https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader into .claude/skills/doc-reader/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "doc-reader", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add HKUDS/Vibe-Trading --skill doc-reader -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install HKUDS/Vibe-Trading doc-reader --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .agents/skills && cp -r skills-src/agent/src/skills/doc-reader .agents/skills/doc-reader && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "doc-reader" agent skill from https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader into .agents/skills/doc-reader/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "doc-reader", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add HKUDS/Vibe-Trading --skill doc-reader -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install HKUDS/Vibe-Trading doc-reader --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/agent/src/skills/doc-reader .cursor/skills/doc-reader && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "doc-reader" agent skill from https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader into .cursor/skills/doc-reader/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "doc-reader", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/HKUDS/Vibe-Trading.git --path agent/src/skills/doc-reader

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add HKUDS/Vibe-Trading --skill doc-reader -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install HKUDS/Vibe-Trading doc-reader --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/agent/src/skills/doc-reader .gemini/skills/doc-reader && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "doc-reader" agent skill from https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader into .gemini/skills/doc-reader/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "doc-reader", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install HKUDS/Vibe-Trading doc-reader

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add HKUDS/Vibe-Trading --skill doc-reader -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .github/skills && cp -r skills-src/agent/src/skills/doc-reader .github/skills/doc-reader && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "doc-reader" agent skill from https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader into .github/skills/doc-reader/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "doc-reader", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add HKUDS/Vibe-Trading --skill doc-reader -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install HKUDS/Vibe-Trading doc-reader --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/HKUDS/Vibe-Trading.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/agent/src/skills/doc-reader .opencode/skills/doc-reader && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "doc-reader" agent skill from https://github.com/HKUDS/Vibe-Trading/tree/main/agent/src/skills/doc-reader into .opencode/skills/doc-reader/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "doc-reader", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: doc-reader
GitHub stars: 35k
Token cost: ~1.5k tokens
SKILL.md length: 534 words
Files: 1
Skills in repo: 89
Repo updated: Oct 6, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Reads PDF, Word, Excel, PowerPoint, image (OCR), CSV, text, config and source files through one read_document tool that returns extracted text in a uniform JSON envelope.

Extracting text from a PDF, including scanned pages
SKILL.md covers Purpose, Usage, Return envelope and Workflows, plus 2 more sections
Calls pip
Reading a contract in Word to flag key clauses

What it does

A single read_document tool dispatches by file extension, so the agent calls the same tool for every format and always gets back the same JSON structure with the extracted text. PDFs use fast text extraction and fall back to OCR for scanned pages, Word files return paragraphs and table cells, Excel files return all sheets with a 100-row preview each, PowerPoint returns slide text and images go through OCR.

Other text-like formats such as CSV, JSON, YAML, HTML and source code come back as raw text with an encoding fallback. A pages parameter slices PDFs, and content over 15000 characters is truncated, so long documents are read in parts. Executables and archives are rejected at upload, and the agent should ask you to unpack archives first. Suggested workflows cover summarizing a paper, flagging key contract clauses and taking a quick look at a spreadsheet.

When your agent uses it

Extracting text from a PDF, including scanned pages
Reading a contract in Word to flag key clauses
Getting a quick preview of every sheet in an Excel workbook
Summarizing a paper or annual report from a PDF

Example prompts

“Read uploads/annual_report.pdf pages 1-10 and summarize the business outlook.”
“Open uploads/contract.docx and flag the termination, liability and payment clauses.”
“Preview the sheets in sales.xlsx.”
“Extract the text from this scanned receipt image.”

Requirements

The read_document tool

What it can do on your machine

Read from SKILL.md and the folder at commit 7f6908b. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- pip
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Universal Document Reader loads about 1.5k tokens when it runs. Until then it costs about 56 tokens; SKILL.md has 534 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~56
When it runs · the whole SKILL.md, loaded when a task matches: ~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

NoteMentions a .env fileSKILL.md:25

nfig | `.json/.yaml/.yml/.toml/.ini/.cfg/.env` | Raw text |

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from HKUDS/Vibe-Trading at commit 7f6908b, republished under its MIT licence (© HKUDS). 534 words, ~1,504 tokens.

Download SKILL.mdSave it as .claude/skills/doc-reader/SKILL.md (or your agent's skills folder).

name: doc-reader
description: Read any common document/data file — PDF, Word (.docx), Excel (.xlsx/.xls), PowerPoint (.pptx), images (OCR), CSV/TSV, plain text, JSON/YAML/TOML, HTML/XML, and most source-code files. Use the `read_document` tool.
category: tool

Universal Document Reader

Purpose

Return extracted text from any supported file in a single unified JSON envelope. The tool dispatches by file extension — you always call the same tool regardless of format.

Supported formats

Category	Extensions	Notes
PDF	`.pdf`	Text pages extracted in ms; scanned/image pages fall back to OCR
Word	`.docx`	Paragraphs + table cells
Excel	`.xlsx`, `.xls`	All sheets, first 100 rows per sheet as preview
PowerPoint	`.pptx`	Slide text content
Images	`.png/.jpg/.jpeg/.gif/.bmp/.webp/.tiff`	OCR only
CSV / TSV	`.csv`, `.tsv`	Raw text with encoding fallback
Plain text	`.txt/.md/.log/.rst`	Encoding fallback
Config	`.json/.yaml/.yml/.toml/.ini/.cfg/.env`	Raw text
Markup	`.html/.htm/.xml`	Raw text (no HTML stripping)
Source code	`.py/.js/.ts/.tsx/.go/.rs/.java/.cpp/.c/.sql/.sh/...`	Raw text
Unknown extension	anything else	Best-effort read as UTF-8/GBK text

Blocked (rejected at /upload): executables (.exe/.dll/.so/...) and archives (.zip/.tar/...). Ask the user to unpack archives locally first.

Usage

Always call the tool directly — do not run Python from bash.

read_document(file_path="uploads/paper.pdf")
read_document(file_path="uploads/annual_report.pdf", pages="1-10")
read_document(file_path="uploads/contract.docx")
read_document(file_path="uploads/sales.xlsx")
read_document(file_path="uploads/deck.pptx")
read_document(file_path="uploads/chart.png")     # image → OCR
read_document(file_path="uploads/config.yaml")
read_document(file_path="uploads/notes.md")

The pages parameter only applies to PDF; other formats ignore it.

Return envelope

All formats share this shape:

json

{
  "status": "ok",
  "file": "paper.pdf",
  "format": "pdf",
  "char_count": 52000,
  "truncated": true,
  "text": "..."
}

Format-specific extra fields:

Format	Extra keys
`pdf`	`total_pages`, `pages_read`, `ocr_pages`, `ocr_engine`, `ocr_quality`, `skipped_pages`
`docx`	`paragraphs`, `tables`
`excel`	`sheets` (array of `{name, rows, cols}`)
`pptx`	`slides`
`text`	`encoding`, `size`

Content longer than 15000 chars is truncated; for PDFs use the pages parameter to read slices.

Workflows

Paper / report summary

1. read_document(file_path="paper.pdf")  → full text
2. Extract abstract, methodology, conclusion → summarize

Contract review

1. read_document(file_path="contract.docx")  → paragraphs + tables
2. Flag key clauses (termination, liability, payment, IP)

Spreadsheet quick-look

1. read_document(file_path="sales.xlsx")  → all sheet previews
2. If user wants trade journal analysis specifically, pivot to
   `analyze_trade_journal` tool instead (see trade-journal skill).

Chart / screenshot / scanned PDF

1. read_document(file_path="scan.png")  → OCR text
2. If OCR returns empty, tell the user; don't fabricate.

OCR Configuration

The read_document tool automatically uses OCR for PDF pages with insufficient extractable text.

OCR Threshold

Use min_text_per_page to control when OCR is triggered (default: 50 characters):

python

read_document("scanned_report.pdf", min_text_per_page=10)  # More aggressive OCR
read_document("mixed_pdf.pdf", min_text_per_page=100)       # Less aggressive OCR

Show full SKILL.md (288 more words)Show less

OCR Engine Configuration

Two OCR engines are built in — no extra packages needed beyond the engine SDK:

Engine	Type	Requires	Install
`rapid`	Local (offline)	`rapidocr_onnxruntime`	`pip install rapidocr_onnxruntime`
`llm-vision`	Cloud	A vision-capable LLM model + API key	No extra install — uses your existing LLM provider config

The llm-vision engine works with any OpenAI-compatible vision model (GPT-4o, Qwen-VL, Gemini, Claude, GLM-4V, etc.). It reuses your existing LANGCHAIN_PROVIDER / LANGCHAIN_MODEL_NAME / API key configuration — no separate provider mapping needed. If you explicitly set VIBE_TRADING_OCR_ENGINE=llm-vision, your model choice is trusted; a real API error from the provider is clearer feedback than a heuristic guess.

To override the model used for OCR (without changing your agent's main model):

VIBE_TRADING_OCR_LLM_MODEL=qwen3.7-plus

Set VIBE_TRADING_OCR_ENGINE to select the engine:

auto (default): use local engines only, never cloud (privacy: document pages never leave the machine)
rapid: force RapidOCR (local, ONNX)
llm-vision: force LLM vision OCR (cloud — pages are sent to your configured LLM provider)
none: disable OCR entirely

Response Fields

PDF responses include OCR metadata:

ocr_engine: name of the OCR engine used (e.g. "rapid", "llm-vision") or null
ocr_pages: number of pages processed via OCR
skipped_pages: number of pages skipped (no OCR engine available)
ocr_quality: object with quality_flag (good/degraded/no_ocr_engine/no_ocr_needed), ocr_pages, and text_density (chars per page)

Notes

Encoding fallback order for text: utf-8 → utf-8-sig → gbk → gb2312 → big5 → latin-1.
OCR uses the configured engine (RapidOCR for local, or LLM vision for cloud). If no engine is available, image/scanned files return empty text with a note field — tell the user to install rapidocr-onnxruntime or set VIBE_TRADING_OCR_ENGINE=llm-vision with a vision-capable model.
Excel previews are limited to 100 rows per sheet to stay in budget. If the user needs full data (e.g. trade journals), call analyze_trade_journal instead.
Source-code files are returned raw; do not re-format or re-indent.

Files

Just SKILL.md in agent/src/skills/doc-reader of HKUDS/Vibe-Trading.

Open the folder on GitHubat commit 7f6908b

Compare with similar skills

Universal Document Reader next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Universal Document Reader compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Universal Document Reader this skillHKUDS/Vibe-Trading	35k	—	~1.5k	Automated safety check: Notes	MIT	yesterday
MarkitdownImCa0/just-laws	781	14 repos	~3.2k	Automated safety check: Notes	MIT	8 days ago
MinerU Document Readeropendatalab/MinerU	81k	—	~9.4k	Automated safety check: Warn	Custom licence	yesterday
Markitdownjimmc414/Kosmos	594	2 repos	~1.7k	Automated safety check: Pass	None	3 days ago
Markdown ConverterTeam-Commonly/commonly	1.4k	—	~557	Automated safety check: Pass	Apache-2.0	today
Nutrient Document Processingaffaan-m/ECC	274k	4 repos	~1.5k	Automated safety check: Pass	MIT	2 days ago

Similar skills

Markitdown
ImCa0/just-laws
Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws.
781 GitHub starsUsed in 14 repos~3.2k tokens
Documents & OfficeAuto-check: notes
MinerU Document Reader
opendatalab/MinerU
Reads, OCRs, searches and cites local documents through the mineru CLI, covering PDF, images, Office files, EPUB, HTML and CSV.
81k GitHub stars~9.4k tokensUpdated yesterday
Documents & OfficeAuto-check: warnings
Markitdown
jimmc414/Kosmos
Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing.
594 GitHub starsUsed in 2 repos~1.7k tokens
Documents & OfficeAuto-check passed
Markdown Converter
Team-Commonly/commonly
Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's markitdown Python tool.
1.4k GitHub stars~557 tokensUpdated today
Documents & OfficeAuto-check passed
Nutrient Document Processing
affaan-m/ECC
Process, convert, OCR, extract, redact, sign, and fill documents using the Nutrient DWS API.
274k GitHub starsUsed in 4 repos~1.5k tokens
Documents & OfficeAuto-check passed
Document Converter
wentorai/Research-Claw
Convert Office documents (PPTX, DOCX, XLSX, PDF, HTML, CSV, JSON, XML, images) to Markdown using Microsoft MarkItDown.
858 GitHub stars~1.3k tokensUpdated 1 mo ago
Documents & OfficeAuto-check passed

Questions about Universal Document Reader

What does Universal Document Reader do?

Reads PDF, Word, Excel, PowerPoint, image (OCR), CSV, text, config and source files through one read_document tool that returns extracted text in a uniform JSON envelope. A single read_document tool dispatches by file extension, so the agent calls the same tool for every format and always gets back the same JSON structure with the extracted text. PDFs use fast text extraction and fall back to OCR for scanned pages, Word files return paragraphs and table cells, Excel files return all sheets with a 100-row preview each, PowerPoint returns slide text and images go through OCR.

When should I use Universal Document Reader?

Universal Document Reader fits situations like: extracting text from a PDF, including scanned pages; reading a contract in Word to flag key clauses; getting a quick preview of every sheet in an Excel workbook; summarizing a paper or annual report from a PDF.

How do I install Universal Document Reader in Claude Code?

Run `npx skills add HKUDS/Vibe-Trading --skill doc-reader -a claude-code`. Or copy the skill folder (agent/src/skills/doc-reader in HKUDS/Vibe-Trading) into .claude/skills/doc-reader in your project. Claude Code loads it when a task matches its description.

How do I install Universal Document Reader in Codex?

Run `npx skills add HKUDS/Vibe-Trading --skill doc-reader -a codex`. Or copy the skill folder (agent/src/skills/doc-reader in HKUDS/Vibe-Trading) into .agents/skills/doc-reader in your project. Codex loads it when a task matches its description.

Can I use Universal Document Reader in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add HKUDS/Vibe-Trading --skill doc-reader -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/doc-reader, .gemini/skills/doc-reader, .github/skills/doc-reader and .opencode/skills/doc-reader in your project.

What does Universal Document Reader need to run?

Going by SKILL.md and its folder, Universal Document Reader needs the command-line tools its instructions call (pip). Our summary lists: The read_document tool.

Does Universal Document Reader access the network?

SKILL.md contains no URLs. Its commands use pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Universal Document Reader safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Universal Document Reader use?

Universal Document Reader is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Universal Document Reader use?

About 1.5k tokens (SKILL.md is roughly 6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Universal Document Reader?

Skills that share tags, products or a category with Universal Document Reader: Markitdown (ImCa0/just-laws, 781 stars), MinerU Document Reader (opendatalab/MinerU, 81k stars), Markitdown (jimmc414/Kosmos, 594 stars) and Markdown Converter (Team-Commonly/commonly, 1.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Universal Document Reader?

HKUDS (a GitHub organization) maintains it in HKUDS/Vibe-Trading, which has 34,884 GitHub stars. The repository holds 89 skills in this directory. The repository was last updated on October 6, 2026.

Source: HKUDS/Vibe-Trading on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Universal Document Reader

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Universal Document Reader

Purpose

Supported formats

Usage

Return envelope

Workflows

Paper / report summary

Contract review

Spreadsheet quick-look

Chart / screenshot / scanned PDF

OCR Configuration

OCR Threshold

OCR Engine Configuration

Response Fields

Notes

Files

Compare with similar skills

Similar skills

More from HKUDS/Vibe-Trading

Related

Questions about Universal Document Reader