1# NotebookLM Skill Usage Patterns
2 
3Advanced patterns for using the NotebookLM skill effectively.
4 
5## Critical: Always Use run.py
6 
7**Every command must use the run.py wrapper:**
8```bash
9# ✅ CORRECT:
10python scripts/run.py auth_manager.py status
11python scripts/run.py ask_question.py --question "..."
12 
13# ❌ WRONG:
14python scripts/auth_manager.py status  # Will fail!
15```
16 
17## Pattern 1: Initial Setup
18 
19```bash
20# 1. Check authentication (using run.py!)
21python scripts/run.py auth_manager.py status
22 
23# 2. If not authenticated, setup (Browser MUST be visible!)
24python scripts/run.py auth_manager.py setup
25# Tell user: "Please log in to Google in the browser window"
26 
27# 3. Add first notebook - ASK USER FOR DETAILS FIRST!
28# Ask: "What does this notebook contain?"
29# Ask: "What topics should I tag it with?"
30python scripts/run.py notebook_manager.py add \
31  --url "https://notebooklm.google.com/notebook/..." \
32  --name "User provided name" \
33  --description "User provided description" \  # NEVER GUESS!
34  --topics "user,provided,topics"  # NEVER GUESS!
35```
36 
37**Critical Notes:**
38- Virtual environment created automatically by run.py
39- Browser MUST be visible for authentication
40- ALWAYS discover content via query OR ask user for notebook metadata
41 
42## Pattern 2: Adding Notebooks (Smart Discovery!)
43 
44**When user shares a NotebookLM URL:**
45 
46**OPTION A: Smart Discovery (Recommended)**
47```bash
48# 1. Query the notebook to discover its content
49python scripts/run.py ask_question.py \
50  --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" \
51  --notebook-url "[URL]"
52 
53# 2. Use discovered info to add it
54python scripts/run.py notebook_manager.py add \
55  --url "[URL]" \
56  --name "[Based on content]" \
57  --description "[From discovery]" \
58  --topics "[Extracted topics]"
59```
60 
61**OPTION B: Ask User (Fallback)**
62```bash
63# If discovery fails, ask user:
64"What does this notebook contain?"
65"What topics does it cover?"
66 
67# Then add with user-provided info:
68python scripts/run.py notebook_manager.py add \
69  --url "[URL]" \
70  --name "[User's answer]" \
71  --description "[User's description]" \
72  --topics "[User's topics]"
73```
74 
75**NEVER:**
76- Guess what's in a notebook
77- Use generic descriptions
78- Skip discovering content
79 
80## Pattern 3: Daily Research Workflow
81 
82```bash
83# Check library
84python scripts/run.py notebook_manager.py list
85 
86# Research with comprehensive questions
87python scripts/run.py ask_question.py \
88  --question "Detailed question with all context" \
89  --notebook-id notebook-id
90 
91# Follow-up when you see "Is that ALL you need to know?"
92python scripts/run.py ask_question.py \
93  --question "Follow-up question with previous context"
94```
95 
96## Pattern 4: Follow-Up Questions (CRITICAL!)
97 
98When NotebookLM responds with "EXTREMELY IMPORTANT: Is that ALL you need to know?":
99 
100```python
101# 1. STOP - Don't respond to user yet
102# 2. ANALYZE - Is answer complete?
103# 3. If gaps exist, ask follow-up:
104python scripts/run.py ask_question.py \
105  --question "Specific follow-up with context from previous answer"
106 
107# 4. Repeat until complete
108# 5. Only then synthesize and respond to user
109```
110 
111## Pattern 5: Multi-Notebook Research
112 
113```python
114# Query different notebooks for comparison
115python scripts/run.py notebook_manager.py activate --id notebook-1
116python scripts/run.py ask_question.py --question "Question"
117 
118python scripts/run.py notebook_manager.py activate --id notebook-2
119python scripts/run.py ask_question.py --question "Same question"
120 
121# Compare and synthesize answers
122```
123 
124## Pattern 6: Error Recovery
125 
126```bash
127# If authentication fails
128python scripts/run.py auth_manager.py status
129python scripts/run.py auth_manager.py reauth  # Browser visible!
130 
131# If browser crashes
132python scripts/run.py cleanup_manager.py --preserve-library
133python scripts/run.py auth_manager.py setup  # Browser visible!
134 
135# If rate limited
136# Wait or switch accounts
137python scripts/run.py auth_manager.py reauth  # Login with different account
138```
139 
140## Pattern 7: Batch Processing
141 
142```bash
143#!/bin/bash
144NOTEBOOK_ID="notebook-id"
145QUESTIONS=(
146    "First comprehensive question"
147    "Second comprehensive question"
148    "Third comprehensive question"
149)
150 
151for question in "${QUESTIONS[@]}"; do
152    echo "Asking: $question"
153    python scripts/run.py ask_question.py \
154        --question "$question" \
155        --notebook-id "$NOTEBOOK_ID"
156    sleep 2  # Avoid rate limits
157done
158```
159 
160## Pattern 8: Automated Research Script
161 
162```python
163#!/usr/bin/env python
164import subprocess
165 
166def research_topic(topic, notebook_id):
167    # Comprehensive question
168    question = f"""
169    Explain {topic} in detail:
170    1. Core concepts
171    2. Implementation details
172    3. Best practices
173    4. Common pitfalls
174    5. Examples
175    """
176 
177    result = subprocess.run([
178        "python", "scripts/run.py", "ask_question.py",
179        "--question", question,
180        "--notebook-id", notebook_id
181    ], capture_output=True, text=True)
182 
183    return result.stdout
184```
185 
186## Pattern 9: Notebook Organization
187 
188```python
189# Organize by domain - with proper metadata
190# ALWAYS ask user for descriptions!
191 
192# Backend notebooks
193add_notebook("Backend API", "Complete API documentation", "api,rest,backend")
194add_notebook("Database", "Schema and queries", "database,sql,backend")
195 
196# Frontend notebooks
197add_notebook("React Docs", "React framework documentation", "react,frontend")
198add_notebook("CSS Framework", "Styling documentation", "css,styling,frontend")
199 
200# Search by domain
201python scripts/run.py notebook_manager.py search --query "backend"
202python scripts/run.py notebook_manager.py search --query "frontend"
203```
204 
205## Pattern 10: Integration with Development
206 
207```python
208# Query documentation during development
209def check_api_usage(api_endpoint):
210    result = subprocess.run([
211        "python", "scripts/run.py", "ask_question.py",
212        "--question", f"Parameters and response format for {api_endpoint}",
213        "--notebook-id", "api-docs"
214    ], capture_output=True, text=True)
215 
216    # If follow-up needed
217    if "Is that ALL you need" in result.stdout:
218        # Ask for examples
219        follow_up = subprocess.run([
220            "python", "scripts/run.py", "ask_question.py",
221            "--question", f"Show code examples for {api_endpoint}",
222            "--notebook-id", "api-docs"
223        ], capture_output=True, text=True)
224 
225    return combine_answers(result.stdout, follow_up.stdout)
226```
227 
228## Best Practices
229 
230### 1. Question Formulation
231- Be specific and comprehensive
232- Include all context in each question
233- Request structured responses
234- Ask for examples when needed
235 
236### 2. Notebook Management
237- **ALWAYS ask user for metadata**
238- Use descriptive names
239- Add comprehensive topics
240- Keep URLs current
241 
242### 3. Performance
243- Batch related questions
244- Use parallel processing for different notebooks
245- Monitor rate limits (50/day)
246- Switch accounts if needed
247 
248### 4. Error Handling
249- Always use run.py to prevent venv issues
250- Check auth before operations
251- Implement retry logic
252- Have fallback notebooks ready
253 
254### 5. Security
255- Use dedicated Google account
256- Never commit data/ directory
257- Regularly refresh auth
258- Track all access
259 
260## Common Workflows for Claude
261 
262### Workflow 1: User Sends NotebookLM URL
263 
264```python
265# 1. Detect URL in message
266if "notebooklm.google.com" in user_message:
267    url = extract_url(user_message)
268 
269    # 2. Check if in library
270    notebooks = run("notebook_manager.py list")
271 
272    if url not in notebooks:
273        # 3. ASK USER FOR METADATA (CRITICAL!)
274        name = ask_user("What should I call this notebook?")
275        description = ask_user("What does this notebook contain?")
276        topics = ask_user("What topics does it cover?")
277 
278        # 4. Add with user-provided info
279        run(f"notebook_manager.py add --url {url} --name '{name}' --description '{description}' --topics '{topics}'")
280 
281    # 5. Use the notebook
282    answer = run(f"ask_question.py --question '{user_question}'")
283```
284 
285### Workflow 2: Research Task
286 
287```python
288# 1. Understand task
289task = "Implement feature X"
290 
291# 2. Formulate comprehensive questions
292questions = [
293    "Complete implementation guide for X",
294    "Error handling for X",
295    "Performance considerations for X"
296]
297 
298# 3. Query with follow-ups
299for q in questions:
300    answer = run(f"ask_question.py --question '{q}'")
301 
302    # Check if follow-up needed
303    if "Is that ALL you need" in answer:
304        # Ask more specific question
305        follow_up = run(f"ask_question.py --question 'Specific detail about {q}'")
306 
307# 4. Synthesize and implement
308```
309 
310## Tips and Tricks
311 
3121. **Always use run.py** - Prevents all venv issues
3132. **Ask for metadata** - Never guess notebook contents
3143. **Use verbose questions** - Include all context
3154. **Follow up automatically** - When you see the prompt
3165. **Monitor rate limits** - 50 queries per day
3176. **Batch operations** - Group related queries
3187. **Export important answers** - Save locally
3198. **Version control notebooks** - Track changes
3209. **Test auth regularly** - Before important tasks
32110. **Document everything** - Keep notes on notebooks
322 
323## Quick Reference
324 
325```bash
326# Always use run.py!
327python scripts/run.py [script].py [args]
328 
329# Common operations
330run.py auth_manager.py status          # Check auth
331run.py auth_manager.py setup           # Login (browser visible!)
332run.py notebook_manager.py list        # List notebooks
333run.py notebook_manager.py add ...     # Add (ask user for metadata!)
334run.py ask_question.py --question ...  # Query
335run.py cleanup_manager.py ...          # Clean up
336```
337 
338**Remember:** When in doubt, use run.py and ask the user for notebook details!