# ocr-super-surya

A skill that runs OCR over images, screenshots and PDFs with Surya on GPU. Useful when a document only carries its text inside pictures.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 558 installs · ★ 26
- Author: yamapan (https://github.com/aktsmm)
- License: LicenseRef-CC-BY-NC-SA-4.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/aktsmm/Agent-Skills/tree/HEAD/ocr-super-surya/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/ocr-super-surya

## What it 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`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ocr-super-surya/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ocr-super-surya/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ocr-super-surya/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ocr-super-surya/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install aktsmm/Agent-Skills ocr-super-surya
```

2. **Manually: put the files in place**
- File: `.github/skills/ocr-super-surya/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/aktsmm/Agent-Skills --path ocr-super-surya
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ocr-super-surya/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add aktsmm/Agent-Skills --skill ocr-super-surya -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/aktsmm/Agent-Skills/tree/HEAD/ocr-super-surya/SKILL.md

## When to use it
- 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
- 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

## Similar
- [PDF OCR Extraction](https://affpapa.org/en/nevibecode/skills/pdf-ocr-extraction.md) — skill · 5700 installs
- [silicon-paddle-ocr](https://affpapa.org/en/nevibecode/skills/silicon-paddle-ocr.md) — skill · 1200 installs
- [transloadit-media-processing](https://affpapa.org/en/nevibecode/skills/transloadit-media-processing.md) — skill · 8700 installs
- [nutrient-document-processing](https://affpapa.org/en/nevibecode/skills/nutrient-sdk-nutrient-document-processing.md) — skill · 468 installs
- [markitdown](https://affpapa.org/en/nevibecode/skills/julianobarbosa-markitdown.md) — skill · 1600 installs
- [liteparse](https://affpapa.org/en/nevibecode/skills/k-dense-ai-liteparse.md) — skill · 1400 installs

From the same set: [aktsmm/agent-skills](https://affpapa.org/en/nevibecode/by/aktsmm/agent-skills.md) — 2 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md