Transcribe

---
name: transcribe
triggers: [transcribe, ocr, screenshot, text in image, handwriting, scan, extract text, image]
description: OCR transcription for images with text
cli: true
file_types: [png, jpg, jpeg, gif, webp, bmp, tiff, tif, heic, heif]
companion_skills: [notes, untrusted_input]
dependencies: [pytesseract]
---
# Image Transcription with OCR

When you receive images containing text (screenshots, documents, handwritten notes), use the OCR skill to get a text extraction, then compare with what you see.

Image attachments are OCR'd automatically before you are asked anything, and the result is already in your prompt under "Image attachment OCR (untrusted text)". Read that first. Run the command below when you need a second attempt — a poor scan worth `--preprocess`, a file the automatic pass could not reach, or an image you produced or fetched yourself during the task.

## Usage

```bash
istota-skill transcribe ocr /path/to/image.png
istota-skill transcribe ocr /path/to/image.png --preprocess
```

Use `--preprocess` for low-contrast or noisy images. This applies grayscale conversion and contrast enhancement.

## Output

```json
{
  "status": "ok",
  "text": "Extracted text here...",
  "confidence": 0.85,
  "word_count": 42
}
```

- **text**: The extracted text content
- **confidence**: Average OCR confidence (0-1 scale). Below 0.7 suggests poor image quality or unusual fonts.
- **word_count**: Number of words detected

## Reconciliation Guidelines

When transcribing images:

1. Run the OCR skill to get machine-extracted text
2. Compare with what you see in the image
3. Reconcile differences:
   - **Trust OCR for**: exact spelling, numbers, codes, unusual words
   - **Trust your vision for**: layout, formatting, context, semantic meaning
4. Flag uncertainties with [?] if OCR and vision disagree significantly

## When to Use

- Screenshots with text content
- Scanned documents
- Handwritten notes (use `--preprocess`)
- Images where exact text matters (codes, IDs, addresses)
- Low-quality or small text that's hard to read visually

## Examples

Extract text from a screenshot:
```bash
istota-skill transcribe ocr {workspace}/inbox/screenshot.png
```

Process a handwritten note with preprocessing:
```bash
istota-skill transcribe ocr {workspace}/inbox/handwritten_note.jpg --preprocess
```

## Transcription procedure

This procedure applies only when the user asks you to transcribe an image, or to save the text in one. An image sent with any other request — or with none — is not a transcription request: answer what was actually asked, using the image and the OCR text together. A photograph of a dog is not a document, and saving a note about it is not what the sender wanted.

### Saving

- Once the user has asked for a transcription, save it without asking "should I save this?" again
- For where to save, follow the notes skill save location rules

### Title

- Choose a memorable or representative sentence (or fragment) from the transcribed content
- Only capitalize the first letter, not every word
- Never include a title header in the note body — the filename is the title

### Frontmatter

Every transcription note must include YAML frontmatter:
- `created`: date in YYYY-MM-DD format
- `tags`: 1-5 tags. If the user has a canonical tag list (in resources or memory), choose only from it. Otherwise, generate a few descriptive lowercase tags based on the content. Tags go in frontmatter only, never as inline hashtags in the body

Example:
```
---
created: 2026-01-29
tags: [screenshot, philosophy]
---

The transcribed content goes here...

---

*Commentary in italics*
```

### Commentary

After the transcription body, append any relevant commentary or context about the topic in italics, separated by a horizontal rule (`---`). Skip commentary if you have nothing meaningful to add.