MicrosoftKnown publishermicrosoft/DocAtlas-Harness/docatlas/skills/read/SKILL.md

read

Skill21 starsChanged 9 days agoMITView on GitHub

Read pages from a document. Returns MinerU markdown (preferred) or PyPDF text, with optional page screenshots and sub-image fetching. When markdown is available, a figure_images_meta catalog is included — use the figures parameter to fetch specific sub-image pixels. Triggers include "read page 5", "what does page 12 say", "show me the chart on page 3", "extract pages 3-5".

We split this skill into the rules it gives an agent

14 rules. 0 are common, 8 are distinctive, and 6 are very specific to this project.

0
Common
Most of the 11 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Read fetches text, page screenshots, and sub-image pixels for specific pages of a PDF.
line 13
Distinctive:
After Search identifies candidate pages — pass them directly to Read.
line 20
Distinctive:
When you need the actual text of specific pages.
line 21
Very specific:
When you need a page rendered as an image (with_image) for figures, charts, tables, or scanned content.
line 22
Very specific:
When figure_images_meta from a previous Read call lists a sub-image you want to inspect — call Read again with figures to fetch it.
line 24
Distinctive:
Don't read more than 5 pages per call.
line 30
Distinctive:
Read returns text in one of two modes:
line 36
Very specific:
If text_is_empty: true, the PDF is scanned/image-only.
line 44
Very specific:
Use zoom (default 1.0, allowed 0.25-4.0) to control screenshot resolution — higher values produce larger images and consume more tokens.
line 54
Very specific:
When Read returns markdown mode, each page may include a figure_images_meta catalog listing sub-images (charts, figures, diagrams) …
line 59
Very specific:
If a figure is too small and was filtered out, use force_figures: true to bypass the minimum-size filter.
line 66
Distinctive:
Search first: Don't guess page numbers — let Search find them.
line 91
Distinctive:
Prefer markdown mode: When available, markdown gives you structured tables and headings that are easier to parse than raw text.
line 94
Distinctive:
Use sub-images selectively: Don't fetch every figure — only those relevant to the question.
line 96

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Read — the single content-retrieval tool

Read fetches text, page screenshots, and sub-image pixels for specific pages of a PDF. It is the only tool for bringing document content into the conversation — text extraction, page screenshots, and figure sub-images are all handled here.

When to use

After Search identifies candidate pages — pass them directly to Read.
When you need the actual text of specific pages.
When you need a page rendered as an image (with_image) for figures, charts, tables, or scanned content.
When figure_images_meta from a previous Read call lists a sub-image you want to inspect — call Read again with figures to fetch it.

When NOT to use

You don't know which pages are relevant yet — call Search first.
Don't read more than 5 pages per call. If Search returned more, read the top 5 first; read remaining candidates in follow-up calls.
The document is a non-PDF format — Read only supports PDFs.

Text retrieval

Read returns text in one of two modes:

markdown (preferred): When MinerU per-page markdown is available, you get structured headings, tables, and inline figure references. The response also includes a figure_images_meta catalog listing available sub-images with their dimensions and byte sizes.
text (fallback): Raw PyPDF extraction when markdown is unavailable.

If text_is_empty: true, the PDF is scanned/image-only. Re-run with with_image: true for vision-based reading.

Page screenshots (`with_image`)

Set with_image: true when:

The page contains charts, diagrams, or complex tables where layout matters.
Text extraction returned empty or garbled content.
You need visual context to interpret the page.

Use zoom (default 1.0, allowed 0.25-4.0) to control screenshot resolution — higher values produce larger images and consume more tokens.

Sub-image workflow

When Read returns markdown mode, each page may include a figure_images_meta catalog listing sub-images (charts, figures, diagrams) extracted by MinerU. To fetch a specific sub-image:

Read pages: Read(pages="3") — inspect the figure_images_meta catalog.
Fetch figures: Read(pages="3", figures=[{"page": 3, "ref": "image_1"}]) — the response includes base64 pixels for the requested sub-image.
If a figure is too small and was filtered out, use force_figures: true to bypass the minimum-size filter. Path, file-type, and byte limits still apply.

Addressing is by (page, ref) where ref matches image_N from the catalog. Invalid refs return an error with available_refs for self-correction.

Parameters

Parameter	Type	Default	Description
`pages`	string	(required)	Page numbers, e.g. `"1,3-5,8"`. ≤5 pages recommended.
`with_image`	boolean	false	Attach full-page screenshots (PNG).
`figures`	array	[]	Sub-images to fetch: `[{"page": N, "ref": "image_N"}]`.
`force_figures`	boolean	false	Bypass minimum-size filter for figures.
`zoom`	number	1.0	Zoom factor for page screenshots.
`doc_id`	string	null	Document identifier override.

Visual Question Routing (selective): When the question EXPLICITLY asks about visual content (e.g. "what does the chart show", "in figure X", "in the diagram", "according to the plot/graph"), prefer with_image=true on Read calls. For text/numeric questions where 'table' or 'chart' merely describes the source location, with_image=true is optional.

Best practices

≤5 pages per call. Narrower reads keep context focused. Read the most relevant pages first; if the answer isn't found, read remaining candidates.
Search first. Don't guess page numbers — let Search find them.
Note after reading. Once you find an answer or key information, write it down with Note so later turns don't need to re-read.
Prefer markdown mode. When available, markdown gives you structured tables and headings that are easier to parse than raw text.
Use sub-images selectively. Don't fetch every figure — only those relevant to the question. Check the catalog metadata first.

Recommended workflow

search("quarterly revenue 2018")
  → pages [12, 47, 48]

read(pages="12,47-48")
  → text + figure_images_meta with image_1 on page 47

read(pages="47", figures=[{"page": 47, "ref": "image_1"}])
  → sub-image pixels for the revenue chart

note(found="Revenue was $32.8B in 2018.", evidence=[{"type":"text","source":"Page 47","content":"Revenue was $32.8B in 2018."}])

Failure modes

error: PDF not found — bad path; check working directory.
missing_pages non-empty — out-of-range pages; the rest still succeeded.
text_is_empty: true — scanned PDF. Re-run with with_image: true.
figure_errors[].reason == "ref_not_found" — bad figure ref; check available_refs.

Download now (ZIP)

Other versions16 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 16
tw93/Waza★ 7.4ksame name
tw93/claude-health★ 7.3ksame name
ninehills/skills★ 280same name
yha9806/academic-writing-toolkit★ 46same name
owenliang60-ship-it/knowledge-mgmt★ 37same name
mhxie/Atelier★ 4same name
Wanghaoyihaoyi/agent-skills★ 2same name
flintfromthebasement/skills★ 1same name
kaelen2026/skills★ 1same name
khanhmoiii/claude-tutor-skills★ 1same name
6 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use hunt, think and 4 more.
Other files people use alongside this one.
- ninehillsSkill
  hunt
  Finds root cause before applying fixes for errors, crashes, regressions, failing tests, broken behavior, and screenshot-reported defects. Use when users report in any language errors, crashes, broken behavior, regressions, failing tests, screenshot evidence, or something that used to work and now fails. Not for code review or new features.
  Also in 4 projects that use this
- vltingSkill
  think
  Lightweight plan-to-execution pipeline. Explores codebase, runs council deliberation, presents plan for approval, then executes via /run.
  Also in 5 projects that use this
- DockerSkill
  write
  Write or edit reader-facing technical prose for immediate comprehension. Use for documentation, PR titles and descriptions, release notes, design documents, user-facing explanations, and substantive comments. Also use when asked to make writing clearer, more natural, less AI-generated, or easier to read. For documentation fixes, handles edits, formatting, self-review, and commits after research identifies what to change. Do not use for code-only tasks with no prose deliverable.
  Also in 6 projects that use this
- genomewalkerSkill
  health
  Soul system health check with remediation
  Also in 5 projects that use this
- kt057Skill
  check
  lint, typecheck, test を一括実行して結果をサマリーする
  Also in 6 projects that use this
- genomewalkerSkill
  learn
  Learn from web sources, generate SKILL.md, and store key patterns in soul memory. Trigger keywords: learn, skill-gen, web-learn, documentation, tutorial.
  Also in 6 projects that use this
In this repository4 other files it gives its agents.
- web/AGENTS.mdAGENTS.md
- noteSkill
- reviewSkill
- searchSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free

14 rules. 0 are common, 8 are distinctive, and 6 are very specific to this project.

Read — the single content-retrieval tool

When to use

When NOT to use

Text retrieval

Page screenshots (with_image)

Sub-image workflow

Parameters

Best practices

Recommended workflow

Failure modes

Word for word · 0

Edited · 0

Wrote their own version · 16

hunt

think

write

health

check

learn

Does it work?

No reviews yet

Your trail

Now do this for your own.

Page screenshots (`with_image`)