ocr

OCR (PDF + Image)

Read PDF and image files with Claude's vision feature and convert them to markdown.

Supported Formats

Type	Extension
PDF	.pdf
Image	.png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff

Quick Start

# 단일 파일 (PDF 또는 이미지)
/ocr /path/to/document.pdf
/ocr /path/to/image.png

With custom instructions

/ocr /path/to/document.pdf "Extract only the tables" /ocr /path/to/screenshot.png "Extract only the code"

All PDFs/images in the folder (parallel processing)

/ocr /path/to/folder/

## Core Workflow

### Step 1: 경로 및 파일 타입 확인

```bash
# 파일인지 폴더인지 확인
ls -la <path>

File type classification:

• .pdf → PDF mode
• .png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff → Image mode
• Folder → Batch Modeproceed with

Step 2: Choose save method (PDF only)

Only for PDF files Ask the user for the save method:

AskUserQuestion:
  question: "PDF 변환 결과를 어떻게 저장할까요?"
  header: "저장 방식"
  options:
    - label: "통합 저장 (Recommended)"
      description: "모든 페이지를 하나의 마크다운 파일로 저장"
    - label: "페이지별 저장"
      description: "각 페이지를 개별 마크다운 파일로 저장 (document_p1.md, document_p2.md, ...)"

Save method variable:

• unified: Unified save → document.pdf → document.md
• per_page: Per-page save → document.pdf → document_p1.md, document_p2.md, ...

Image file: Without asking for a save method, directly image.png → image.mdconvert to

---

Single File Mode - Image

Single image file processing workflow.

IMPORTANT: Even for a single file, use a Task agent to protect the main context.

Task(subagent_type="general-purpose"):
  프롬프트: |
    이미지 파일을 OCR하여 마크다운으로 변환하고 저장해주세요.

    파일: [이미지 절대경로]
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 이미지 읽기
    2. 이미지 내용을 마크다운으로 변환
    3. Write 도구로 [파일명].md 파일 저장
    4. 저장 완료 확인

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [출력파일명].md
    또는
    ⚠️ 실패: [파일명] - [사유]

---

Single File Mode - PDF

Single PDF file processing workflow.

IMPORTANT: Even for a single file, use a Task agent to protect the main context.

Unified save mode (unified)

Task(subagent_type="general-purpose"):
  프롬프트: |
    PDF 파일을 OCR하여 마크다운으로 변환하고 저장해주세요.

    파일: [PDF 절대경로]
    저장 방식: 통합 (모든 페이지를 하나의 파일로)
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 PDF 읽기
    2. 모든 페이지를 하나의 마크다운으로 변환
    3. Write 도구로 [파일명].md 파일 저장
    4. 저장 완료 확인

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [출력파일명].md
    또는
    ⚠️ 실패: [파일명] - [사유]

Per-page save mode (per_page)

Task(subagent_type="general-purpose"):
  프롬프트: |
    PDF 파일을 OCR하여 페이지별로 마크다운 파일을 생성해주세요.

    파일: [PDF 절대경로]
    저장 방식: 페이지별 (각 페이지를 개별 파일로)
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 PDF 읽기
    2. 각 페이지별로 마크다운 변환
    3. 각 페이지를 개별 파일로 저장:
       - [파일명]_p1.md (1페이지)
       - [파일명]_p2.md (2페이지)
       - ...
    4. 모든 파일 저장 완료 확인

    **출력 파일 명명 규칙:**
    - document.pdf → document_p1.md, document_p2.md, document_p3.md, ...

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [N]개 페이지 파일 생성
       - [파일명]_p1.md
       - [파일명]_p2.md
       - ...
    또는
    ⚠️ 실패: [파일명] - [사유]

---

Batch Mode (folder processing)

Process multiple PDFs/images in a folder in parallel.

1. Collect and classify file list

# 폴더 내 지원 파일 목록
ls <folder_path>/*.{pdf,png,jpg,jpeg,webp,gif,bmp,tiff} 2>/dev/null

File classification:

• PDF file list: *.pdf
• Image file list: *.png, *.jpg, *.jpeg, *.webp, *.gif, *.bmp, *.tiff

2. Choose save method (only if PDFs are present)

Ask for save method only if PDF files are included:

AskUserQuestion:
  question: "PDF 변환 결과를 어떻게 저장할까요? (이미지는 항상 통합 저장)"
  header: "저장 방식"
  options:
    - label: "통합 저장 (Recommended)"
      description: "각 PDF의 모든 페이지를 하나의 마크다운 파일로 저장"
    - label: "페이지별 저장"
      description: "각 PDF의 페이지를 개별 마크다운 파일로 저장"

3. Batch splitting (in units of 3)

Split the files into groups of 3(PDFs and images can be mixed):

• Group 1: file1.pdf, image1.png, file2.pdf
• Group 2: image2.jpg, file3.pdf, image3.webp
• ...

4. Run parallel agents

For each group, Task toolrun parallel agents with:

Task(subagent_type="general-purpose"):
  프롬프트: |
    다음 파일들을 OCR하여 마크다운으로 변환해주세요.

    파일 목록:
    - [file1 절대경로]
    - [file2 절대경로]
    - [file3 절대경로]

    PDF 저장 방식: [unified 또는 per_page]
    커스텀 지침: [사용자 지침 있으면 포함]
    출력 폴더: [원본과 동일 폴더]

    **파일 타입별 처리:**
    - PDF (.pdf): 지정된 저장 방식 적용
    - 이미지 (.png, .jpg 등): 항상 통합 저장 (image.png → image.md)

    **CRITICAL - 각 파일에 대해 에이전트 내에서 완료:**
    1. Read 도구로 파일 읽기
    2. 에러 발생 시 skip하고 다음 파일로 (413 에러 등)
    3. 마크다운으로 변환
    4. **Write 도구로 파일 저장** (반드시 에이전트 내에서!)
    5. 저장 완료 확인

    **IMPORTANT**:
    - 변환된 마크다운 내용을 메인으로 반환하지 마세요
    - 파일 저장까지 에이전트 내에서 완료해야 합니다
    - 메인에는 처리 결과 상태만 반환합니다

    처리 결과를 다음 형식으로만 보고 (내용 제외):
    ✅ 성공: [파일명] → [출력파일명].md
    ⚠️ SKIP: [파일명] - [사유]

IMPORTANT:

• Call the Tasks for all groups simultaneously to run in parallel
• The agent completes both Read + Write and then returns only the status
• Prevent file contents from being loaded into the main context

5. Aggregate results

Aggregate results after all agents complete:

## 📊 OCR 처리 결과

### ✅ 성공 ([N]개)
**PDF:**
- document1.pdf → document1.md
- document2.pdf → document2_p1.md, document2_p2.md (페이지별)

**이미지:**
- screenshot.png → screenshot.md
- photo.jpg → photo.md

### ⚠️ Skip ([M]개)
- large_file.pdf - 파일 크기 초과 (413 에러)
- corrupted.png - 읽기 실패

### 📁 출력 위치
[folder_path]/

---

Markdown conversion guidelines

Analyze the file contents and convert to markdown in the following format:

# 문서 제목

## 섹션 1
본문 내용...

### 표
| 열1 | 열2 |
|-----|-----|
| 값  | 값  |

### 이미지/다이어그램 설명
[이미지 설명: ...]

Apply custom instructions

If the user provided additional instructions:

• "Extract only tables" → Only tabular data as a markdown table
• "Summarize" → Summarize only the key content
• "Translate to English" → Translated output
• "Extract code only" → extract only the code block

---

Supported Content Types

Content	Conversion Method
Plain Text	Keep as Markdown
Headings/Sections	Structure as # headings
표	Markdown Table
Lists	- or 1. format
Images/Diagrams	Describe in the form [image description]
Code	언어 code block
Formulas	LaTeX ($...$) format
Screenshot UI	Extract UI elements and text

Important Rules

Context Protection (Key)

• ALWAYS Complete both Read + Write within the Task agent
• ALWAYS The agent returns only the processing status (do not return the converted content)
• NEVER Do not load file contents into the main context

Processing Method

• ALWAYS Use the Read tool to read files (do not use libraries)
• ALWAYS Preserve the structure of the original document as much as possible
• ALWAYS If there are user custom instructions, apply them first
• ALWAYS On error, skip that file and continue processing the rest
• ALWAYS When processing a folder, run parallel agents in groups of 3
• NEVER Do not use external libraries (PyPDF, Pillow, etc.)
• NEVER Do not fill unreadable parts with guesses (mark as [unclear] when unclear)
• NEVER Do not process all files in a single context (prevent memory overflow)