[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78ASMNTB40PY7WPXKP6X72K":3,"skill-same:01M78ASMNTB40PY7WPXKP6X72K":161},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":15,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":41,"ownerHtmlUrl":42,"ownerBlogUrl":6,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M78ASMNTB40PY7WPXKP6X72K","library-rag",null,"Semantic search over a personal library using Nemotron-3-Embed-1B embeddings + sqlite-vec. Index books, documents, any text corpus; query by meaning. Includes EPUB→Markdown conversion and MCP server for auto-available search tools.","moonlight-lupin\u002Fagent-skills","moonlight-lupin","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F136997773?v=4","01M78AEDSH1N62R0RNWPWMWVQY","01M78AEDT8ZF85MTK6XYBQBTNT",123,"MIT","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: library-rag\ndescription: \"Semantic search over a personal library using Nemotron-3-Embed-1B embeddings + sqlite-vec. Index books, documents, any text corpus; query by meaning. Includes EPUB→Markdown conversion and MCP server for auto-available search tools.\"\nlicense: MIT\nmetadata:\n  version: 1.0.0\n  author: moonlight-lupin\n  platforms: [linux, macos, windows]\n  tags: [rag, embeddings, semantic-search, library, mcp]\n---\n\n# Library RAG\n\nSemantic search over `~\u002F.hermes\u002Flibrary\u002F` using Nemotron-3-Embed-1B embeddings (via NVIDIA NIM) stored in sqlite-vec. Enables meaning-based retrieval across any text corpus — books, documents, reference works — in any language.\n\n## Architecture\n\n```\nNVIDIA NIM API (nemotron-3-embed-1b, 2048-dim)\n        │\n        ▼\n~\u002F.hermes\u002Flibrary\u002Frag_index.db (sqlite-vec)\n  ├── chunks table      — text + metadata (source, book, chapter, section)\n  ├── vec_chunks table  — L2-normalized vector embeddings\n  └── indexed_files     — SHA-256 hash tracking for incremental updates\n\nMCP Server (mcp_server.py)\n  ├── search(query, top_k, source_type)  — semantic search, auto-available\n  ├── stats()                             — index statistics\n  └── add_book(file_path, ...)            — EPUB\u002FPDF → md → index in one call\n```\n\n## Onboarding workflow (run this the first time a user sets up the skill)\n\nWhen a user wants to start using Library RAG, walk them through this sequence.\nUse `AskUserQuestion` for the decisions marked **ASK** — don't assume paths or\nsilently create directories outside the home folder.\n\n### Step 1 — Check prerequisites\n\n```bash\npython3 --version                                   # need 3.9+\npython3 -c \"import sqlite_vec; print('sqlite-vec ok')\" 2>&1\ntest -n \"$NVIDIA_API_KEY\" && echo \"key in env\" || grep -qs NVIDIA_API_KEY ~\u002F.hermes\u002F.env && echo \"key in .env\" || echo \"NO API KEY\"\n```\n\n- If `sqlite-vec` import fails → run `pip install -r requirements.txt` (add\n  `--break-system-packages` on externally-managed Python). See README \"Installation\".\n- If `NO API KEY` → help the user create a free NVIDIA NIM key at\n  \u003Chttps:\u002F\u002Fbuild.nvidia.com\u002Fnvidia\u002Fnemotron-3-embed-1b>, then\n  store it: `echo 'NVIDIA_API_KEY=nvapi-...' >> ~\u002F.hermes\u002F.env`.\n  (Legacy OpenRouter keys still work: if only `OPENROUTER_API_KEY` is set,\n  `load_api_key()` auto-switches to the bge-m3 OpenRouter endpoint.)\n\n### Step 2 — Define directories (**ASK**)\n\nThree locations drive everything. Confirm them with the user and export the env vars\n(persist in their shell profile). Defaults in parentheses:\n\n| Purpose | Env var | Default | Notes |\n|---|---|---|---|\n| **Indexed content + vector DB** | `LIBRARY_ROOT` | `~\u002F.hermes\u002Flibrary` | Holds the structured `.md`\u002F`.txt` that get embedded, plus `rag_index.db`. |\n| **Vector DB file** | (derived) | `$LIBRARY_ROOT\u002Frag_index.db` | Override per-run with `rag_index.py --db \u003Cpath>` if you want it elsewhere. |\n| **Raw books + conversion staging** | `BOOKS_DIR` | `~\u002F.hermes\u002Fbook` | Where original EPUBs\u002FPDFs land and where text is extracted. |\n\nRecommended layout (keep raw\u002Ftext **out of** `LIBRARY_ROOT` — see pitfall below):\n\n```\n$BOOKS_DIR\u002F                        staging — NOT indexed\n  raw\u002F        original EPUBs\u002FPDFs\n  text\u002F       extracted plain text\n$LIBRARY_ROOT\u002F                     indexed — scanned recursively\n  rag_index.db\n  \u003Csource_type>\u002F                   top-level dir name becomes the \"source type\"\n    markdown\u002F\u003Cslug>\u002Fchapters\u002F*.md  the structured files that get embedded\n```\n\n> **Pitfall — avoid double-indexing:** `discover_files()` indexes *every* `.md` **and**\n> `.txt` under `LIBRARY_ROOT`. If both the extracted `.txt` and the converted `.md` of the\n> same book live under `LIBRARY_ROOT`, the content is embedded twice. Keep only **one**\n> representation (prefer the structured `.md`) under `LIBRARY_ROOT`; keep raw + text staging\n> in `BOOKS_DIR` outside it.\n\nCreate the chosen dirs:\n```bash\nmkdir -p \"$LIBRARY_ROOT\" \"$BOOKS_DIR\u002Fraw\" \"$BOOKS_DIR\u002Ftext\"\n```\n\n### Step 3 — Add the first content & build the index\n\n- **EPUB\u002FPDF via MCP (if the server is configured):** call `add_book(...)` — it converts and\n  indexes in one step.\n- **Manual:** drop source files in `$BOOKS_DIR\u002Fraw`, convert to structured markdown under\n  `$LIBRARY_ROOT\u002F\u003Csource_type>\u002F` (see `convert_epub_library.py` and\n  `references\u002Fepub-conversion.md`), then:\n\n```bash\npython3 scripts\u002Frag_index.py --dry-run     # preview chunk counts, no API cost\npython3 scripts\u002Frag_index.py               # incremental build\npython3 scripts\u002Frag_query.py --stats       # confirm chunks landed\npython3 scripts\u002Frag_query.py \"a test query\"\n```\n\n### Step 4 — Automated scanning\u002Fconversion\u002Findexing (**ASK**)\n\nAsk the user whether they want new files indexed **automatically** or **manually**:\n\n- **Manual (default, recommended to start):** they run `python3 scripts\u002Frag_index.py`\n  after adding files. Incremental + SHA-256 tracking means re-runs are cheap and only touch\n  new\u002Fchanged files. No setup needed.\n- **Automated (cron):** schedule a periodic incremental index. Only offer this once Step 3\n  works end-to-end. Example — index nightly at 02:00 and log output:\n\n  ```bash\n  # crontab -e   (adjust the repo path and env vars)\n  0 2 * * * NVIDIA_API_KEY=nvapi-... LIBRARY_ROOT=$HOME\u002F.hermes\u002Flibrary \\\n    \u002Fusr\u002Fbin\u002Fpython3 $HOME\u002Flibrary-rag\u002Fscripts\u002Frag_index.py >> $HOME\u002F.hermes\u002Frag_index.log 2>&1\n  ```\n\n  If they also want EPUBs auto-converted before indexing, chain a conversion step ahead of\n  `rag_index.py` in the same cron line (or a small wrapper script). On macOS, `launchd` \u002F\n  a `launchd` plist is the more reliable equivalent of cron.\n\n  **Cron cautions to mention:**\n  - Cron has a minimal environment — set `NVIDIA_API_KEY`, `LIBRARY_ROOT`, and use an\n    **absolute** `python3` path (or activate the venv inside a wrapper script).\n  - Never overlap two `--rebuild` runs on the same DB (see Pitfalls). A nightly incremental\n    run is safe; a full `--rebuild` should stay manual.\n  - NIM embeddings are free on the NVIDIA free trial tier; the log still shows token usage.\n\nAfter onboarding, summarize for the user: the three paths chosen, where the DB lives, and\nwhether indexing is manual or scheduled.\n\n## MCP Tools (auto-available in every conversation)\n\nOnce configured in `config.yaml`, these tools are available as\n`mcp_library_rag_search`, `mcp_library_rag_stats`, `mcp_library_rag_add_book`.\n\n### Config\n\n```yaml\n# ~\u002F.hermes\u002Fconfig.yaml\nmcp_servers:\n  library_rag:\n    command: \"python3\"\n    args: [\"~\u002F.hermes\u002Fskills\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Fmcp_server.py\"]\n    timeout: 60\n```\n\nRestart the gateway after adding.\n\n### search\n\n```\nmcp_library_rag_search(query=\"your search query\", top_k=10)\nmcp_library_rag_search(query=\"search terms\", source_type=\"my-source-type\")\n```\n\nReturns JSON array of results with `similarity`, `source_type`, `book`, `chapter`,\n`section_title`, `text`.\n\n### stats\n\n```\nmcp_library_rag_stats()\n→ {\"total_chunks\": 78000, \"files_indexed\": 1383, \"by_source\": {...}}\n```\n\n### add_book\n\n```\nmcp_library_rag_add_book(\n    file_path=\"\u002Fpath\u002Fto\u002Fbook.epub\",   # or \u002Fpath\u002Fto\u002Fdoc.pdf\n    book_slug=\"my-new-book\",\n    author=\"Author Name\",\n    title=\"Book Title\",\n    year=\"2024\"\n)\n```\n\nConverts EPUB → chapters or PDF → pages, then indexes them. One-call workflow for adding\nnew books to the library.\n\n## Scripts (for batch operations)\n\n### rag_index.py — Indexer\n\n```bash\n# Index all new\u002Fchanged files (incremental — SHA-256 hash tracking)\npython3 scripts\u002Frag_index.py\n\n# Full rebuild (drop everything, re-index from scratch)\npython3 scripts\u002Frag_index.py --rebuild\n\n# Dry run (show what would be indexed, no API calls)\npython3 scripts\u002Frag_index.py --dry-run\n\n# Index only one source type\npython3 scripts\u002Frag_index.py --source my-source-type\n\n# Prune DB rows for files deleted\u002Fmoved out of the library, then shrink the file\npython3 scripts\u002Frag_index.py --prune-missing --vacuum\n```\n\n**When to use:**\n- After adding new files to the library → run incremental (default)\n- After changing chunking strategy → run `--rebuild`\n- To estimate cost\u002Ftime → run `--dry-run` first\n- After deleting\u002Fmoving files out of the library → run `--prune-missing`\n  (removes orphaned chunks + vectors so the DB doesn't keep dead rows; safe\n  alongside incremental indexing — only files absent from disk are retired)\n- After a `--rebuild` or a large `--prune-missing` → run `--vacuum` to shrink\n  the DB file (SQLite reuses freed pages but doesn't shrink the file otherwise)\n\n### rag_query.py — CLI Query\n\n```bash\npython3 scripts\u002Frag_query.py \"your search query\"\npython3 scripts\u002Frag_query.py \"search terms\" --top-k 5\npython3 scripts\u002Frag_query.py \"query\" --source my-source-type --verbose\npython3 scripts\u002Frag_query.py --stats\n```\n\nCan also be imported:\n```python\nfrom rag_query import search\nresults = search(\"query text\", top_k=10)\n```\n\n## Conversion Tools\n\n### EPUB → Markdown (`scripts\u002Fconvert_epub_library.py`)\n\nExtracts text from EPUB files and splits into per-chapter Markdown with YAML frontmatter.\nRunnable as a CLI or importable as `convert_epub()` — the same implementation backs the MCP\n`add_book` tool, so there is one conversion code path.\n\n```bash\npython3 scripts\u002Fconvert_epub_library.py \\\n    --epub book.epub --slug my-book --title \"Book Title\" --author \"Author\" --year 2024 \\\n    --md-root ~\u002F.hermes\u002Flibrary\u002Fbooks\u002Fmarkdown   # under LIBRARY_ROOT so it gets indexed\n```\n\nRaw EPUB + extracted text stage under `$BOOKS_DIR` (outside `LIBRARY_ROOT`); only the\nstructured markdown is written to `--md-root`, so the raw text is never double-indexed.\n\nChapter detection tries several styles (`CHAPTER 12` \u002F `CHAPTER One` \u002F `PART IV` \u002F\n`12. Title` \u002F bare `12\\nTitle`), picking the first that confidently applies, and guards\nagainst date\u002Fpage-number false positives. Before trusting a conversion, eyeball\n`convert_epub_library.audit_chapter_markers(text)` — every entry should be a real chapter,\nnot a date or page number.\n\nKey pitfalls (see `references\u002Fepub-conversion.md` for full details):\n1. **Multiple TOC ghosts**: Large EPUBs produce multiple table-of-contents blocks. Skip all when finding chapter headings in body text.\n2. **CHAPTER N vs N. Title**: EPUBs use different heading patterns in TOC vs body. Match the BODY pattern.\n3. **Title + subtitle leak into YAML**: Use only the main title for the `title:` field.\n4. **Slug truncation**: Truncate slugs to 60 chars (preserving the `chNN-` prefix).\n5. **Page-number blocks**: Some EPUBs extract huge blocks of standalone page numbers. Detect and exclude.\n6. **Post-processing pass**: Always verify every `.md` file has valid YAML frontmatter.\n\n### PDF → Markdown (`scripts\u002Fconvert_pdf_library.py`)\n\nExtracts text **and tables** with `pdfplumber`. Each page → a `## Page N` section (so the\nmarkdown chunker yields per-page citations); tables → `**[Table N]**` blocks. CLI or\n`convert_pdf()`; it also backs `add_book` for `.pdf` inputs.\n\n```bash\npython3 scripts\u002Fconvert_pdf_library.py \\\n    --pdf doc.pdf --slug my-doc --title \"Doc\" --author \"Author\" --year 2024 \\\n    --md-root ~\u002F.hermes\u002Flibrary\u002Fbooks\u002Fmarkdown\n```\n\nThe table block is display-only: `clean_for_embedding` strips `**[Table N]**` and rows ending\nin `\u003Cbr>` from the embedding input (the page's narrative text already carries the table content\nlinearly), so tables stay searchable without being embedded twice.\n\n### Built-in chunkers (`rag_index.py`)\n\n| Chunker | Input | Strategy |\n|---|---|---|\n| `chunk_markdown()` | `.md` with headings | Split by `##`\u002F`###` (a `###` chunk carries its parent `##` as a `Section — Subsection` breadcrumb), paragraph merge fallback, single-newline normalization |\n| `chunk_plain_text()` | `.txt` files | Paragraph merge with 15% overlap |\n\nFor domain-specific formats (PDFs, XML, JSON), write a custom chunker and register it in\n`discover_files()`. See `references\u002Fchunking-strategies.md` for patterns.\n\n## Adding new books to the library\n\n### Quick path (EPUB\u002FPDF via MCP)\n\nUse `mcp_library_rag_add_book` — it dispatches on extension and handles\nEPUB\u002FPDF → md → index in one call.\n\n### Manual path\n\n1. **Convert to structured Markdown** with the converter CLI for the format. Both stage\n   the raw file + extracted text under `$BOOKS_DIR` (outside `LIBRARY_ROOT`, so they're not\n   indexed) and write markdown to `--md-root`:\n\n   ```bash\n   # EPUB → per-chapter markdown\n   python3 scripts\u002Fconvert_epub_library.py \\\n       --epub book.epub --slug \u003Cslug> --title \"...\" --author \"...\" --year 2024 \\\n       --md-root $LIBRARY_ROOT\u002Fbooks\u002Fmarkdown\n\n   # PDF → per-page markdown (tables preserved)\n   python3 scripts\u002Fconvert_pdf_library.py \\\n       --pdf doc.pdf --slug \u003Cslug> --title \"...\" --author \"...\" --year 2024 \\\n       --md-root $LIBRARY_ROOT\u002Fbooks\u002Fmarkdown\n   ```\n\n   For other sources (XML\u002FJSON, etc.), follow the extraction pattern in\n   `references\u002Fchunking-strategies.md` and write the markdown under\n   `$LIBRARY_ROOT\u002F\u003Csource_type>\u002F` yourself.\n\n2. **Register the chunker** (if new file type):\n   - Add a chunker function in `rag_index.py`\n   - Register it in `discover_files()`\n   See `references\u002Fchunking-strategies.md` for patterns and pitfalls.\n   See `references\u002Fportable-rag-per-skill.md` for the standalone per-skill RAG pattern.\n   See `references\u002Frag-pipeline-review.md` for a systematic audit checklist.\n\n3. **Index:**\n   ```bash\n   python3 scripts\u002Frag_index.py  # incremental — only new files\n   ```\n\n## Cost\n\nDefault provider is NVIDIA NIM (`nvidia\u002Fnemotron-3-embed-1b`) — free on the\nNVIDIA API free trial tier. No per-token embedding cost for personal use.\n\nLegacy OpenRouter path (`baai\u002Fbge-m3`, ~$0.01\u002FM tokens) remains available as a\nfallback; see `references\u002Fopenrouter-embeddings.md`.\n\nEffectively free for personal use.\n\n## Portable Standalone RAG Instances\n\nThe same Nemotron-3-Embed-1B → sqlite-vec pattern can be deployed as a **standalone,\nself-contained RAG** inside any skill directory — no MCP registration, no\ndependency on `~\u002F.hermes\u002Flibrary\u002F`. This makes the skill portable: zip the\nfolder, drop on another machine, it works.\n\n### How to build a standalone instance\n\n1. **Copy** `rag_index.py` and `rag_query.py` into the skill's `scripts\u002F` dir\n2. **Parameterize the DB path** — replace the hardcoded `LIBRARY_ROOT` \u002F\n   `DB_PATH` with an env var or CLI flag, defaulting to the skill's own\n   `references\u002F` directory\n3. **Write a domain-specific chunker** — chunk by the document's natural\n   structure (headings, sections). For PDF-extracted content, parse\n   `\u003C!-- Page N -->` markers via `split_by_pages()` for per-chunk page citations.\n4. **Do NOT register an MCP server** — scripts import `rag_query.py` directly:\n   ```python\n   from rag_query import search\n   results = search(\"query text\", top_k=5)\n   ```\n5. **L2-normalize vectors at store + query time** — add `normalize_vec()` to\n   `float_to_blob()` (indexer) and `get_embedding()` (query). Makes cosine\n   similarity exact, not an implicit assumption.\n6. **Add ~15% chunk overlap** — `split_long_text()` should carry the tail\n   of each chunk into the next for better recall.\n7. **Clean embedding input** — `clean_for_embedding()` must strip `\u003Cbr>`,\n   `**[Table N]**`, and `\u003C!-- Page N -->` in addition to markdown markers.\n8. **Wire in `MIN_CHUNK_CHARS`** — call `merge_tiny_chunks()` after chunking\n   to prevent near-empty chunks from diluting search results.\n9. **Shared dependency:** the NVIDIA API key (Nemotron-3-Embed-1B via NIM).\n   The embedding model and sqlite-vec extension are shared, not duplicated.\n\nSee `references\u002Fportable-rag-per-skill.md` for full code patterns and\n`references\u002Frag-pipeline-review.md` for a systematic audit checklist.\n\n### When to use standalone vs. the main library\n\n| Use the main library when... | Use standalone when... |\n|---|---|\n| Content is reference\u002Fbooks you want globally searchable | Content is domain-specific (rulebooks, code docs, etc.) |\n| You want auto-available MCP search tools | You want the skill to be portable\u002Fself-contained |\n| Content should be globally searchable | Content should only surface when that skill is loaded |\n\n## Pitfalls\n\n- **sqlite-vec must be loaded before DROP\u002FCREATE of vec0 tables**: The extension must be loaded first in `init_db()`.\n- **`file_hash` must be added to chunks before storing**: The indexer adds it after chunking but before embedding. Don't forget this when adding new chunkers.\n- **Single-newline wrapping**: Some text sources use single `\\n` for line wrapping, not paragraph breaks. Normalize to spaces before splitting on `\\n\\n`.\n- **MCP server timeout**: The default 60s timeout is fine for `search` and `stats`. `add_book` may need more time for large EPUBs — increase `timeout` in config if needed.\n- **sqlite-vec source filtering**: sqlite-vec's `MATCH`\u002F`k` vector search cannot be combined with arbitrary `WHERE` clauses. `source_type` and `source_book` filters must be applied as post-filters after over-fetching results (fetch `top_k * 5`, then filter on chunk metadata). See `references\u002Fportable-rag-per-skill.md` for the correct pattern.\n- **Portable RAG instances**: To create a standalone RAG for a different skill, copy `rag_index.py` and `rag_query.py` and parameterize: (1) resolve paths from `__file__` not hardcoded `LIBRARY_ROOT`, (2) store DB inside the skill's `references\u002F` dir, (3) skip the MCP server — import `search()` directly instead, (4) write a domain-specific chunker, (5) parse `\u003C!-- Page N -->` markers for per-chunk page citations, (6) L2-normalize vectors at store+query time, (7) add ~15% chunk overlap for better recall. See `references\u002Fportable-rag-per-skill.md` for the full pattern.\n- **Page citations require marker parsing**: PDF extractors insert `\u003C!-- Page N -->` comments, but chunkers must actively parse them — otherwise all chunks degrade to chapter-level citations. Use `split_by_pages()` in the chunker to split by markers and stamp each chunk with its page.\n- **L2 normalization required for exact similarity**: `1 - dist²\u002F2` is only exact cosine if both stored and query vectors are unit-normalized. Nemotron-3-Embed-1B (and the legacy bge-m3 path) may return near-unit vectors, but `normalize_vec()` is called at store time (`float_to_blob`) and query time (`get_embedding`) to guarantee this explicitly.\n- **`clean_for_embedding` must strip table\u002FPDF artifacts**: In addition to markdown markers, strip `\u003Cbr>`, `**[Table N]**`, and `\u003C!-- Page N -->` from embedding input. These are noise from PDF table extraction. Chunk text in the DB retains them for display readability.\n- **Never run two `--rebuild` processes on the same DB simultaneously**: SQLite allows concurrent connections but `--rebuild` drops and recreates tables. If a foreground test and a background job overlap, the background process gets spurious \"Failed after 3 retries\" errors. Always let any foreground `--rebuild` test fully exit before starting the background job, or use `--dry-run` for quick tests (it doesn't touch the DB).\n- **Full library re-index takes ~50-90 min**: Small files finish fast, large text collections dominate. NIM embeddings are free; legacy OpenRouter path was ~$0.01-$0.12 depending on corpus size. Batch size 32 with a short delay between batches remains a safe default.\n","# Library RAG\n\nSemantic search over `~\u002F.hermes\u002Flibrary\u002F` using Nemotron-3-Embed-1B embeddings (via NVIDIA NIM) stored in sqlite-vec. Enables meaning-based retrieval across any text corpus — books, documents, reference works — in any language.\n\n## Architecture\n\n```\nNVIDIA NIM API (nemotron-3-embed-1b, 2048-dim)\n        │\n        ▼\n~\u002F.hermes\u002Flibrary\u002Frag_index.db (sqlite-vec)\n  ├── chunks table      — text + metadata (source, book, chapter, section)\n  ├── vec_chunks table  — L2-normalized vector embeddings\n  └── indexed_files     — SHA-256 hash tracking for incremental updates\n\nMCP Server (mcp_server.py)\n  ├── search(query, top_k, source_type)  — semantic search, auto-available\n  ├── stats()                             — index statistics\n  └── add_book(file_path, ...)            — EPUB\u002FPDF → md → index in one call\n```\n\n## Onboarding workflow (run this the first time a user sets up the skill)\n\nWhen a user wants to start using Library RAG, walk them through this sequence.\nUse `AskUserQuestion` for the decisions marked **ASK** — don't assume paths or\nsilently create directories outside the home folder.\n\n### Step 1 — Check prerequisites\n\n```bash\npython3 --version                                   # need 3.9+\npython3 -c \"import sqlite_vec; print('sqlite-vec ok')\" 2>&1\ntest -n \"$NVIDIA_API_KEY\" && echo \"key in env\" || grep -qs NVIDIA_API_KEY ~\u002F.hermes\u002F.env && echo \"key in .env\" || echo \"NO API KEY\"\n```\n\n- If `sqlite-vec` import fails → run `pip install -r requirements.txt` (add\n  `--break-system-packages` on externally-managed Python). See README \"Installation\".\n- If `NO API KEY` → help the user create a free NVIDIA NIM key at\n  \u003Chttps:\u002F\u002Fbuild.nvidia.com\u002Fnvidia\u002Fnemotron-3-embed-1b>, then\n  store it: `echo 'NVIDIA_API_KEY=nvapi-...' >> ~\u002F.hermes\u002F.env`.\n  (Legacy OpenRouter keys still work: if only `OPENROUTER_API_KEY` is set,\n  `load_api_key()` auto-switches to the bge-m3 OpenRouter endpoint.)\n\n### Step 2 — Define directories (**ASK**)\n\nThree locations drive everything. Confirm them with the user and export the env vars\n(persist in their shell profile). Defaults in parentheses:\n\n| Purpose | Env var | Default | Notes |\n|---|---|---|---|\n| **Indexed content + vector DB** | `LIBRARY_ROOT` | `~\u002F.hermes\u002Flibrary` | Holds the structured `.md`\u002F`.txt` that get embedded, plus `rag_index.db`. |\n| **Vector DB file** | (derived) | `$LIBRARY_ROOT\u002Frag_index.db` | Override per-run with `rag_index.py --db \u003Cpath>` if you want it elsewhere. |\n| **Raw books + conversion staging** | `BOOKS_DIR` | `~\u002F.hermes\u002Fbook` | Where original EPUBs\u002FPDFs land and where text is extracted. |\n\nRecommended layout (keep raw\u002Ftext **out of** `LIBRARY_ROOT` — see pitfall below):\n\n```\n$BOOKS_DIR\u002F                        staging — NOT indexed\n  raw\u002F        original EPUBs\u002FPDFs\n  text\u002F       extracted plain text\n$LIBRARY_ROOT\u002F                     indexed — scanned recursively\n  rag_index.db\n  \u003Csource_type>\u002F                   top-level dir name becomes the \"source type\"\n    markdown\u002F\u003Cslug>\u002Fchapters\u002F*.md  the structured files that get embedded\n```\n\n> **Pitfall — avoid double-indexing:** `discover_files()` indexes *every* `.md` **and**\n> `.txt` under `LIBRARY_ROOT`. If both the extracted `.txt` and the converted `.md` of the\n> same book live under `LIBRARY_ROOT`, the content is embedded twice. Keep only **one**\n> representation (prefer the structured `.md`) under `LIBRARY_ROOT`; keep raw + text staging\n> in `BOOKS_DIR` outside it.\n\nCreate the chosen dirs:\n```bash\nmkdir -p \"$LIBRARY_ROOT\" \"$BOOKS_DIR\u002Fraw\" \"$BOOKS_DIR\u002Ftext\"\n```\n\n### Step 3 — Add the first content & build the index\n\n- **EPUB\u002FPDF via MCP (if the server is configured):** call `add_book(...)` — it converts and\n  indexes in one step.\n- **Manual:** drop source files in `$BOOKS_DIR\u002Fraw`, convert to structured markdown under\n  `$LIBRARY_ROOT\u002F\u003Csource_type>\u002F` (see `convert_epub_library.py` and\n  `references\u002Fepub-conversion.md`), then:\n\n```bash\npython3 scripts\u002Frag_index.py --dry-run     # preview chunk counts, no API cost\npython3 scripts\u002Frag_index.py               # incremental build\npython3 scripts\u002Frag_query.py --stats       # confirm chunks landed\npython3 scripts\u002Frag_query.py \"a test query\"\n```\n\n### Step 4 — Automated scanning\u002Fconversion\u002Findexing (**ASK**)\n\nAsk the user whether they want new files indexed **automatically** or **manually**:\n\n- **Manual (default, recommended to start):** they run `python3 scripts\u002Frag_index.py`\n  after adding files. Incremental + SHA-256 tracking means re-runs are cheap and only touch\n  new\u002Fchanged files. No setup needed.\n- **Automated (cron):** schedule a periodic incremental index. Only offer this once Step 3\n  works end-to-end. Example — index nightly at 02:00 and log output:\n\n  ```bash\n  # crontab -e   (adjust the repo path and env vars)\n  0 2 * * * NVIDIA_API_KEY=nvapi-... LIBRARY_ROOT=$HOME\u002F.hermes\u002Flibrary \\\n    \u002Fusr\u002Fbin\u002Fpython3 $HOME\u002Flibrary-rag\u002Fscripts\u002Frag_index.py >> $HOME\u002F.hermes\u002Frag_index.log 2>&1\n  ```\n\n  If they also want EPUBs auto-converted before indexing, chain a conversion step ahead of\n  `rag_index.py` in the same cron line (or a small wrapper script). On macOS, `launchd` \u002F\n  a `launchd` plist is the more reliable equivalent of cron.\n\n  **Cron cautions to mention:**\n  - Cron has a minimal environment — set `NVIDIA_API_KEY`, `LIBRARY_ROOT`, and use an\n    **absolute** `python3` path (or activate the venv inside a wrapper script).\n  - Never overlap two `--rebuild` runs on the same DB (see Pitfalls). A nightly incremental\n    run is safe; a full `--rebuild` should stay manual.\n  - NIM embeddings are free on the NVIDIA free trial tier; the log still shows token usage.\n\nAfter onboarding, summarize for the user: the three paths chosen, where the DB lives, and\nwhether indexing is manual or scheduled.\n\n## MCP Tools (auto-available in every conversation)\n\nOnce configured in `config.yaml`, these tools are available as\n`mcp_library_rag_search`, `mcp_library_rag_stats`, `mcp_library_rag_add_book`.\n\n### Config\n\n```yaml\n# ~\u002F.hermes\u002Fconfig.yaml\nmcp_servers:\n  library_rag:\n    command: \"python3\"\n    args: [\"~\u002F.hermes\u002Fskills\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Fmcp_server.py\"]\n    timeout: 60\n```\n\nRestart the gateway after adding.\n\n### search\n\n```\nmcp_library_rag_search(query=\"your search query\", top_k=10)\nmcp_library_rag_search(query=\"search terms\", source_type=\"my-source-type\")\n```\n\nReturns JSON array of results with `similarity`, `source_type`, `book`, `chapter`,\n`section_title`, `text`.\n\n### stats\n\n```\nmcp_library_rag_stats()\n→ {\"total_chunks\": 78000, \"files_indexed\": 1383, \"by_source\": {...}}\n```\n\n### add_book\n\n```\nmcp_library_rag_add_book(\n    file_path=\"\u002Fpath\u002Fto\u002Fbook.epub\",   # or \u002Fpath\u002Fto\u002Fdoc.pdf\n    book_slug=\"my-new-book\",\n    author=\"Author Name\",\n    title=\"Book Title\",\n    year=\"2024\"\n)\n```\n\nConverts EPUB → chapters or PDF → pages, then indexes them. One-call workflow for adding\nnew books to the library.\n\n## Scripts (for batch operations)\n\n### rag_index.py — Indexer\n\n```bash\n# Index all new\u002Fchanged files (incremental — SHA-256 hash tracking)\npython3 scripts\u002Frag_index.py\n\n# Full rebuild (drop everything, re-index from scratch)\npython3 scripts\u002Frag_index.py --rebuild\n\n# Dry run (show what would be indexed, no API calls)\npython3 scripts\u002Frag_index.py --dry-run\n\n# Index only one source type\npython3 scripts\u002Frag_index.py --source my-source-type\n\n# Prune DB rows for files deleted\u002Fmoved out of the library, then shrink the file\npython3 scripts\u002Frag_index.py --prune-missing --vacuum\n```\n\n**When to use:**\n- After adding new files to the library → run incremental (default)\n- After changing chunking strategy → run `--rebuild`\n- To estimate cost\u002Ftime → run `--dry-run` first\n- After deleting\u002Fmoving files out of the library → run `--prune-missing`\n  (removes orphaned chunks + vectors so the DB doesn't keep dead rows; safe\n  alongside incremental indexing — only files absent from disk are retired)\n- After a `--rebuild` or a large `--prune-missing` → run `--vacuum` to shrink\n  the DB file (SQLite reuses freed pages but doesn't shrink the file otherwise)\n\n### rag_query.py — CLI Query\n\n```bash\npython3 scripts\u002Frag_query.py \"your search query\"\npython3 scripts\u002Frag_query.py \"search terms\" --top-k 5\npython3 scripts\u002Frag_query.py \"query\" --source my-source-type --verbose\npython3 scripts\u002Frag_query.py --stats\n```\n\nCan also be imported:\n```python\nfrom rag_query import search\nresults = search(\"query text\", top_k=10)\n```\n\n## Conversion Tools\n\n### EPUB → Markdown (`scripts\u002Fconvert_epub_library.py`)\n\nExtracts text from EPUB files and splits into per-chapter Markdown with YAML frontmatter.\nRunnable as a CLI or importable as `convert_epub()` — the same implementation backs the MCP\n`add_book` tool, so there is one conversion code path.\n\n```bash\npython3 scripts\u002Fconvert_epub_library.py \\\n    --epub book.epub --slug my-book --title \"Book Title\" --author \"Author\" --year 2024 \\\n    --md-root ~\u002F.hermes\u002Flibrary\u002Fbooks\u002Fmarkdown   # under LIBRARY_ROOT so it gets indexed\n```\n\nRaw EPUB + extracted text stage under `$BOOKS_DIR` (outside `LIBRARY_ROOT`); only the\nstructured markdown is written to `--md-root`, so the raw text is never double-indexed.\n\nChapter detection tries several styles (`CHAPTER 12` \u002F `CHAPTER One` \u002F `PART IV` \u002F\n`12. Title` \u002F bare `12\\nTitle`), picking the first that confidently applies, and guards\nagainst date\u002Fpage-number false positives. Before trusting a conversion, eyeball\n`convert_epub_library.audit_chapter_markers(text)` — every entry should be a real chapter,\nnot a date or page number.\n\nKey pitfalls (see `references\u002Fepub-conversion.md` for full details):\n1. **Multiple TOC ghosts**: Large EPUBs produce multiple table-of-contents blocks. Skip all when finding chapter headings in body text.\n2. **CHAPTER N vs N. Title**: EPUBs use different heading patterns in TOC vs body. Match the BODY pattern.\n3. **Title + subtitle leak into YAML**: Use only the main title for the `title:` field.\n4. **Slug truncation**: Truncate slugs to 60 chars (preserving the `chNN-` prefix).\n5. **Page-number blocks**: Some EPUBs extract huge blocks of standalone page numbers. Detect and exclude.\n6. **Post-processing pass**: Always verify every `.md` file has valid YAML frontmatter.\n\n### PDF → Markdown (`scripts\u002Fconvert_pdf_library.py`)\n\nExtracts text **and tables** with `pdfplumber`. Each page → a `## Page N` section (so the\nmarkdown chunker yields per-page citations); tables → `**[Table N]**` blocks. CLI or\n`convert_pdf()`; it also backs `add_book` for `.pdf` inputs.\n\n```bash\npython3 scripts\u002Fconvert_pdf_library.py \\\n    --pdf doc.pdf --slug my-doc --title \"Doc\" --author \"Author\" --year 2024 \\\n    --md-root ~\u002F.hermes\u002Flibrary\u002Fbooks\u002Fmarkdown\n```\n\nThe table block is display-only: `clean_for_embedding` strips `**[Table N]**` and rows ending\nin `\u003Cbr>` from the embedding input (the page's narrative text already carries the table content\nlinearly), so tables stay searchable without being embedded twice.\n\n### Built-in chunkers (`rag_index.py`)\n\n| Chunker | Input | Strategy |\n|---|---|---|\n| `chunk_markdown()` | `.md` with headings | Split by `##`\u002F`###` (a `###` chunk carries its parent `##` as a `Section — Subsection` breadcrumb), paragraph merge fallback, single-newline normalization |\n| `chunk_plain_text()` | `.txt` files | Paragraph merge with 15% overlap |\n\nFor domain-specific formats (PDFs, XML, JSON), write a custom chunker and register it in\n`discover_files()`. See `references\u002Fchunking-strategies.md` for patterns.\n\n## Adding new books to the library\n\n### Quick path (EPUB\u002FPDF via MCP)\n\nUse `mcp_library_rag_add_book` — it dispatches on extension and handles\nEPUB\u002FPDF → md → index in one call.\n\n### Manual path\n\n1. **Convert to structured Markdown** with the converter CLI for the format. Both stage\n   the raw file + extracted text under `$BOOKS_DIR` (outside `LIBRARY_ROOT`, so they're not\n   indexed) and write markdown to `--md-root`:\n\n   ```bash\n   # EPUB → per-chapter markdown\n   python3 scripts\u002Fconvert_epub_library.py \\\n       --epub book.epub --slug \u003Cslug> --title \"...\" --author \"...\" --year 2024 \\\n       --md-root $LIBRARY_ROOT\u002Fbooks\u002Fmarkdown\n\n   # PDF → per-page markdown (tables preserved)\n   python3 scripts\u002Fconvert_pdf_library.py \\\n       --pdf doc.pdf --slug \u003Cslug> --title \"...\" --author \"...\" --year 2024 \\\n       --md-root $LIBRARY_ROOT\u002Fbooks\u002Fmarkdown\n   ```\n\n   For other sources (XML\u002FJSON, etc.), follow the extraction pattern in\n   `references\u002Fchunking-strategies.md` and write the markdown under\n   `$LIBRARY_ROOT\u002F\u003Csource_type>\u002F` yourself.\n\n2. **Register the chunker** (if new file type):\n   - Add a chunker function in `rag_index.py`\n   - Register it in `discover_files()`\n   See `references\u002Fchunking-strategies.md` for patterns and pitfalls.\n   See `references\u002Fportable-rag-per-skill.md` for the standalone per-skill RAG pattern.\n   See `references\u002Frag-pipeline-review.md` for a systematic audit checklist.\n\n3. **Index:**\n   ```bash\n   python3 scripts\u002Frag_index.py  # incremental — only new files\n   ```\n\n## Cost\n\nDefault provider is NVIDIA NIM (`nvidia\u002Fnemotron-3-embed-1b`) — free on the\nNVIDIA API free trial tier. No per-token embedding cost for personal use.\n\nLegacy OpenRouter path (`baai\u002Fbge-m3`, ~$0.01\u002FM tokens) remains available as a\nfallback; see `references\u002Fopenrouter-embeddings.md`.\n\nEffectively free for personal use.\n\n## Portable Standalone RAG Instances\n\nThe same Nemotron-3-Embed-1B → sqlite-vec pattern can be deployed as a **standalone,\nself-contained RAG** inside any skill directory — no MCP registration, no\ndependency on `~\u002F.hermes\u002Flibrary\u002F`. This makes the skill portable: zip the\nfolder, drop on another machine, it works.\n\n### How to build a standalone instance\n\n1. **Copy** `rag_index.py` and `rag_query.py` into the skill's `scripts\u002F` dir\n2. **Parameterize the DB path** — replace the hardcoded `LIBRARY_ROOT` \u002F\n   `DB_PATH` with an env var or CLI flag, defaulting to the skill's own\n   `references\u002F` directory\n3. **Write a domain-specific chunker** — chunk by the document's natural\n   structure (headings, sections). For PDF-extracted content, parse\n   `\u003C!-- Page N -->` markers via `split_by_pages()` for per-chunk page citations.\n4. **Do NOT register an MCP server** — scripts import `rag_query.py` directly:\n   ```python\n   from rag_query import search\n   results = search(\"query text\", top_k=5)\n   ```\n5. **L2-normalize vectors at store + query time** — add `normalize_vec()` to\n   `float_to_blob()` (indexer) and `get_embedding()` (query). Makes cosine\n   similarity exact, not an implicit assumption.\n6. **Add ~15% chunk overlap** — `split_long_text()` should carry the tail\n   of each chunk into the next for better recall.\n7. **Clean embedding input** — `clean_for_embedding()` must strip `\u003Cbr>`,\n   `**[Table N]**`, and `\u003C!-- Page N -->` in addition to markdown markers.\n8. **Wire in `MIN_CHUNK_CHARS`** — call `merge_tiny_chunks()` after chunking\n   to prevent near-empty chunks from diluting search results.\n9. **Shared dependency:** the NVIDIA API key (Nemotron-3-Embed-1B via NIM).\n   The embedding model and sqlite-vec extension are shared, not duplicated.\n\nSee `references\u002Fportable-rag-per-skill.md` for full code patterns and\n`references\u002Frag-pipeline-review.md` for a systematic audit checklist.\n\n### When to use standalone vs. the main library\n\n| Use the main library when... | Use standalone when... |\n|---|---|\n| Content is reference\u002Fbooks you want globally searchable | Content is domain-specific (rulebooks, code docs, etc.) |\n| You want auto-available MCP search tools | You want the skill to be portable\u002Fself-contained |\n| Content should be globally searchable | Content should only surface when that skill is loaded |\n\n## Pitfalls\n\n- **sqlite-vec must be loaded before DROP\u002FCREATE of vec0 tables**: The extension must be loaded first in `init_db()`.\n- **`file_hash` must be added to chunks before storing**: The indexer adds it after chunking but before embedding. Don't forget this when adding new chunkers.\n- **Single-newline wrapping**: Some text sources use single `\\n` for line wrapping, not paragraph breaks. Normalize to spaces before splitting on `\\n\\n`.\n- **MCP server timeout**: The default 60s timeout is fine for `search` and `stats`. `add_book` may need more time for large EPUBs — increase `timeout` in config if needed.\n- **sqlite-vec source filtering**: sqlite-vec's `MATCH`\u002F`k` vector search cannot be combined with arbitrary `WHERE` clauses. `source_type` and `source_book` filters must be applied as post-filters after over-fetching results (fetch `top_k * 5`, then filter on chunk metadata). See `references\u002Fportable-rag-per-skill.md` for the correct pattern.\n- **Portable RAG instances**: To create a standalone RAG for a different skill, copy `rag_index.py` and `rag_query.py` and parameterize: (1) resolve paths from `__file__` not hardcoded `LIBRARY_ROOT`, (2) store DB inside the skill's `references\u002F` dir, (3) skip the MCP server — import `search()` directly instead, (4) write a domain-specific chunker, (5) parse `\u003C!-- Page N -->` markers for per-chunk page citations, (6) L2-normalize vectors at store+query time, (7) add ~15% chunk overlap for better recall. See `references\u002Fportable-rag-per-skill.md` for the full pattern.\n- **Page citations require marker parsing**: PDF extractors insert `\u003C!-- Page N -->` comments, but chunkers must actively parse them — otherwise all chunks degrade to chapter-level citations. Use `split_by_pages()` in the chunker to split by markers and stamp each chunk with its page.\n- **L2 normalization required for exact similarity**: `1 - dist²\u002F2` is only exact cosine if both stored and query vectors are unit-normalized. Nemotron-3-Embed-1B (and the legacy bge-m3 path) may return near-unit vectors, but `normalize_vec()` is called at store time (`float_to_blob`) and query time (`get_embedding`) to guarantee this explicitly.\n- **`clean_for_embedding` must strip table\u002FPDF artifacts**: In addition to markdown markers, strip `\u003Cbr>`, `**[Table N]**`, and `\u003C!-- Page N -->` from embedding input. These are noise from PDF table extraction. Chunk text in the DB retains them for display readability.\n- **Never run two `--rebuild` processes on the same DB simultaneously**: SQLite allows concurrent connections but `--rebuild` drops and recreates tables. If a foreground test and a background job overlap, the background process gets spurious \"Failed after 3 retries\" errors. Always let any foreground `--rebuild` test fully exit before starting the background job, or use `--dry-run` for quick tests (it doesn't touch the DB).\n- **Full library re-index takes ~50-90 min**: Small files finish fast, large text collections dominate. NIM embeddings are free; legacy OpenRouter path was ~$0.01-$0.12 depending on corpus size. Batch size 32 with a short delay between batches remains a safe default.\n",{"name":5,"license":14,"metadata":24,"description":7},{"tags":25,"author":9,"version":31,"platforms":32},[26,27,28,29,30],"rag","embeddings","semantic-search","library","mcp","1.0.0",[33,34,35],"linux","macos","windows","main","e943e3285cd03c44b2c762a9a52328e3d16444b1","research\u002Flibrary-rag",22,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills","https:\u002F\u002Fhermes-agent.nousresearch.com","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin","Accounting\u002FFP&A\u002FM&A\u002FPERE guy by day, AI\u002Fself-host\u002Fprogramming hobbyist by night. \r\n\r\nPassionate in solving practical business issues.","2026-11-13 19:46:18",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add moonlight-lupin\u002Fagent-skills --skill library-rag",{"tool":51,"command":52},"bunx","bunx skills add moonlight-lupin\u002Fagent-skills --skill library-rag",{"tool":54,"command":55},"pnpm","pnpm dlx skills add moonlight-lupin\u002Fagent-skills --skill library-rag","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002FSKILL.md",true,[59,65,69,75,79,83,87,91,95,99,103,109,113,117,121,125,129,133,137,141,145,149,153,157],{"path":60,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":63,"sourceHtmlUrl":64},".gitignore","OTHER","其他",305,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002F.gitignore",{"path":66,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":15},"LICENSE","许可证",1375,{"path":70,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":73,"sourceHtmlUrl":74},"README.md","REFERENCE","参考文档",12111,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002FREADME.md",{"path":76,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fchunking-strategies.md",5933,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Freferences\u002Fchunking-strategies.md",{"path":80,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fepub-conversion.md",3884,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Freferences\u002Fepub-conversion.md",{"path":84,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Fopenrouter-embeddings.md",4158,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Freferences\u002Fopenrouter-embeddings.md",{"path":88,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Fportable-rag-per-skill.md",12357,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Freferences\u002Fportable-rag-per-skill.md",{"path":92,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":93,"sourceHtmlUrl":94},"references\u002Frag-pipeline-review.md",9951,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Freferences\u002Frag-pipeline-review.md",{"path":96,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":97,"sourceHtmlUrl":98},"requirements-dev.txt",167,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Frequirements-dev.txt",{"path":100,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":101,"sourceHtmlUrl":102},"requirements.txt",286,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Frequirements.txt",{"path":104,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":107,"sourceHtmlUrl":108},"scripts\u002Fconvert_epub_library.py","SCRIPT","脚本",13315,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Fconvert_epub_library.py",{"path":110,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":111,"sourceHtmlUrl":112},"scripts\u002Fconvert_pdf_library.py",6126,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Fconvert_pdf_library.py",{"path":114,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":115,"sourceHtmlUrl":116},"scripts\u002Fmcp_server.py",11172,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Fmcp_server.py",{"path":118,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":119,"sourceHtmlUrl":120},"scripts\u002Frag_common.py",8911,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Frag_common.py",{"path":122,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":123,"sourceHtmlUrl":124},"scripts\u002Frag_index.py",23985,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Frag_index.py",{"path":126,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":127,"sourceHtmlUrl":128},"scripts\u002Frag_query.py",7013,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Fscripts\u002Frag_query.py",{"path":130,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":131,"sourceHtmlUrl":132},"tests\u002Fconftest.py",188,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Fconftest.py",{"path":134,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":135,"sourceHtmlUrl":136},"tests\u002Ftest_chunking.py",5129,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_chunking.py",{"path":138,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":139,"sourceHtmlUrl":140},"tests\u002Ftest_convert_pdf.py",4154,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_convert_pdf.py",{"path":142,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":143,"sourceHtmlUrl":144},"tests\u002Ftest_convert.py",4760,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_convert.py",{"path":146,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":147,"sourceHtmlUrl":148},"tests\u002Ftest_index_search.py",4902,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_index_search.py",{"path":150,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":151,"sourceHtmlUrl":152},"tests\u002Ftest_indexing_atomicity.py",4888,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_indexing_atomicity.py",{"path":154,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":155,"sourceHtmlUrl":156},"tests\u002Ftest_prune_vacuum.py",5585,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_prune_vacuum.py",{"path":158,"resourceType":105,"resourceTypeDesc":106,"sizeBytes":159,"sourceHtmlUrl":160},"tests\u002Ftest_rag_common.py",5017,"https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Flibrary-rag\u002Ftests\u002Ftest_rag_common.py",[162,169,176,183,190,197],{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":168,"publishedAt":19},"01M78ATNRV7RYQ8M314V0QZX18","website-scraping","Generic playbook for extracting structured data from any website — hotel prices, flight fares, e-commerce listings, real estate, jobs, competitor product catalogues, anything where the goal is to turn one or more URLs into clean records on disk. Use this skill whenever the user mentions scraping, harvesting, extracting, or pulling data from a website; names a specific site or competitor they want data from; asks how to handle JavaScript-rendered pages, Cloudflare blocks, bot detection, Turnstile challenges, or Playwright; wants to monitor prices over time; needs to automate a copy-paste research task; or says things like \"just get the data from X\" or \"I need a script that grabs N from site Y\". Covers recon, picking the lightest extraction tool that works, surviving anti-bot defences, and writing clean JSONL output with a run manifest. Scope is scraping only — landing data in a database, scheduling, and downstream pipeline work are explicitly out of scope and live in other tools.","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fweb-scraping\u002Fwebsite-scraping\u002FSKILL.md",[],[],{"skillNo":170,"name":171,"nameZh":6,"description":172,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":173,"categories":174,"keywords":175,"publishedAt":19},"01M78ATK9XGEKSH3QRN7P2MEER","greet","Greets a named person warmly.","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fclaude_plugin_sample\u002Fskills\u002Fgreet\u002FSKILL.md",[],[],{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":182,"publishedAt":19},"01M78ATEAQB5CK2D4MKPCW4YHQ","skill-quality-review","Use when auditing or reviewing skill quality — batch checks across a library, deep per-skill grep methodology, usage stats, efficacy testing, or fix planning. Single consolidated home for the writing-for-agents review framework and the 3-surface review methodology.","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fsoftware-development\u002Fskill-quality-review\u002FSKILL.md",[],[],{"skillNo":184,"name":185,"nameZh":6,"description":186,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":189,"publishedAt":19},"01M78AT58EM57023QSC79S8R6D","people-enrichment","Use when the user has a list of names or companies and wants their job, employer, work history, LinkedIn URLs or company profiles looked up, or wants to find people or companies matching criteria — trigger on phrases like \"enrich these contacts\", \"find their LinkedIn\", \"look up these people\", \"who works at X\", \"find directors at Y\", \"enrich these companies\", or \"get firmographics for\". Enrich and search People Data Labs (PDL) Person and Company data, writing results to .xlsx. Five operations: enrich named PEOPLE into a profile, employment history and LinkedIn URL; IDENTIFY an ambiguous person as several scored candidates; SEARCH people by criteria (company, title, location); enrich COMPANIES into firmographics (industry, size, employees, HQ, founded, LinkedIn); and SEARCH companies by criteria. Do not scrape LinkedIn directly — this uses a licensed data aggregator (PDL) instead, for legal and reliability reasons.","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fpeople-enrichment\u002FSKILL.md",[],[],{"skillNo":191,"name":192,"nameZh":6,"description":193,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":194,"categories":195,"keywords":196,"publishedAt":19},"01M78AT0AZJ7WFY73766NBA1EC","notebooklm-mode","Source-grounded research pipeline inspired by NotebookLM. Collect verbatim source extracts into a temporary workspace, then answer questions and create deliverables grounded in those sources. Two grounding modes: strict (vault-only) and augmented (vault + labeled [background] knowledge). Trigger when the user asks to research a topic from sources, wants NotebookLM-style grounded answers, asks to build a resource vault, or says \"notebooklm mode\".","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fnotebooklm-mode\u002FSKILL.md",[],[],{"skillNo":198,"name":199,"nameZh":6,"description":200,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":201,"categories":202,"keywords":203,"publishedAt":19},"01M78ASTJVZ9G5JY6GM40SF909","news-monitoring","Use when a topic or news stream needs recurring monitoring — cover it with web search, multi-language sources, digest formatting, and automated delivery via Hermes cron jobs. Covers search strategy, source selection, Chinese-language platforms, and digest templates.","https:\u002F\u002Fgithub.com\u002Fmoonlight-lupin\u002Fagent-skills\u002Fblob\u002Fmain\u002Fresearch\u002Fnews-monitoring\u002FSKILL.md",[],[]]