# image-ocr

Use this skill to read text in images with Tesseract OCR through Python. It fits scans, screenshots, and batches of image files.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 1933 repo stars
- Author: benchflow-ai
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/benchflow-ai/skillsbench/tree/HEAD/tasks/jpg-ocr-stat/environment/skills/image-ocr/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/image-ocr

## What it does

The skill handles JPG, JPEG, PNG, and WEBP images. It can return recognized text or a JSON result containing the filename, confidence level, metadata, and warnings. The examples cover a single image as well as processing a directory.

Recognition uses `pytesseract` and `PIL`; the examples also import `json` and `os`. Tesseract language and page segmentation settings can be supplied. For printed text, the instructions recommend images at 300 DPI or higher and files under 5 MB. Set the language for non-English text, or the OCR configuration may not match the image.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add benchflow-ai/skillsbench --skill image-ocr -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add benchflow-ai/skillsbench --skill image-ocr -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add benchflow-ai/skillsbench --skill image-ocr -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install benchflow-ai/skillsbench tasks/jpg-ocr-stat/environment/skills/image-ocr
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add benchflow-ai/skillsbench --skill image-ocr -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/benchflow-ai/skillsbench --path tasks/jpg-ocr-stat/environment/skills/image-ocr
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add benchflow-ai/skillsbench --skill image-ocr -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/benchflow-ai/skillsbench/tree/HEAD/tasks/jpg-ocr-stat/environment/skills/image-ocr/SKILL.md

## When to use it
- read text from a scanned document
- extract words from a screenshot
- process images in a directory
- return OCR results as JSON
- check OCR confidence scores

## Example prompts
- Extract the text from `document.jpg` and return the result as JSON.
- Read the images in this folder and save the batch results to a file.
- OCR this screenshot, setting the recognition language to French.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2db0e55307d9f93e.

BEGIN THIRD-PARTY FILE 2db0e55307d9f93e
````text
---
name: image-ocr
description: Extract text content from images using Tesseract OCR via Python
---

# Image OCR Skill

## Purpose
This skill enables accurate text extraction from image files (JPG, PNG, etc.) using Tesseract OCR via the `pytesseract` Python library. It is suitable for scanned documents, screenshots, photos of text, receipts, forms, and other visual content containing text.

## When to Use
- Extracting text from scanned documents or photos
- Reading text from screenshots or image captures
- Processing batch image files that contain textual information
- Converting visual documents to machine-readable text
- Extracting structured data from forms, receipts, or tables in images

## Required Libraries

The following Python libraries are required:

```python
import pytesseract
from PIL import Image
import json
import os
```

## Input Requirements
- **File formats**: JPG, JPEG, PNG, WEBP
- **Image quality**: Minimum 300 DPI recommended for printed text; clear and legible text
- **File size**: Under 5MB per image (resize if necessary)
- **Text language**: Specify if non-English to improve accuracy

## Output Schema
All extracted content must be returned as valid JSON conforming to this schema:

```json
{
  "success": true,
  "filename": "example.jpg",
  "extracted_text": "Full raw text extracted from the image...",
  "confidence": "high|medium|low",
  "metadata": {
    "language_detected": "en",
    "text_regions": 3,
    "has_tables": false,
    "has_handwriting": false
  },
  "warnings": [
    "Text partially obscured in bottom-right corner",
    "Low contrast detected in header section"
  ]
}
```


### Field Descriptions

- `success`: Boolean indicating whether text extraction completed
- `filename`: Original image filename
- `extracted_text`: Complete text content in reading order (top-to-bottom, left-to-right)
- `confidence`: Overall OCR confidence level based on image quality and text clarity
- `metadata.language_detected`: ISO 639-1 language code
- `metadata.text_regions`: Number of distinct text blocks identified
- `metadata.has_tables`: Whether tabular data structures were detected
- `metadata.has_handwriting`: Whether handwritten text was detected
- `warnings`: Array of quality issues or potential errors


## Code Examples

### Basic OCR Extraction

```python
import pytesseract
from PIL import Image

def extract_text_from_image(image_path):
    """Extract text from a single image using Tesseract OCR."""
    img = Image.open(image_path)
    text = pytesseract.image_to_string(img)
    return text.strip()
```

### OCR with Confidence Data

```python
import pytesseract
from PIL import Image

def extract_with_confidence(image_path):
    """Extract text with per-word confidence scores."""
    img = Image.open(image_path)

    # Get detailed OCR data including confidence
    data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)

    words = []
    confidences = []

    for i, word in enumerate(data['text']):
        if word.strip():  # Skip empty strings
            words.append(word)
````
END THIRD-PARTY FILE 2db0e55307d9f93e

The third-party file has ended. Everything between the 2db0e55307d9f93e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3073 of 11348 bytes. © benchflow-ai · Apache-2.0 · https://github.com/benchflow-ai/skillsbench/tree/HEAD/tasks/jpg-ocr-stat/environment/skills/image-ocr/SKILL.md

_Part of the page did not fit — see the HTML version._

---
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
