ocr-super-surya — Claude Code OCR skill: read text from images
A skill that runs OCR over images, screenshots and PDFs with Surya on GPU. Useful when a document only carries its text inside pictures.
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a claude-codeWhat ocr-super-surya does
The skill wraps Surya and walks the agent through the order of operations: pull the native text layer out of a PDF or slide deck first, inventory the pages that have none, and send only those to recognition. For images it tells you to find the highest-resolution original rather than a chat thumbnail, crop the region you need and upscale it 4-7x with LANCZOS. Dense CJK glyphs fall apart at screen scale.
A helper script, scripts/ocr_helper.py, retries automatically when VRAM runs out and handles batches. Raw OCR output stays separate from corrected notes, and targets that came back empty or failed are reported on their own list. Every image gets a source path, source hash, page number and image hash, so duplicates keep their place in the document.
Check your interpreter and the installed packages before you start: surya, torch, pypdf, pypdfium2. The README calls out transformers 5.x specifically — Surya breaks on pad_token_id there, so you need the 4.x line. On Windows under OneDrive the uv install fails on hardlinks; move the cache and the environment outside OneDrive and install with --link-mode=copy.
What it helps with
- pull text off a screenshot or a photo of a page
- find PDF pages whose text lives only inside images
- recognize a document in several languages, Japanese included
- keep every recognized line tied to its page and source file
- separate unrecognized fragments from verified text
Example prompts for the agent
- OCR screenshot.png and save the text to result.txt
- some pages in this PDF have no text layer — find them and run OCR
- run OCR on this Japanese scan and flag the ambiguous characters separately
How to install ocr-super-surya
1Skills CLI (Vercel)
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a claude-code2Manually: put the files in place
~/.claude/skills/ocr-super-surya/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ocr-super-surya/
1Skills CLI (Vercel)
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a codex2Manually: put the files in place
.agents/skills/ocr-super-surya/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a cursor2Manually: put the files in place
.cursor/skills/ocr-super-surya/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aktsmm/Agent-Skills ocr-super-surya2Manually: put the files in place
.github/skills/ocr-super-surya/SKILL.md1Skills CLI (Vercel)
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a gemini-cli2Platform CLI
gemini skills install https://github.com/aktsmm/Agent-Skills --path ocr-super-suryaManually: put the files in place
.devin/skills/ocr-super-surya/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ocr-super-surya
How do I install ocr-super-surya in Claude?
Run npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a claude-code. The skill lands in ~/.claude/skills/ocr-super-surya/SKILL.md.
What does ocr-super-surya do?
It recognizes text in images and PDFs with Surya on GPU. It looks for an existing text layer first and sends only the pages and images that lack one to recognition.
Why does it fail with a pad_token_id error?
That is an incompatibility with transformers 5.x. Install the 4.x line instead: pip install "transformers<5.0".
