hathach Read Doc
Overview
Some maintainers keep datasheets, manuals, and books in a Calibre library at
$HOME/Documents/calibre-library/. For hardware/protocol facts — registers,
bitfields, memory maps, pinouts, electrical/timing specs, errata, USB spec —
read the doc instead of answering from training knowledge or the web.
Search the library's metadata.db, never the filesystem. The database indexes
title, authors, tags, series, publisher, description and the stored filename;
most part numbers live in the tags, which the filesystem does not carry.
Gate first
The library is per-user and usually on a network mount, so test the database file, not the directory — an unmounted or half-synced mountpoint is still a directory:
[ -f "${CALIBRE_LIBRARY:-$HOME/Documents/calibre-library}/metadata.db" ] && echo present || echo absent
Absent → the skill does not apply; fall back to normal sources silently (don't mention the library unless the user named it).
When to use
- About to state a register/bitfield/reset-value/memory-map/pinout/timing spec for a specific MCU or peripheral.
- User says "read the RP2040 datasheet", "open the CH569 manual", "what does the STM32H7 RM say about…".
Not for general concepts, repo/code questions, or when no such doc is likely.
Find
Keywords supplied as skill arguments, else derived from the question (part
number, peripheral, spec name). search.py ANDs them across every metadata
field and prints the best matches first — at most 40, and the header says when
more matched:
python3 .claude/skills/read-doc/search.py errata RT1064 # AND (default)
python3 .claude/skills/read-doc/search.py RT1060 RT1064 --any
Exit 0 matched, 1 nothing matched, 2 bad usage or no library — 2 means the search never ran, so fix the invocation instead of broadening.
One match → read it. Several → list them and ask the user which to read. Nothing
(exit 1) → retry with fewer keywords; the part number alone often works where
<part> datasheet does not, because words like "datasheet" and "manual" are
rarely in the metadata. --any only changes anything with two or more
keywords. Still nothing → say the document is missing rather than answering
from memory.
Set CALIBRE_LIBRARY to search a library elsewhere.
Read
search.py prints one FORMAT path line per stored file:
- PDF — use the runtime's PDF-reading capability with page ranges; for >10 pages start with pages 1-20 (TOC/overview), report the page count, then read sections on demand.
- Any other format (EPUB, MOBI, CHM, ZIP…) — if the runtime has no decoder, say the document is not in a readable format; do not paste mojibake.
MISSING— the metadata is real but the file is not on disk (library mid-sync, or the file was deleted). Report the file as unavailable, not the document as nonexistent.
Summarize in one line (title, pages, coverage) and keep as reference context.
Common mistakes
- Searching with
find/grepover the library tree. It sees only truncated filenames, missing the tags, series and descriptions where part numbers and errata IDs actually live. Query the database. - Skipping the gate on a machine with no library.
- Answering a register/spec question from memory when the datasheet is on disk.
- Loading a 1000-page PDF up front instead of TOC-first.
- Requiring all keywords to match — broaden, or use
--any, on zero hits. - Treating a
MISSINGfile, or an exit 2, as proof the document is absent.