book-library-analyzer
niki8885/book-library-analyzer
Claude Code skills for organizing book and paper libraries
Instalação
npx convez-ai niki8885/book-library-analyzer1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Book Library Analyzer & Organizer
Three skills for managing a personal library of ebooks and audiobooks.
| Skill | When to use |
|---|---|
/book-library-analyzer | Explore what's in a folder, get ratings and recommendations |
/book-library-organizer | Set up a new organized library — naming format, folder structure, catalog |
/book-library-import | Add new books to an existing library using its saved rules |
/scientific-paper-organizer | Organize scientific papers — DOI extraction, CrossRef/S2 enrichment, separate catalog |
Skill 1 — Book Library Analyzer
Turn a messy folder into a clean, enriched catalog and get personalized reading recommendations.
What it does
- Check — if a catalog already exists, offer to reuse, update (add new files only), or rescan from scratch
- Scan — walk the folder tree, extract embedded metadata (EPUB, FB2, PDF, MP3, FLAC, OGG/Opus, M4B)
- Identify — reconcile filenames with metadata; detect duplicates (same book in multiple formats) and series membership
- Enrich — fetch year, genre, tags, 2–3 sentence description, and Goodreads rating per book (falls back to OpenLibrary/LibraryThing)
- Catalog — save
library-catalog.md; books grouped by series and standalone; supports custom output path - Recommend — ask one question about mood and suggest 2–3 books from the collection
Usage
/book-library-analyzer
/book-library-analyzer D:\Books
/book-library-analyzer /home/user/audiobooks
/book-library-analyzer D:\Books --output D:\library-catalog.md
Output (library-catalog.md)
# Library Catalog — Books
Generated 2025-06-10 · 24 books (18 ebooks, 6 audiobooks)
## Summary
| # | Author | Title | Year | Series | Genre | Goodreads | Format |
|---|--------|-------|------|--------|-------|-----------|--------|
| 1 | Orwell | 1984 | 1949 | | Dystopia | 4.19 (4.1M) | fb2+epub |
| 2 | Herbert | Dune | 1965 | Dune #1 | Sci-Fi | 4.25 (1.2M) | epub |
Skill 2 — Book Library Organizer
Rename files, reorganize into folders, and export a structured catalog in your chosen format. Saves all settings to a rules file — re-running the skill next time skips all setup questions.
What it does
- Load rules — if
library-rules.jsonexists, offer to reuse / edit / ignore saved settings - Incremental scan — uses
.library-index.jsonto skip books that haven't changed - Naming format — 5 presets or custom pattern with tokens (
{author},{title},{year},{series},{num},{lang},{genre}…) - Folder sorting — flat, by author, genre, year, genre→author, or author→series
- Scientific libraries — choose discipline depth: L1 (
Biology), L2 (Biology/Genetics), L3 (Biology/Genetics/Epigenetics) - Catalog fields — pick which 14 available fields to export
- Catalog formats — Markdown, CSV, XLSX (stdlib, no pip), SQLite DB (with indexes), or all at once
- Preview — see all planned renames before anything changes; conflict and missing-data warnings
- Execute — rename files, write catalogs, save
rename-log.tsv(undo log) - Save rules + index —
library-rules.jsonstores all settings;.library-index.jsonindexes all books for fast incremental reruns - Undo — reverse all renames from the undo log
Usage
/book-library-organizer
/book-library-organizer D:\Books
/book-library-organizer D:\Books, E:\Audiobooks
/book-library-organizer D:\Books --output D:\catalog
/book-library-organizer D:\Books --dry-run
/book-library-organizer --undo D:\Books\rename-log.tsv
Naming format presets
| # | Format | Example |
|---|---|---|
| 1 (default) | {author} - {title} ({year}) | George Orwell - 1984 (1949) |
| 2 | {author} - {title} | George Orwell - 1984 |
| 3 | {last}, {first} - {title} ({year}) | Orwell, George - 1984 (1949) |
| 4 | {title} - {author} ({year}) | 1984 - George Orwell (1949) |
| 5 | {series} {num:02d}. {title} ({author}, {year}) | Dune 01. Dune (Herbert, 1965) |
| 6 | Custom pattern |
Catalog fields
| Field | Description |
|---|---|
new_path | File path after rename ✓ |
old_path | Original path before rename |
title | Book title ✓ |
author | Author name ✓ |
year | Year of first publication ✓ |
publisher | Publisher name |
language | Language code (en / ru / de…) ✓ |
series | Series name ✓ |
series_num | Part number within series ✓ |
genre | Primary genre ✓ |
tags | Thematic tags |
format | File extension ✓ |
size_mb | File size in MB |
goodreads | Goodreads rating (requires Skill 1 catalog) |
description | Short description (requires Skill 1 catalog) |
✓ = included by default
Catalog output formats
| Format | File | Notes |
|---|---|---|
| Markdown | library-catalog.md | Human-readable, git-friendly |
| CSV | library-catalog.csv | Excel / Notion / Airtable import |
| XLSX | library-catalog.xlsx | Bold header, auto-filter ready; stdlib only, no pip |
| SQLite | library-catalog.db | Indexed on author, title, genre, year, series, language |
Persistent files written after each run
| File | Purpose |
|---|---|
library-rules.json | Saves all settings — next run reuses them without re-asking |
.library-index.json | Indexes all books for fast incremental updates |
rename-log.tsv | Undo log — reverse all renames with --undo |
Skill 3 — Book Library Import
Add new books from an unsorted folder into an existing organized library using its saved rules.
No setup needed — reads library-rules.json and .library-index.json from the library.
What it does
- Validate — confirms
library-rules.jsonexists in the catalog folder; if not, asks to run/book-library-organizerfirst - Load context — reads naming format, folder structure, catalog formats, and existing book index
- Scan — runs
scan_library.pyon the unsorted folder; reconciles metadata - Detect duplicates — cross-checks against
.library-index.json(same format / different format) - Enrich — web search for missing tokens required by the naming format (batched)
- Preview — shows all planned moves with duplicate and conflict warnings
- Move — moves files into the organized library structure (with undo log)
- Update — rebuilds all catalog formats (Markdown / CSV / XLSX / SQLite) from the merged index
- Clean up — offers to delete the now-empty unsorted folder
Usage
/book-library-import D:\Books D:\Downloads\new-books
/book-library-import ← asks for both paths
Duplicate handling options
| Option | Behaviour |
|---|---|
| Skip (default) | Leave duplicates in the unsorted folder |
Move to _duplicates/ | Move into <library>/_duplicates/ for manual review |
| Add with suffix | Import as Title (2).epub alongside existing copy |
| Overwrite | Replace existing file (confirms separately) |
Persistent files updated
| File | Change |
|---|---|
.library-index.json | New entries added, total and last_scan updated |
library-catalog.md/csv/xlsx/db | Full rebuild from merged index |
rename-log.tsv | New import section appended (reversible with --undo) |
library-rules.json | Only updated timestamp changed |
Skill 4 — Scientific Paper Organizer
Scan PDFs for DOIs and arXiv IDs, enrich full metadata from CrossRef and Semantic Scholar, rename and sort into folders, export a paper-specific catalog. Completely separate rules and index from the book skills — papers and books coexist without conflict.
What it does
- Mode selection — papers-only folder, or mixed (identifies papers vs. books, offers to hand books off to
/book-library-organizer) - Scan —
paper_scanner.pyextracts DOI, arXiv ID, PDF metadata, and classifies each file as paper/book/unknown - Enrich —
paper_enricher.pycalls CrossRef + Semantic Scholar (free APIs, no key, stdlib urllib) for title, all authors, journal, abstract (500 chars), citation count, open-access status - Naming format — 5 presets or custom, paper-specific tokens:
{first_author},{authors_et_al},{journal},{doi_short},{arxiv_id},{title_short}… - Folder sorting — flat, by year, journal, first author, keyword/topic (auto-assigned from abstract), or discipline depth L1/L2/L3
- Catalog fields — 20+ paper-specific fields including DOI, abstract, citations, open-access URL, ISSN
- Catalog formats — Markdown, CSV, XLSX, SQLite (indexed on doi, first_author, year, journal, type)
- Preview + execute — with undo log (same format as book organizer, compatible with
--undo) - Save rules + index —
paper-rules.jsonand.paper-index.json(separate from book rules)
Usage
/scientific-paper-organizer
/scientific-paper-organizer D:\Papers
/scientific-paper-organizer D:\Research --output D:\paper-catalog
/scientific-paper-organizer D:\MixedLibrary ← detects papers and books, offers split workflow
Paper-specific naming tokens
| Token | Example |
|---|---|
{first_author} | Smith |
{authors_et_al} | Smith et al. |
{year} | 2023 |
{title_short} | Attention Is All You Need |
{journal} | Nature |
{journal_abbr} | Nat. |
{doi_short} | 10.1038.s41586 |
{arxiv_id} | 1706.03762 |
{type} | preprint |
Bundled scripts
| Script | Purpose |
|---|---|
paper_scanner.py | Walk folder, extract DOI/arXiv from PDF bytes, classify paper vs. book |
paper_enricher.py | Batch DOI lookup via CrossRef + Semantic Scholar (stdlib urllib, no pip) |
catalog_writer.py | Write XLSX and SQLite output |
Mixed library workflow
# 1. Organize papers (skips book-like PDFs)
/scientific-paper-organizer D:\Research
# 2. Organize books in the same folder
/book-library-organizer D:\Research
Both skills write to separate rule and catalog files — they don't interfere with each other.
Supported formats
| Type | Extensions |
|---|---|
| Ebooks | .epub, .fb2, .fb2.zip, .pdf, .mobi, .azw, .azw3, .djvu |
| Audiobooks | .mp3, .m4b, .m4a, .flac, .ogg, .oga, .opus, .aac, .wma |
Metadata extraction: EPUB, FB2, PDF, MP3 ID3v2, M4B/M4A, FLAC Vorbis, OGG/Opus Vorbis.
MOBI, AZW, AZW3, DJVU, AAC, WMA fall back to filename parsing.
Requirements
- Python (stdlib only — no pip installs) for the bundled scanner and catalog writer scripts
- Falls back to manual directory listing if Python is unavailable
Bundled scripts
| Script | Used by | Purpose |
|---|---|---|
skills/book-library-analyzer/scripts/scan_library.py | Analyzer, Organizer, Import | Walk folder tree, extract book metadata |
skills/book-library-organizer/scripts/catalog_writer.py | Organizer, Import | Write XLSX and SQLite catalog files |
skills/scientific-paper-organizer/scripts/paper_scanner.py | Paper Organizer | Walk folder, extract DOI/arXiv from PDF bytes, classify paper vs. book |
skills/scientific-paper-organizer/scripts/paper_enricher.py | Paper Organizer | Batch CrossRef + Semantic Scholar lookup (stdlib urllib) |
skills/scientific-paper-organizer/scripts/catalog_writer.py | Paper Organizer | Write XLSX and SQLite paper catalog |
License
MIT License — Copyright (c) 2025 Nikita Manaenkov