notebooklm

•

24.4k23983 months ago

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.

Quick Install

npxskills add davila7/claude-code-templates--skill notebooklm

Instructions

NotebookLM Research Assistant Skill

Interact 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.

When to Use This Skill

Trigger when user:

Mentions NotebookLM explicitly
Shares NotebookLM URL (https://notebooklm.google.com/notebook/...)
Asks to query their notebooks/documentation
Wants to add documentation to NotebookLM library
Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"

⚠️ CRITICAL: Add Command - Smart Discovery

When user wants to add a notebook without providing details:

SMART ADD (Recommended): Query the notebook first to discover its content:

# Step 1: Query the notebook about its content
python 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: Use the discovered information to add it
python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]"

MANUAL ADD: If user provides all details:

--url - The NotebookLM URL
--name - A descriptive name
--description - What the notebook contains (REQUIRED!)
--topics - Comma-separated topics (REQUIRED!)

NEVER guess or use generic descriptions! If details missing, use Smart Add to discover them.

Critical: Always Use run.py Wrapper

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

# ✅ CORRECT - Always use run.py:
python scripts/run.py auth_manager.py status
python scripts/run.py notebook_manager.py list
python scripts/run.py ask_question.py --question "..."

# ❌ WRONG - Never call directly:
python scripts/auth_manager.py status  # Fails without venv!

The run.py wrapper automatically:

Creates .venv if needed
Installs all dependencies
Activates environment
Executes script properly

Core Workflow

Step 1: Check Authentication Status

python scripts/run.py auth_manager.py status

If not authenticated, proceed to setup.

Step 2: Authenticate (One-Time Setup)

# Browser MUST be visible for manual Google login
python scripts/run.py auth_manager.py setup

Important:

Browser is VISIBLE for authentication
Browser window opens automatically
User must manually log in to Google
Tell user: "A browser window will open for Google login"

Step 3: Manage Notebook Library

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

# BEFORE ADDING: Ask user for metadata if unknown!
# "What does this notebook contain?"
# "What topics should I tag it with?"

# Add notebook to library (ALL parameters are REQUIRED!)
python scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \  # REQUIRED - ASK USER IF UNKNOWN!
  --topics "topic1,topic2,topic3"  # REQUIRED - ASK USER IF UNKNOWN!

# Search notebooks by topic
python scripts/run.py notebook_manager.py search --query "keyword"

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

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

Quick Workflow

Check library: python scripts/run.py notebook_manager.py list
Ask question: python scripts/run.py ask_question.py --question "..." --notebook-id ID

Step 4: Ask Questions

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

# Query specific notebook
python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

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

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

Follow-Up Mechanism (CRITICAL)

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

Required Claude Behavior:

STOP - Do not immediately respond to user
ANALYZE - Compare answer to user's original request
IDENTIFY GAPS - Determine if more information needed

ASK FOLLOW-UP - If gaps exist, immediately ask:

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

REPEAT - Continue until information is complete
SYNTHESIZE - Combine all answers before responding to user

Script Reference

Authentication Management (`auth_manager.py`)

python scripts/run.py auth_manager.py setup    # Initial setup (browser visible)
python scripts/run.py auth_manager.py status   # Check authentication
python scripts/run.py auth_manager.py reauth   # Re-authenticate (browser visible)
python scripts/run.py auth_manager.py clear    # Clear authentication

Notebook Management (`notebook_manager.py`)

python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
python scripts/run.py notebook_manager.py list
python scripts/run.py notebook_manager.py search --query QUERY
python scripts/run.py notebook_manager.py activate --id ID
python scripts/run.py notebook_manager.py remove --id ID
python scripts/run.py notebook_manager.py stats

Question Interface (`ask_question.py`)

python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]

Data Cleanup (`cleanup_manager.py`)

python scripts/run.py cleanup_manager.py                    # Preview cleanup
python scripts/run.py cleanup_manager.py --confirm          # Execute cleanup
python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks

Environment Management

The virtual environment is automatically managed:

First run creates .venv automatically
Dependencies install automatically
Chromium browser installs automatically
Everything isolated in skill directory

Manual setup (only if automatic fails):

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
python -m patchright install chromium

Data Storage

All data stored in ~/.claude/skills/notebooklm/data/:

library.json - Notebook metadata
auth_info.json - Authentication status
browser_state/ - Browser cookies and session

Security: Protected by .gitignore, never commit to git.

Configuration

Optional .env file in skill directory:

HEADLESS=false           # Browser visibility
SHOW_BROWSER=false       # Default browser display
STEALTH_ENABLED=true     # Human-like behavior
TYPING_WPM_MIN=160       # Typing speed
TYPING_WPM_MAX=240
DEFAULT_NOTEBOOK_ID=     # Default notebook

Decision Flow

User mentions NotebookLM
    ↓
Check auth → python scripts/run.py auth_manager.py status
    ↓
If not authenticated → python scripts/run.py auth_manager.py setup
    ↓
Check/Add notebook → python scripts/run.py notebook_manager.py list/add (with --description)
    ↓
Activate notebook → python scripts/run.py notebook_manager.py activate --id ID
    ↓
Ask question → python scripts/run.py ask_question.py --question "..."
    ↓
See "Is that ALL you need?" → Ask follow-ups until complete
    ↓
Synthesize and respond to user

Troubleshooting

Problem	Solution
ModuleNotFoundError	Use `run.py` wrapper
Authentication fails	Browser must be visible for setup! --show-browser
Rate limit (50/day)	Wait or switch Google account
Browser crashes	`python scripts/run.py cleanup_manager.py --preserve-library`
Notebook not found	Check with `notebook_manager.py list`

Best Practices

Always use run.py - Handles environment automatically
Check auth first - Before any operations
Follow-up questions - Don't stop at first answer
Browser visible for auth - Required for manual login
Include context - Each question is independent
Synthesize answers - Combine multiple responses

Limitations

No session persistence (each question = new browser)
Rate limits on free Google accounts (50 queries/day)
Manual upload required (user must add docs to NotebookLM)
Browser overhead (few seconds per question)

Resources (Skill Structure)

Important directories and files:

scripts/ - All automation scripts (ask_question.py, notebook_manager.py, etc.)
data/ - Local storage for authentication and notebook library
references/ - Extended documentation:
- api_reference.md - Detailed API documentation for all scripts
- troubleshooting.md - Common issues and solutions
- usage_patterns.md - Best practices and workflow examples
.venv/ - Isolated Python environment (auto-created on first run)
.gitignore - Protects sensitive data from being committed

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885

Tags & Topics

anthropicanthropic-claudeclaudeclaude-code

NotebookLM Research Assistant Skill

When to Use This Skill

Trigger when user:

Mentions NotebookLM explicitly
Shares NotebookLM URL (https://notebooklm.google.com/notebook/...)
Asks to query their notebooks/documentation
Wants to add documentation to NotebookLM library
Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"

⚠️ CRITICAL: Add Command - Smart Discovery

When user wants to add a notebook without providing details:

SMART ADD (Recommended): Query the notebook first to discover its content:

# Step 1: Query the notebook about its content
python 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: Use the discovered information to add it
python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]"

MANUAL ADD: If user provides all details:

--url - The NotebookLM URL
--name - A descriptive name
--description - What the notebook contains (REQUIRED!)
--topics - Comma-separated topics (REQUIRED!)

NEVER guess or use generic descriptions! If details missing, use Smart Add to discover them.

Critical: Always Use run.py Wrapper

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

# ✅ CORRECT - Always use run.py:
python scripts/run.py auth_manager.py status
python scripts/run.py notebook_manager.py list
python scripts/run.py ask_question.py --question "..."

# ❌ WRONG - Never call directly:
python scripts/auth_manager.py status  # Fails without venv!

The run.py wrapper automatically:

Creates .venv if needed
Installs all dependencies
Activates environment
Executes script properly

Core Workflow

Step 1: Check Authentication Status

python scripts/run.py auth_manager.py status

If not authenticated, proceed to setup.

Step 2: Authenticate (One-Time Setup)

# Browser MUST be visible for manual Google login
python scripts/run.py auth_manager.py setup

Important:

Browser is VISIBLE for authentication
Browser window opens automatically
User must manually log in to Google
Tell user: "A browser window will open for Google login"

Step 3: Manage Notebook Library

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

# BEFORE ADDING: Ask user for metadata if unknown!
# "What does this notebook contain?"
# "What topics should I tag it with?"

# Add notebook to library (ALL parameters are REQUIRED!)
python scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \  # REQUIRED - ASK USER IF UNKNOWN!
  --topics "topic1,topic2,topic3"  # REQUIRED - ASK USER IF UNKNOWN!

# Search notebooks by topic
python scripts/run.py notebook_manager.py search --query "keyword"

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

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

Quick Workflow

Check library: python scripts/run.py notebook_manager.py list
Ask question: python scripts/run.py ask_question.py --question "..." --notebook-id ID

Step 4: Ask Questions

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

# Query specific notebook
python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

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

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

Follow-Up Mechanism (CRITICAL)

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

Required Claude Behavior:

STOP - Do not immediately respond to user
ANALYZE - Compare answer to user's original request
IDENTIFY GAPS - Determine if more information needed

ASK FOLLOW-UP - If gaps exist, immediately ask:

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

REPEAT - Continue until information is complete
SYNTHESIZE - Combine all answers before responding to user

Script Reference

Authentication Management (`auth_manager.py`)

python scripts/run.py auth_manager.py setup    # Initial setup (browser visible)
python scripts/run.py auth_manager.py status   # Check authentication
python scripts/run.py auth_manager.py reauth   # Re-authenticate (browser visible)
python scripts/run.py auth_manager.py clear    # Clear authentication

Notebook Management (`notebook_manager.py`)

python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
python scripts/run.py notebook_manager.py list
python scripts/run.py notebook_manager.py search --query QUERY
python scripts/run.py notebook_manager.py activate --id ID
python scripts/run.py notebook_manager.py remove --id ID
python scripts/run.py notebook_manager.py stats

Question Interface (`ask_question.py`)

python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]

Data Cleanup (`cleanup_manager.py`)

python scripts/run.py cleanup_manager.py                    # Preview cleanup
python scripts/run.py cleanup_manager.py --confirm          # Execute cleanup
python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks

Environment Management

The virtual environment is automatically managed:

First run creates .venv automatically
Dependencies install automatically
Chromium browser installs automatically
Everything isolated in skill directory

Manual setup (only if automatic fails):

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
python -m patchright install chromium

Data Storage

All data stored in ~/.claude/skills/notebooklm/data/:

library.json - Notebook metadata
auth_info.json - Authentication status
browser_state/ - Browser cookies and session

Security: Protected by .gitignore, never commit to git.

Configuration

Optional .env file in skill directory:

HEADLESS=false           # Browser visibility
SHOW_BROWSER=false       # Default browser display
STEALTH_ENABLED=true     # Human-like behavior
TYPING_WPM_MIN=160       # Typing speed
TYPING_WPM_MAX=240
DEFAULT_NOTEBOOK_ID=     # Default notebook

Decision Flow

User mentions NotebookLM
    ↓
Check auth → python scripts/run.py auth_manager.py status
    ↓
If not authenticated → python scripts/run.py auth_manager.py setup
    ↓
Check/Add notebook → python scripts/run.py notebook_manager.py list/add (with --description)
    ↓
Activate notebook → python scripts/run.py notebook_manager.py activate --id ID
    ↓
Ask question → python scripts/run.py ask_question.py --question "..."
    ↓
See "Is that ALL you need?" → Ask follow-ups until complete
    ↓
Synthesize and respond to user

Troubleshooting

Problem	Solution
ModuleNotFoundError	Use `run.py` wrapper
Authentication fails	Browser must be visible for setup! --show-browser
Rate limit (50/day)	Wait or switch Google account
Browser crashes	`python scripts/run.py cleanup_manager.py --preserve-library`
Notebook not found	Check with `notebook_manager.py list`

Best Practices

Always use run.py - Handles environment automatically
Check auth first - Before any operations
Follow-up questions - Don't stop at first answer
Browser visible for auth - Required for manual login
Include context - Each question is independent
Synthesize answers - Combine multiple responses

Limitations

No session persistence (each question = new browser)
Rate limits on free Google accounts (50 queries/day)
Manual upload required (user must add docs to NotebookLM)
Browser overhead (few seconds per question)

Resources (Skill Structure)

Important directories and files:

scripts/ - All automation scripts (ask_question.py, notebook_manager.py, etc.)
data/ - Local storage for authentication and notebook library
references/ - Extended documentation:
- api_reference.md - Detailed API documentation for all scripts
- troubleshooting.md - Common issues and solutions
- usage_patterns.md - Best practices and workflow examples
.venv/ - Isolated Python environment (auto-created on first run)
.gitignore - Protects sensitive data from being committed

notebooklm

NotebookLM Research Assistant Skill

When to Use This Skill

⚠️ CRITICAL: Add Command - Smart Discovery

Critical: Always Use run.py Wrapper

Core Workflow

Step 1: Check Authentication Status

Step 2: Authenticate (One-Time Setup)

Step 3: Manage Notebook Library

Quick Workflow

Step 4: Ask Questions

Follow-Up Mechanism (CRITICAL)

Script Reference

Authentication Management (auth_manager.py)

Notebook Management (notebook_manager.py)

Question Interface (ask_question.py)

Data Cleanup (cleanup_manager.py)

Environment Management

Data Storage

Configuration

Decision Flow

Troubleshooting

Best Practices

Limitations

Resources (Skill Structure)

Related Skills

skill-creator

skill-creator

1password

himalaya

NotebookLM Research Assistant Skill

When to Use This Skill

⚠️ CRITICAL: Add Command - Smart Discovery

Critical: Always Use run.py Wrapper

Core Workflow

Step 1: Check Authentication Status

Step 2: Authenticate (One-Time Setup)

Step 3: Manage Notebook Library

Quick Workflow

Step 4: Ask Questions

Follow-Up Mechanism (CRITICAL)

Script Reference

Authentication Management (auth_manager.py)

Notebook Management (notebook_manager.py)

Question Interface (ask_question.py)

Data Cleanup (cleanup_manager.py)

Environment Management

Data Storage

Configuration

Decision Flow

Troubleshooting

Best Practices

Limitations

Resources (Skill Structure)

Related Skills

skill-creator

skill-creator

1password

himalaya

Related Skills

skill-creator

skill-creator

1password

himalaya

Authentication Management (`auth_manager.py`)

Notebook Management (`notebook_manager.py`)

Question Interface (`ask_question.py`)

Data Cleanup (`cleanup_manager.py`)

Authentication Management (`auth_manager.py`)

Notebook Management (`notebook_manager.py`)

Question Interface (`ask_question.py`)

Data Cleanup (`cleanup_manager.py`)