notebooklm

NotebookLM Skill

Query Google NotebookLM notebooks for source-grounded answers exclusively from your uploaded documentation, drastically reducing hallucinations.

When to Use

Trigger when user:

• Mentions NotebookLM or shares URL (https://notebooklm.google.com/notebook/...)
• Asks to query notebooks/documentation ("ask my NotebookLM", "check my docs")
• Wants citations from specific sources
• Needs to add notebooks to library

Critical: Always Use run.py Wrapper

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

# ✅ CORRECT
python scripts/run.py auth_manager.py status
python scripts/run.py ask_question.py --question "..."

# ❌ WRONG - Fails without venv!
python scripts/auth_manager.py status

The run.py wrapper auto-creates .venv, installs dependencies, and executes properly.

Core Workflow

1. Check Authentication

python scripts/run.py auth_manager.py status

2. Authenticate (One-Time, Browser Visible)

python scripts/run.py auth_manager.py setup

Tell user: "A browser window will open for Google login"

3. Add Notebooks (Smart Discovery Recommended)

Smart Add: Query first to discover content:

# Step 1: Discover content
python scripts/run.py ask_question.py --question "What topics does this notebook cover?" --notebook-url "[URL]"

# Step 2: Add with discovered metadata
python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[From discovery]" --topics "[From discovery]"

Manual Add: Only if user provides all details:

python scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this contains" \  # REQUIRED
  --topics "topic1,topic2,topic3"      # REQUIRED

NEVER guess metadata! Use Smart Add if details unknown.

4. Ask Questions

# Uses active notebook
python scripts/run.py ask_question.py --question "Your question"

# Specific notebook
python scripts/run.py ask_question.py --question "..." --notebook-id ID

# Direct URL
python scripts/run.py ask_question.py --question "..." --notebook-url URL

Follow-Up Mechanism (CRITICAL)

Every answer ends with: "Is that ALL you need to know?"

Required behavior:

1. STOP - Don't immediately respond
2. ANALYZE - Compare answer to user's request
3. IDENTIFY GAPS - Determine missing information
4. ASK FOLLOW-UP - If gaps exist, ask immediately:

   python scripts/run.py ask_question.py --question "Follow-up with context..."
   

5. REPEAT - Continue until information complete
6. SYNTHESIZE - Combine all answers before responding

Quick Commands

# Authentication
python scripts/run.py auth_manager.py status|setup|reauth|clear

# Library management
python scripts/run.py notebook_manager.py list|search --query QUERY|activate --id ID|stats

# Cleanup (preserves library)
python scripts/run.py cleanup_manager.py --preserve-library --confirm

Troubleshooting

Error	Solution
ModuleNotFoundError	Use run.py wrapper
Authentication failed	Browser must be visible for setup
Rate limit (50/day)	Wait or switch Google account
Browser crashes	cleanup_manager.py --preserve-library

Important Notes

• Local Claude Code only - Web UI sandbox blocks network access
• Stateless sessions - Each question = fresh browser (3-5 sec overhead)
• Browser automation - UI changes will break selectors (see README maintenance section)
• Expect maintenance - NotebookLM updates require selector updates
• See README.md and references/ for comprehensive documentation

Data Storage

~/.claude/skills/notebooklm/data/
├── library.json         # Notebook metadata
├── auth_info.json       # Auth status
└── browser_state/       # Browser cookies (NEVER commit)

All sensitive data protected by .gitignore.