Claude Code OCR Skill: Extract Text from Screenshots and Docs in Your Agent

If you searched for Claude Code OCR, you probably want text out of screenshots, PDF pages, receipts, or UI dumps while you work in Anthropic’s CLI coding agent. Claude Code does not ship a built-in OCR product. You get image-to-text two ways: ask Claude to read a file with its vision capabilities in the session, or install a skill that calls a dedicated OCR API when you need bulk extraction, stable Markdown, or typed JSON.

Short answer: for one screenshot and a question, Claude Code vision is often enough. For many files, predictable schemas, or cost control on dense scans, a Claude Code OCR skill that shells out to an API such as OCRskill is the cleaner path. Claude still does the reasoning; the skill handles the pixels-to-text step.

Claude Code skills vs Claude chat Skills

Claude Code skills are folders with a SKILL.md file (YAML frontmatter plus markdown instructions). Anthropic documents them at code.claude.com/docs/en/skills. You place them under ~/.claude/skills/<skill-name>/ for personal use across projects, or under .claude/skills/<skill-name>/ in a repo so the team shares the same procedure. Invoke with /skill-name, or let Claude load the skill when your request matches the description field.

That is different from the creative Skills you may see in claude.ai for media workflows. If you want a long-form Claude.ai skill that builds thumbnails and carousels, that is a separate tutorial (build ultimate Claude OCR skill for media). This post is only about Claude Code: agent sessions, /skill-name invocation, and when to call an OCR API from the skill instead of relying on in-session vision alone.

For the general FAQ on Claude vision versus OCR (not CLI-specific), see Does Claude have OCR?.

When Claude Code vision is enough

Drop a PNG into the conversation, or point Claude at a local image or PDF page, and ask what it says. Vision shines when:

you have one or two screenshots and want an explanation or a fix
layout, charts, or UI chrome matter as much as the raw characters
you are iterating on a bug and need Claude to reason about what it sees
volume is low enough that vision token cost is not the bottleneck

Anthropic’s vision docs cover image formats (JPEG, PNG, GIF, WebP), how images become tokens, and known weak spots such as tiny crops and dense numeric tables. Treat high-stakes digits (totals, IDs, account numbers) as something to validate even when the read looks good.

When a Claude Code OCR skill wins

A skill plus a dedicated OCR API fits better when:

you have dozens or hundreds of screenshots, scans, or PDF pages
you want the same Markdown shape every time for notes, RAG chunks, or git diffs
you need named fields (invoice date, total, license plate) as typed JSON
you want extraction priced and logged separately from chat tokens
Claude should reason on the resulting text without re-paying vision tokens for every pass

The mental model is simple. Vision answers “what is going on in this image?” An OCR skill answers “give me the text (or fields) so I can keep working.” Many workflows use both: OCRskill for extraction, Claude Code for decisions on the output.

Minimal Claude Code OCR skill

Create a skill directory named ocrskill so the slash command is /ocrskill. Personal install:

mkdir -p ~/.claude/skills/ocrskill

Project install (share with the repo):

mkdir -p .claude/skills/ocrskill

Save this as SKILL.md in that directory:

---
name: ocrskill
description: Extract text or typed fields from images and PDFs via the OCRskill API. Use when the user asks for OCR, image-to-text, screenshot text, receipt fields, or Claude Code OCR on local files. Prefer this over pasting large scans into vision when they want Markdown or JSON for many files.
---

# OCRskill OCR for Claude Code

Read `OCRSKILL_API_KEY` from the environment. Never print or commit the key.

## Markdown text (default)

For a local image or document, run:

```bash
curl https://api.ocrskill.com/ocr \
  -H "Authorization: Bearer $OCRSKILL_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary "@$FILE"
```

Adjust `Content-Type` to match the file (`image/jpeg`, `image/webp`, `application/pdf`, etc.). Multipart also works:

```bash
curl https://api.ocrskill.com/ocr \
  -H "Authorization: Bearer $OCRSKILL_API_KEY" \
  -F "image=@$FILE"
```

Return the response body to the user as Markdown. If they gave several files, process them one by one and label each result with the source path.

## Structured JSON (when they name fields)

If the user asks for specific fields (for example `invoice_date`, `total`, `vendor`):

```bash
curl "https://api.ocrskill.com/ocr.json?fields=$FIELDS" \
  -H "Authorization: Bearer $OCRSKILL_API_KEY" \
  -F "file=@$FILE"
```

Return the JSON object. Do not invent fields that were not requested.

## When not to call the API

If the user only wants a quick answer about one screenshot already in context, use Claude vision instead of calling the API. Prefer the API for bulk files, stable Markdown, or typed schemas.

Keep SKILL.md focused. Official guidance allows supporting scripts under the skill directory; move long reference material out of the main file so you do not burn context every time the skill loads. The description field is how Claude decides to auto-load the skill, so put trigger phrases (OCR, screenshot text, receipt fields) there first.

Install and invoke

Get a free API key: curl https://api.ocrskill.com/get-key.json
Export it in your shell profile or session: export OCRSKILL_API_KEY="sk-your-key-here"
Write SKILL.md under the personal or project path above
Start Claude Code (claude) in a project
Invoke with /ocrskill path/to/screenshot.png, or ask in natural language (“OCR these receipts into Markdown”)

Claude Code watches skill directories and picks up new SKILL.md files without a full reinstall. If auto-trigger feels weak, invoke /ocrskill directly and tighten the description with the phrases you actually type.

Do not put the API key inside SKILL.md or commit it to git. Env vars keep secrets out of the skill tree and out of chat history you might share.

Runnable API examples (what the skill calls)

Markdown from a PNG (simplified --data-binary upload):

export OCRSKILL_API_KEY="sk-your-key-here"

curl https://api.ocrskill.com/ocr \
  -H "Authorization: Bearer $OCRSKILL_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary "@ui-dump.png"

Typed fields from a receipt (structured /ocr.json):

curl "https://api.ocrskill.com/ocr.json?fields=vendor,receipt_date,total" \
  -H "Authorization: Bearer $OCRSKILL_API_KEY" \
  -F "file=@receipt.jpg"

Supported inputs include common image types (PNG, JPEG, WebP, GIF). /ocr.json also accepts PDFs and other docs per site docs, with a 20 MB max size. Auth is always Authorization: Bearer plus your key.

Pitfalls worth avoiding

Vague skill descriptions. If Claude never loads the skill, the description probably does not match how you ask. Include “Claude Code OCR”, “screenshot”, and “receipt” style phrases, or always type /ocrskill.

Keys in the repo. A committed sk-... in a sample skill is a credential leak. Use OCRSKILL_API_KEY and document the export in README, not in the skill body with a real value.

Vision on huge scans. Feeding multi-page full-resolution pages into the chat burns tokens. Prefer the OCR skill for bulk text, then ask Claude to reason on the Markdown or JSON.

Trusting every digit. OCR APIs and vision models can still misread dense tables. Validate totals, IDs, and codes before you write them into production data.

Wrong tool for the job. Creative thumbnail Skills in Claude chat are not a substitute for a Claude Code agent skill that shells to /ocr. Pick the surface that matches your workflow.

Pair extraction with reasoning

A Claude Code OCR skill does not replace Claude. It feeds Claude better evidence. Extract Markdown or typed JSON with OCRskill, then let Claude Code refactor code against a UI dump, draft a commit message from a ticket screenshot, or map invoice fields into your schema. That split keeps extraction cheap and predictable while you spend model capacity on the work only an agent can do.

Install the skill, put the key in the environment, and try /ocrskill on the next screenshot that would otherwise clog your context window.