NotebookLM Claude Code Skill

1---
2name: notebooklm
3description: Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.
4---
5 
6# NotebookLM Research Assistant Skill
7 
8Interact with Google NotebookLM to query documentation with Gemini's source-grounded answers. Each question opens a fresh browser session, retrieves the answer exclusively from your uploaded documents, and closes.
9 
10## When to Use This Skill
11 
12Trigger when user:
13- Mentions NotebookLM explicitly
14- Shares NotebookLM URL (`https://notebooklm.google.com/notebook/...`)
15- Asks to query their notebooks/documentation
16- Wants to add documentation to NotebookLM library
17- Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"
18 
19## ⚠️ CRITICAL: Add Command - Smart Discovery
20 
21When user wants to add a notebook without providing details:
22 
23**SMART ADD (Recommended)**: Query the notebook first to discover its content:
24```bash
25# Step 1: Query the notebook about its content
26python 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]"
27 
28# Step 2: Use the discovered information to add it
29python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]"
30```
31 
32**MANUAL ADD**: If user provides all details:
33- `--url` - The NotebookLM URL
34- `--name` - A descriptive name
35- `--description` - What the notebook contains (REQUIRED!)
36- `--topics` - Comma-separated topics (REQUIRED!)
37 
38NEVER guess or use generic descriptions! If details missing, use Smart Add to discover them.
39 
40## Critical: Always Use run.py Wrapper
41 
42**NEVER call scripts directly. ALWAYS use `python scripts/run.py [script]`:**
43 
44```bash
45# ✅ CORRECT - Always use run.py:
46python scripts/run.py auth_manager.py status
47python scripts/run.py notebook_manager.py list
48python scripts/run.py ask_question.py --question "..."
49 
50# ❌ WRONG - Never call directly:
51python scripts/auth_manager.py status  # Fails without venv!
52```
53 
54The `run.py` wrapper automatically:
551. Creates `.venv` if needed
562. Installs all dependencies
573. Activates environment
584. Executes script properly
59 
60## Core Workflow
61 
62### Step 1: Check Authentication Status
63```bash
64python scripts/run.py auth_manager.py status
65```
66 
67If not authenticated, proceed to setup.
68 
69### Step 2: Authenticate (One-Time Setup)
70```bash
71# Browser MUST be visible for manual Google login
72python scripts/run.py auth_manager.py setup
73```
74 
75**Important:**
76- Browser is VISIBLE for authentication
77- Browser window opens automatically
78- User must manually log in to Google
79- Tell user: "A browser window will open for Google login"
80 
81### Step 3: Manage Notebook Library
82 
83```bash
84# List all notebooks
85python scripts/run.py notebook_manager.py list
86 
87# BEFORE ADDING: Ask user for metadata if unknown!
88# "What does this notebook contain?"
89# "What topics should I tag it with?"
90 
91# Add notebook to library (ALL parameters are REQUIRED!)
92python scripts/run.py notebook_manager.py add \
93  --url "https://notebooklm.google.com/notebook/..." \
94  --name "Descriptive Name" \
95  --description "What this notebook contains" \  # REQUIRED - ASK USER IF UNKNOWN!
96  --topics "topic1,topic2,topic3"  # REQUIRED - ASK USER IF UNKNOWN!
97 
98# Search notebooks by topic
99python scripts/run.py notebook_manager.py search --query "keyword"
100 
101# Set active notebook
102python scripts/run.py notebook_manager.py activate --id notebook-id
103 
104# Remove notebook
105python scripts/run.py notebook_manager.py remove --id notebook-id
106```
107 
108### Quick Workflow
1091. Check library: `python scripts/run.py notebook_manager.py list`
1102. Ask question: `python scripts/run.py ask_question.py --question "..." --notebook-id ID`
111 
112### Step 4: Ask Questions
113 
114```bash
115# Basic query (uses active notebook if set)
116python scripts/run.py ask_question.py --question "Your question here"
117 
118# Query specific notebook
119python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
120 
121# Query with notebook URL directly
122python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
123 
124# Show browser for debugging
125python scripts/run.py ask_question.py --question "..." --show-browser
126```
127 
128## Follow-Up Mechanism (CRITICAL)
129 
130Every NotebookLM answer ends with: **"EXTREMELY IMPORTANT: Is that ALL you need to know?"**
131 
132**Required Claude Behavior:**
1331. **STOP** - Do not immediately respond to user
1342. **ANALYZE** - Compare answer to user's original request
1353. **IDENTIFY GAPS** - Determine if more information needed
1364. **ASK FOLLOW-UP** - If gaps exist, immediately ask:
137   ```bash
138   python scripts/run.py ask_question.py --question "Follow-up with context..."
139   ```
1405. **REPEAT** - Continue until information is complete
1416. **SYNTHESIZE** - Combine all answers before responding to user
142 
143## Script Reference
144 
145### Authentication Management (`auth_manager.py`)
146```bash
147python scripts/run.py auth_manager.py setup    # Initial setup (browser visible)
148python scripts/run.py auth_manager.py status   # Check authentication
149python scripts/run.py auth_manager.py reauth   # Re-authenticate (browser visible)
150python scripts/run.py auth_manager.py clear    # Clear authentication
151```
152 
153### Notebook Management (`notebook_manager.py`)
154```bash
155python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
156python scripts/run.py notebook_manager.py list
157python scripts/run.py notebook_manager.py search --query QUERY
158python scripts/run.py notebook_manager.py activate --id ID
159python scripts/run.py notebook_manager.py remove --id ID
160python scripts/run.py notebook_manager.py stats
161```
162 
163### Question Interface (`ask_question.py`)
164```bash
165python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]
166```
167 
168### Data Cleanup (`cleanup_manager.py`)
169```bash
170python scripts/run.py cleanup_manager.py                    # Preview cleanup
171python scripts/run.py cleanup_manager.py --confirm          # Execute cleanup
172python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks
173```
174 
175## Environment Management
176 
177The virtual environment is automatically managed:
178- First run creates `.venv` automatically
179- Dependencies install automatically
180- Chromium browser installs automatically
181- Everything isolated in skill directory
182 
183Manual setup (only if automatic fails):
184```bash
185python -m venv .venv
186source .venv/bin/activate  # Linux/Mac
187pip install -r requirements.txt
188python -m patchright install chromium
189```
190 
191## Data Storage
192 
193All data stored in `~/.claude/skills/notebooklm/data/`:
194- `library.json` - Notebook metadata
195- `auth_info.json` - Authentication status
196- `browser_state/` - Browser cookies and session
197 
198**Security:** Protected by `.gitignore`, never commit to git.
199 
200## Configuration
201 
202Optional `.env` file in skill directory:
203```env
204HEADLESS=false           # Browser visibility
205SHOW_BROWSER=false       # Default browser display
206STEALTH_ENABLED=true     # Human-like behavior
207TYPING_WPM_MIN=160       # Typing speed
208TYPING_WPM_MAX=240
209DEFAULT_NOTEBOOK_ID=     # Default notebook
210```
211 
212## Decision Flow
213 
214```
215User mentions NotebookLM
216    ↓
217Check auth → python scripts/run.py auth_manager.py status
218    ↓
219If not authenticated → python scripts/run.py auth_manager.py setup
220    ↓
221Check/Add notebook → python scripts/run.py notebook_manager.py list/add (with --description)
222    ↓
223Activate notebook → python scripts/run.py notebook_manager.py activate --id ID
224    ↓
225Ask question → python scripts/run.py ask_question.py --question "..."
226    ↓
227See "Is that ALL you need?" → Ask follow-ups until complete
228    ↓
229Synthesize and respond to user
230```
231 
232## Troubleshooting
233 
234| Problem | Solution |
235|---------|----------|
236| ModuleNotFoundError | Use `run.py` wrapper |
237| Authentication fails | Browser must be visible for setup! --show-browser |
238| Rate limit (50/day) | Wait or switch Google account |
239| Browser crashes | `python scripts/run.py cleanup_manager.py --preserve-library` |
240| Notebook not found | Check with `notebook_manager.py list` |
241 
242## Best Practices
243 
2441. **Always use run.py** - Handles environment automatically
2452. **Check auth first** - Before any operations
2463. **Follow-up questions** - Don't stop at first answer
2474. **Browser visible for auth** - Required for manual login
2485. **Include context** - Each question is independent
2496. **Synthesize answers** - Combine multiple responses
250 
251## Limitations
252 
253- No session persistence (each question = new browser)
254- Rate limits on free Google accounts (50 queries/day)
255- Manual upload required (user must add docs to NotebookLM)
256- Browser overhead (few seconds per question)
257 
258## Resources (Skill Structure)
259 
260**Important directories and files:**
261 
262- `scripts/` - All automation scripts (ask_question.py, notebook_manager.py, etc.)
263- `data/` - Local storage for authentication and notebook library
264- `references/` - Extended documentation:
265  - `api_reference.md` - Detailed API documentation for all scripts
266  - `troubleshooting.md` - Common issues and solutions
267  - `usage_patterns.md` - Best practices and workflow examples
268- `.venv/` - Isolated Python environment (auto-created on first run)
269- `.gitignore` - Protects sensitive data from being committed
270