| name | holo-zlib |
| description | Search and download published ebooks from Z-Library. Use this skill whenever the user wants to find or obtain a specific book or ebook (in formats like epub, pdf, mobi, or djvu) — whether they ask directly (find, grab, fetch, download) or indirectly (get me a copy of a title, I need this textbook as a file, do you have this book?). Trigger even when the user names no source, and when they mention Z-Library / zlibrary / zlib or name a different book library. Not for academic papers/preprints (e.g. arXiv), non-book media (movies, music, software), or operating on a file the user already has (converting, extracting text, summarizing) — though an ebook that happens to be a PDF still counts. |
Z-Library Book Search & Download
Search and download ebooks through Z-Library's eAPI, filtering by format and result
count. Standard library only (Python >= 3.10) — no third-party packages. The machine
must be able to reach https://z-library.sk (network connectivity is your
responsibility).
Paths below are relative to this skill's directory — run the commands from here. Examples
use python; on Linux/macOS where only python3 exists, substitute it. On Windows,
python from a venv or the Microsoft Store works; the py launcher is not always
installed, so don't rely on py -3.
Prerequisites
Credentials file credentials/zlib.json
{"remix_userid": "YOUR_USERID", "remix_userkey": "YOUR_USERKEY"}
Take remix_userid / remix_userkey from your browser cookies after logging in to
Z-Library.
The script uses the nearest credentials/zlib.json found while walking up from the skill
directory. When installed under <project>/.claude/skills/holo-zlib/, put it at the
project root (<project>/credentials/zlib.json) — the .claude sibling counts as an
ancestor. Set an explicit path with HOLO_ZLIB_CREDENTIALS_FILE=/abs/path/to/zlib.json.
Workflow
Two steps: (1) run search to get a result's book_id and hash; (2) pass those two
values to download. The identifiers come only from search output — don't guess them.
Usage
Search for books
python scripts/zlib.py search "title"
python scripts/zlib.py search "title" --ext epub
python scripts/zlib.py search "title" --ext epub --limit 5
--ext is passed straight to the API (not validated), so any format Z-Library supports
works — commonly epub, pdf, mobi, djvu, fb2, txt, rtf, azw3, doc, docx.
Choosing a result
Each result prints two numbers: Quality (qualityScore) and Popularity
(interestScore). In practice these are often null/0 or tied at the top — every popular
edition tends to show the same value — so they rarely separate the best match. Results are
listed in the API's relevance order, so for a generic "best" / "most popular" request,
prefer the top result whose title actually matches what the user asked for, then break
ties by completeness (a full edition over a sample/companion volume), file size, year, and
language. Tell the user which one you picked and why.
Download a book
Take the book_id and hash from the chosen result line and pass them to download
(book_id first, then hash):
python scripts/zlib.py download <book_id> <hash>
python scripts/zlib.py download <book_id> <hash> --output /some/other/dir
End-to-end example (values are illustrative — use real ones from your own search):
python scripts/zlib.py search "the pragmatic programmer" --ext epub --limit 3
python scripts/zlib.py download 123456 abc123def
By default files are saved to the nearest existing ebooks/ directory found while walking
up from the skill directory (e.g. <project>/ebooks/, or <repo>/ebooks/ in a dev
checkout). Override globally with HOLO_ZLIB_EBOOKS_DIR=..., or per call with
--output ....
Free accounts are limited to roughly 10 downloads per day. There is no API to check
remaining quota, so when asked for several books at once, download the highest-priority
titles first (or confirm scope) rather than firing a large batch that may exhaust midway.
Troubleshooting
- "Credentials file not found": create
credentials/zlib.json as described in
Prerequisites and fill in both fields.
- "Network request failed" / "Request timed out (30s)" / "Download timed out (120s)":
a connectivity problem — confirm your network (and proxy, e.g. mihomo) can reach
https://z-library.sk, then retry. Large files can legitimately need the full window.
- "Failed to get download link": the
book_id/hash is likely stale or invalid
(hashes can change between searches) — re-run the search to get fresh identifiers and
retry. This is not a quota problem, so don't wait for the next day.
- "Download not allowed": a link came back but downloading is blocked — almost always
the daily quota is exhausted (resets about once a day). Less commonly the specific title
is restricted for your account; if quota clearly isn't the issue, try a different
edition/result.
- Endpoint / auth / field details: see
references/eapi.md.
Notes
- Credentials stay valid until you log out in the browser.
- This is deliberately a small, two-command surface (search + download). Supply the
orchestration — which result to pick, when to download — yourself; there is no
interactive picker or download-by-rank flag.
