blog-notebooklm

Original：🇺🇸 English

Translated

10 scripts

Query Google NotebookLM notebooks for source-grounded, citation-backed answers from user-uploaded documents. Manages notebook library, handles Google authentication, and supports smart discovery. Works standalone via /blog notebooklm or internally from blog-write and blog-researcher for Tier 1 research data. Falls back gracefully when not configured. Use when user says "notebooklm", "notebook", "query notebook", "ask notebook", "notebook research", "source grounded research", "document query", "notebook library".

3installs

Sourceagricidaniel/claude-blog

Added on2026-05-11

NPX Install

npx skill4agent add agricidaniel/claude-blog blog-notebooklm

SKILL.md Content

View Translation Comparison →

Blog NotebookLM -- Source-Grounded Research from Your Documents

Query Google NotebookLM notebooks directly from Claude Code for citation-backed answers from Gemini. Each question opens a headless browser session, retrieves the answer exclusively from your uploaded documents, and closes. Responses are Tier 1 quality (user's own primary sources) -- zero hallucination risk. Answers satisfy the FLOW evidence triple: use the returned source title as the inline citation and the notebook URL plus retrieval date as the bibliography entry. This is the highest-confidence path to meeting the "verified source" bar that FLOW requires before any statistic goes public.

Quick Reference

Command	What it does
`/blog notebooklm ask <question>`	Query a notebook for source-grounded answers
`/blog notebooklm discover <url>`	Smart-discover notebook content before cataloging
`/blog notebooklm library list`	List all notebooks in library
`/blog notebooklm library add <url>`	Add a notebook to library
`/blog notebooklm library search <query>`	Search notebooks by keyword
`/blog notebooklm library remove <id>`	Remove a notebook from library
`/blog notebooklm setup`	One-time Google authentication (browser visible)
`/blog notebooklm status`	Check authentication status
`/blog notebooklm cleanup`	Clean browser state (preserves library)

Prerequisites

Google account with NotebookLM access
Python 3.11+ (venv managed automatically by
```
run.py
```
)
Google Chrome (installed automatically on first run via Patchright)
One-time authentication setup (interactive Google login in visible browser)

Always Use run.py Wrapper

NEVER call scripts directly. ALWAYS use
python3 scripts/run.py [script]
:

bash

# CORRECT:
python3 scripts/run.py auth_manager.py status
python3 scripts/run.py ask_question.py --question "..."

# WRONG -- fails without venv:
python3 scripts/auth_manager.py status

The

run.py

wrapper automatically creates

.venv

, installs dependencies, sets up Chrome, and executes the target script.

Auth Check (Gate Pattern)

Before any query operation, check authentication:

bash

python3 scripts/run.py auth_manager.py status

If authenticated: proceed with the query
If not authenticated: inform user and guide to setup: "NotebookLM requires Google login. Run
```
/blog notebooklm setup
```
to authenticate."
When called internally (from blog-write or blog-researcher): return silently with no error if not authenticated. Never block the writing workflow.

Setup Workflow

For

/blog notebooklm setup

bash

# Opens a visible browser for manual Google login (one-time)
python3 scripts/run.py auth_manager.py setup

Tell the user: "A browser window will open. Please log in to your Google account." Authentication persists via browser profile + cookie injection (hybrid approach).

Other auth commands:

bash

python3 scripts/run.py auth_manager.py status   # Check auth
python3 scripts/run.py auth_manager.py reauth   # Re-authenticate
python3 scripts/run.py auth_manager.py clear     # Clear all auth data

Query Workflow

For

/blog notebooklm ask <question>

Step 1: Check Auth

Run auth check (see gate pattern above). If not authenticated, guide to setup.

Step 2: Resolve Notebook

Determine which notebook to query:

If
```
--notebook-url
```
provided: use directly
If
```
--notebook-id
```
provided: look up in library
If neither: use active notebook from library
If no active notebook: show library and ask user to select

Step 3: Ask the Question

bash

# Basic query (uses active notebook)
python3 scripts/run.py ask_question.py --question "Your question here"

# Query specific notebook by ID
python3 scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

# Query by URL directly
python3 scripts/run.py ask_question.py --question "..." --notebook-url "https://..."

# JSON output (for internal/programmatic use)
python3 scripts/run.py ask_question.py --question "..." --json

# Show browser for debugging
python3 scripts/run.py ask_question.py --question "..." --show-browser

Step 4: Analyze and Follow Up

Every response ends with a follow-up prompt. Required behavior:

STOP -- do not immediately respond to the user
ANALYZE -- compare the answer to the user's original request
IDENTIFY GAPS -- determine if more information is needed
ASK FOLLOW-UP -- if gaps exist, immediately ask a follow-up question
REPEAT -- continue until information is complete
SYNTHESIZE -- combine all answers before responding to the user

Smart Discovery Workflow

For

/blog notebooklm discover <url>

When adding a notebook without knowing its content, query it first:

bash

# Step 1: Discover content
python3 scripts/run.py ask_question.py \
  --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" \
  --notebook-url "<URL>"

# Step 2: Add with discovered metadata
python3 scripts/run.py notebook_manager.py add \
  --url "<URL>" \
  --name "<Based on content>" \
  --description "<Based on content>" \
  --topics "<Extracted topics>"

NEVER guess or use generic descriptions. Always discover or ask the user.

Library Management

bash

# List all notebooks
python3 scripts/run.py notebook_manager.py list

# Add notebook (all params required -- discover or ask user!)
python3 scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \
  --topics "topic1,topic2,topic3"

# Search by keyword
python3 scripts/run.py notebook_manager.py search --query "keyword"

# Set active notebook
python3 scripts/run.py notebook_manager.py activate --id notebook-id

# Remove notebook
python3 scripts/run.py notebook_manager.py remove --id notebook-id

# Library statistics
python3 scripts/run.py notebook_manager.py stats

Internal API (for blog-write / blog-researcher)

When invoked as a Task subagent from blog-write or blog-researcher:

Input (provided by calling skill):

```
question
```
: Research question relevant to the blog topic
```
notebook_id
```
or
```
notebook_url
```
: Which notebook to query
```
context
```
: "internal" (signals graceful fallback mode)

Process:

Check auth status -- if not authenticated, return empty result silently
Query the notebook with the research question
Parse and return structured response

Output (returned to calling skill):

markdown

### NotebookLM Research
- **Source:** [Notebook name]
- **Question:** [What was asked]
- **Answer:** [Source-grounded response from user's documents]
- **Source Quality:** Tier 1 (user-uploaded primary documents)

Graceful fallback: If auth is missing or query fails, return immediately with no error. The calling workflow continues with WebSearch-based research. Never block blog-write or blog-rewrite because NotebookLM is unavailable.

Data Storage

All data stored inside the skill directory:

```
scripts/data/library.json
```
-- Notebook metadata and library
```
scripts/data/auth_info.json
```
-- Authentication status
```
scripts/data/browser_state/
```
-- Chrome profile with cookies

Security: All data directories are gitignored. Never commit auth or browser state.

Error Handling

Error	Resolution
Not authenticated	Run `/blog notebooklm setup`
ModuleNotFoundError	Always use `run.py` wrapper
Browser crash	`cleanup_manager.py --confirm --preserve-library` , then re-auth
Rate limit (50/day)	Wait until midnight PST or switch Google account
Notebook not found	Check with `notebook_manager.py list`
Query timeout (120s)	Retry with simpler question or `--show-browser` to debug
MCP unavailable (internal)	Return silently -- writing workflow uses WebSearch

Limitations

No session persistence (each question = new browser session)
Rate limits on free Google accounts (50 queries/day)
Manual upload required (user must add docs to NotebookLM web UI)
Browser overhead (few seconds per question for launch + teardown)
Local Claude Code only (not available in web UI)

Reference Documentation

Load on-demand -- do NOT load all at startup:

```
references/commands.md
```
-- Full CLI commands, parameters, and workflow patterns
```
references/troubleshooting.md
```
-- Error solutions, recovery procedures, debugging

blog-notebooklm

NPX Install

Tags

SKILL.md Content

Blog NotebookLM -- Source-Grounded Research from Your Documents

Quick Reference

Prerequisites

Always Use run.py Wrapper

Auth Check (Gate Pattern)

Setup Workflow

Query Workflow

Step 1: Check Auth

Step 2: Resolve Notebook

Step 3: Ask the Question

Step 4: Analyze and Follow Up

Smart Discovery Workflow

Library Management

Internal API (for blog-write / blog-researcher)

Data Storage

Error Handling

Limitations

Reference Documentation