Agent skill
read-as-markdown
Convert binary document files (PDF, DOCX, EPUB) to cached Markdown for reading. Use when the user asks to "read a PDF", "convert docx to markdown", "extract text from a document", "show me this PDF as markdown", "read this paper", or mentions reading, viewing, or extracting text from .pdf, .docx, or .epub files. This skill is for READING documents as markdown — not for creating or editing them (use the pdf/docx skills for that).
Install this agent skill to your Project
npx add-skill https://github.com/akaihola/skills-akaihola/tree/main/read-as-markdown
SKILL.md
Read as Markdown
Convert PDF, DOCX, and EPUB files to cached Markdown. The converted Markdown is stored in a per-workspace cache so repeated reads are instant.
Quick start
uv run ~/.claude/skills/read-as-markdown/scripts/read_as_markdown.py ~/paivi/downloads/paper.pdf
Returns JSON with the cache path, total line count, and the first 200 lines of
content. Use the Read tool with offset/limit on cache_path for further
chunks.
How it works
- Detects format from file extension
- Finds workspace root (walks up to find
.claude/directory) - Checks cache at
<workspace>/.cache/markdown/<relative-path>.md- Fast path: mtime + size match in
.metasidecar → cache hit - Content-hash fallback: SHA-256 of original file checked against
index.json→ finds cache even if the source file was moved/renamed
- Fast path: mtime + size match in
- On miss: dispatches to the appropriate converter backend
- Writes markdown +
.metasidecar + updatesindex.jsonhash index - Returns JSON with first N lines (default 200)
CLI interface
read_as_markdown.py FILE [options]
positional arguments:
FILE Path to document file (.pdf, .docx, .epub)
options:
--workspace-root PATH Override workspace root (auto-detected via .claude/)
--limit N Max lines to return (default: 200)
--offset N Line offset for chunked reading (default: 0)
--backend NAME Force a specific backend (pandoc, pdftotext)
Output format
{
"cache_path": "/home/agent/paivi/.cache/markdown/downloads/paper.md",
"total_lines": 847,
"content": "first 200 lines...",
"source": "/home/agent/paivi/downloads/paper.pdf",
"format": "pdf",
"backend": "pdftotext",
"cached": false
}
On error: {"error": "description"}.
Caching
Cache lives at <workspace>/.cache/markdown/ mirroring the source file tree.
Each cached file has a .meta JSON sidecar:
{
"mtime": 1709312456.789,
"size": 2048576,
"content_hash": "sha256:a1b2c3...",
"toolchain": [
{"step": "convert", "backend": "pdftotext", "version": "24.04.0", "at": "2026-03-01T12:00:00+00:00"}
],
"converted_at": "2026-03-01T12:00:00+00:00"
}
A hash index at <workspace>/.cache/markdown/index.json maps content hashes to
cache paths, enabling cache hits when source files are moved or renamed.
The toolchain array records every processing step — the initial conversion and
any later post-processing (formatting, cleanup, refinement by helper scripts).
Each step records its name, tool, version, and timestamp.
Backends
| Format | Default backend | Fallback |
|---|---|---|
| pdftotext | pandoc | |
| DOCX | pandoc | — |
| EPUB | pandoc | — |
pdftotext uses -layout mode for best table/column preservation in academic
papers. On NixOS, automatically falls back to nix-shell -p poppler-utils if
pdftotext is not in PATH.
pandoc uses --to=markdown --wrap=none for clean, unwrapped output.
Adding a new backend
Add a converter function and register it in BACKENDS:
def marker_converter(source: Path) -> tuple[str, str]:
# ... convert ...
return markdown_text, "marker 1.0"
BACKENDS["pdf"].insert(0, ("marker", marker_converter))
Distinction from pdf/docx skills
- read-as-markdown: Reads documents → produces Markdown for the agent to consume
- pdf skill: Creates, merges, splits, watermarks, OCR, fills forms in PDFs
- docx skill: Creates, edits, tracks changes in Word documents
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
akaihola/skills-akaihola
youtube-to-markdown
Convert a YouTube video into clean, readable Markdown using its free auto-generated captions (no paid API needed). Use when the user asks to "convert YouTube video to markdown", "get transcript from YouTube URL", "summarise this video", or wants to turn YouTube subtitles/captions into readable text. Prefer this over youtube-transcription when the video already has auto-generated subtitles — it's free and faster. Accepts YouTube URLs.
akaihola/skills-akaihola
brave-search
Search the web using Brave Search API. Use when the user asks to "search the web", "look up current information", "find news about", "research a topic online", "check prices online", or needs up-to-date facts that may not be in the model's training data. Requires BRAVE_SEARCH_API_KEY. Supports structured web results (pages, FAQs, news, videos) and an optional AI summarizer.
akaihola/skills-akaihola
verkkokauppa
Search products on the Verkkokauppa.com Finnish webshop. This skill uses the Verkkokauppa search API directly, requiring no browser. Use when the user asks to "search Verkkokauppa", "find products on verkkokauppa.com", "verkkokauppa product search", "check Verkkokauppa prices", or mentions searching the Verkkokauppa store.
akaihola/skills-akaihola
clasohlson
Search products on the Clas Ohlson Finland webshop (clasohlson.com/fi/). This skill uses the Voyado Elevate (Apptus eSales) search API directly, requiring no browser. Use when the user asks to "search Clas Ohlson", "find products on clasohlson.com", "clas ohlson product search", "check Clas Ohlson prices", or mentions searching the Finnish Clas Ohlson store.
akaihola/skills-akaihola
bauhaus
Search products on the Bauhaus webshop (bauhaus.fi). This skill uses the Algolia search API with automatic key refresh. Use when the user asks to "search Bauhaus", "find products on bauhaus.fi", "bauhaus product search", "check Bauhaus prices", or mentions searching the Bauhaus store.
akaihola/skills-akaihola
library
Didn't find tool you were looking for?