convez.ai
Skill
niki8885

book-library-analyzer

niki8885/book-library-analyzer

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code skills for organizing book and paper libraries

Instalação

$npx convez-ai niki8885/book-library-analyzer

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.

SkillWhen to use
/book-library-analyzerExplore what's in a folder, get ratings and recommendations
/book-library-organizerSet up a new organized library — naming format, folder structure, catalog
/book-library-importAdd new books to an existing library using its saved rules
/scientific-paper-organizerOrganize 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

  1. Check — if a catalog already exists, offer to reuse, update (add new files only), or rescan from scratch
  2. Scan — walk the folder tree, extract embedded metadata (EPUB, FB2, PDF, MP3, FLAC, OGG/Opus, M4B)
  3. Identify — reconcile filenames with metadata; detect duplicates (same book in multiple formats) and series membership
  4. Enrich — fetch year, genre, tags, 2–3 sentence description, and Goodreads rating per book (falls back to OpenLibrary/LibraryThing)
  5. Catalog — save library-catalog.md; books grouped by series and standalone; supports custom output path
  6. 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

  1. Load rules — if library-rules.json exists, offer to reuse / edit / ignore saved settings
  2. Incremental scan — uses .library-index.json to skip books that haven't changed
  3. Naming format — 5 presets or custom pattern with tokens ({author}, {title}, {year}, {series}, {num}, {lang}, {genre}…)
  4. Folder sorting — flat, by author, genre, year, genre→author, or author→series
  5. Scientific libraries — choose discipline depth: L1 (Biology), L2 (Biology/Genetics), L3 (Biology/Genetics/Epigenetics)
  6. Catalog fields — pick which 14 available fields to export
  7. Catalog formats — Markdown, CSV, XLSX (stdlib, no pip), SQLite DB (with indexes), or all at once
  8. Preview — see all planned renames before anything changes; conflict and missing-data warnings
  9. Execute — rename files, write catalogs, save rename-log.tsv (undo log)
  10. Save rules + index — library-rules.json stores all settings; .library-index.json indexes all books for fast incremental reruns
  11. 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

#FormatExample
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)
6Custom pattern

Catalog fields

FieldDescription
new_pathFile path after rename ✓
old_pathOriginal path before rename
titleBook title ✓
authorAuthor name ✓
yearYear of first publication ✓
publisherPublisher name
languageLanguage code (en / ru / de…) ✓
seriesSeries name ✓
series_numPart number within series ✓
genrePrimary genre ✓
tagsThematic tags
formatFile extension ✓
size_mbFile size in MB
goodreadsGoodreads rating (requires Skill 1 catalog)
descriptionShort description (requires Skill 1 catalog)

✓ = included by default

Catalog output formats

FormatFileNotes
Markdownlibrary-catalog.mdHuman-readable, git-friendly
CSVlibrary-catalog.csvExcel / Notion / Airtable import
XLSXlibrary-catalog.xlsxBold header, auto-filter ready; stdlib only, no pip
SQLitelibrary-catalog.dbIndexed on author, title, genre, year, series, language

Persistent files written after each run

FilePurpose
library-rules.jsonSaves all settings — next run reuses them without re-asking
.library-index.jsonIndexes all books for fast incremental updates
rename-log.tsvUndo 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

  1. Validate — confirms library-rules.json exists in the catalog folder; if not, asks to run /book-library-organizer first
  2. Load context — reads naming format, folder structure, catalog formats, and existing book index
  3. Scan — runs scan_library.py on the unsorted folder; reconciles metadata
  4. Detect duplicates — cross-checks against .library-index.json (same format / different format)
  5. Enrich — web search for missing tokens required by the naming format (batched)
  6. Preview — shows all planned moves with duplicate and conflict warnings
  7. Move — moves files into the organized library structure (with undo log)
  8. Update — rebuilds all catalog formats (Markdown / CSV / XLSX / SQLite) from the merged index
  9. 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

OptionBehaviour
Skip (default)Leave duplicates in the unsorted folder
Move to _duplicates/Move into <library>/_duplicates/ for manual review
Add with suffixImport as Title (2).epub alongside existing copy
OverwriteReplace existing file (confirms separately)

Persistent files updated

FileChange
.library-index.jsonNew entries added, total and last_scan updated
library-catalog.md/csv/xlsx/dbFull rebuild from merged index
rename-log.tsvNew import section appended (reversible with --undo)
library-rules.jsonOnly 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

  1. Mode selection — papers-only folder, or mixed (identifies papers vs. books, offers to hand books off to /book-library-organizer)
  2. Scan — paper_scanner.py extracts DOI, arXiv ID, PDF metadata, and classifies each file as paper/book/unknown
  3. Enrich — paper_enricher.py calls CrossRef + Semantic Scholar (free APIs, no key, stdlib urllib) for title, all authors, journal, abstract (500 chars), citation count, open-access status
  4. Naming format — 5 presets or custom, paper-specific tokens: {first_author}, {authors_et_al}, {journal}, {doi_short}, {arxiv_id}, {title_short}…
  5. Folder sorting — flat, by year, journal, first author, keyword/topic (auto-assigned from abstract), or discipline depth L1/L2/L3
  6. Catalog fields — 20+ paper-specific fields including DOI, abstract, citations, open-access URL, ISSN
  7. Catalog formats — Markdown, CSV, XLSX, SQLite (indexed on doi, first_author, year, journal, type)
  8. Preview + execute — with undo log (same format as book organizer, compatible with --undo)
  9. Save rules + index — paper-rules.json and .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

TokenExample
{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

ScriptPurpose
paper_scanner.pyWalk folder, extract DOI/arXiv from PDF bytes, classify paper vs. book
paper_enricher.pyBatch DOI lookup via CrossRef + Semantic Scholar (stdlib urllib, no pip)
catalog_writer.pyWrite 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

TypeExtensions
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

ScriptUsed byPurpose
skills/book-library-analyzer/scripts/scan_library.pyAnalyzer, Organizer, ImportWalk folder tree, extract book metadata
skills/book-library-organizer/scripts/catalog_writer.pyOrganizer, ImportWrite XLSX and SQLite catalog files
skills/scientific-paper-organizer/scripts/paper_scanner.pyPaper OrganizerWalk folder, extract DOI/arXiv from PDF bytes, classify paper vs. book
skills/scientific-paper-organizer/scripts/paper_enricher.pyPaper OrganizerBatch CrossRef + Semantic Scholar lookup (stdlib urllib)
skills/scientific-paper-organizer/scripts/catalog_writer.pyPaper OrganizerWrite XLSX and SQLite paper catalog

License

MIT License — Copyright (c) 2025 Nikita Manaenkov

Ver o original no GitHub

Bom para

Relacionados