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".
Instrucciones de origen · Vista previa de solo lectura
name
blog-notebooklm
description
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".
Blog NotebookLM: Source-Grounded Research from Your Documents
Query Google NotebookLM notebooks directly from Antigravity 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]:
# 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:
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:
# 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:
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
# 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:
# 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
# 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
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 Antigravity 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
