Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
pleaseprompto avatar

Notebooklm

  • 7.3k installs
  • 7.5k repo stars
  • Updated November 21, 2025
  • pleaseprompto/notebooklm-skill

notebooklm is a Claude Code skill that queries Google NotebookLM notebooks through browser automation for document-grounded answers with library and auth management scripts.

About

notebooklm is a Claude Code skill that queries Google NotebookLM notebooks for source-grounded, citation-backed answers from uploaded documents using Gemini through browser automation. Each question opens a fresh browser session, retrieves answers exclusively from notebook sources, and closes to reduce hallucinations. Authentication uses auth_manager.py setup with a visible browser for one-time Google login, storing session data under ~/.claude/skills/notebooklm/data/. Notebook library management supports list, add with required name description and topics, search, activate, and remove via notebook_manager.py. Questions run through ask_question.py with notebook-id or notebook-url, and agents must use the run.py wrapper for venv and dependency setup. A critical follow-up loop requires agents to ask additional NotebookLM questions until the user's request is fully answered before synthesizing a final response. Smart Add discovers notebook metadata by querying content before library registration.

  • Source-grounded NotebookLM answers via browser automation with reduced hallucinations.
  • Mandatory run.py wrapper for venv creation dependency install and script execution.
  • Notebook library with add list search activate and persistent auth in local data dir.
  • Follow-up loop: keep querying until user request is complete before responding.
  • Smart Add discovers notebook name description and topics by querying content first.

Notebooklm by the numbers

  • 7,289 all-time installs (skills.sh)
  • +92 installs in the week ending Jul 28, 2026 (Skillselion tracking)
  • Ranked #112 of 16,659 AI & Agent Building skills by installs in the Skillselion catalog
  • Security screen: MEDIUM risk (skills.sh audit)
  • Data as of Jul 28, 2026 (Skillselion catalog sync)
At a glance

notebooklm capabilities & compatibility

Capabilities
google authentication with visible browser setup · notebook library add list search activate remove · ask_question.py queries with notebook id or note · run.py wrapper for automatic venv and dependency · follow up question loop until user request compl · smart add metadata discovery from notebook conte
Use cases
research · documentation · web search
From the docs

What notebooklm says it does

Interact with Google NotebookLM to query documentation with Gemini's source-grounded answers.
SKILL.md
NEVER call scripts directly. ALWAYS use `python scripts/run.py [script]`:
SKILL.md
npx skills add https://github.com/pleaseprompto/notebooklm-skill --skill notebooklm

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs7.3k
repo stars7.5k
Security audit1 / 3 scanners passed
Last updatedNovember 21, 2025
Repositorypleaseprompto/notebooklm-skill

How do I get citation-backed answers from my NotebookLM notebooks inside Claude Code without hallucinating beyond uploaded sources?

Query Google NotebookLM notebooks from Claude Code for source-grounded citation-backed answers via browser automation and library management.

Who is it for?

Claude Code users with NotebookLM notebooks who need scripted queries, library management, and follow-up research loops.

Skip if: Offline document search without Google login, API-only NotebookLM access without browser automation, or bulk document upload automation.

When should I use this skill?

User mentions NotebookLM, shares a notebooklm.google.com URL, or asks to query notebooks with ask my NotebookLM phrasing.

What you get

Authenticated notebook queries with library metadata, follow-up questions, and synthesized answers grounded in uploaded documents.

  • Citation-backed research answers
  • Notebook library query results

Files

SKILL.mdMarkdownGitHub ↗

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: 1. Creates .venv if needed 2. Installs all dependencies 3. Activates environment 4. 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

1. Check library: python scripts/run.py notebook_manager.py list 2. 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: 1. STOP - Do not immediately respond to user 2. ANALYZE - Compare answer to user's original request 3. IDENTIFY GAPS - Determine if more information needed 4. ASK FOLLOW-UP - If gaps exist, immediately ask:

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

5. REPEAT - Continue until information is complete 6. 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

ProblemSolution
ModuleNotFoundErrorUse run.py wrapper
Authentication failsBrowser must be visible for setup! --show-browser
Rate limit (50/day)Wait or switch Google account
Browser crashespython scripts/run.py cleanup_manager.py --preserve-library
Notebook not foundCheck with notebook_manager.py list

Best Practices

1. Always use run.py - Handles environment automatically 2. Check auth first - Before any operations 3. Follow-up questions - Don't stop at first answer 4. Browser visible for auth - Required for manual login 5. Include context - Each question is independent 6. 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

Related skills

Forks & variants (4)

Notebooklm has 4 known copies in the catalog totaling 967 installs. They canonicalize to this original listing.

How it compares

Pick notebooklm when corpora already live in Google NotebookLM; use repo-native RAG skills when sources are only in the git workspace.

FAQ

Why must scripts use run.py?

run.py creates the venv, installs dependencies, activates the environment, and executes scripts; direct calls fail without the venv.

How does Smart Add work?

Query the notebook about its content first, then add it with discovered name, description, and topics instead of guessing metadata.

What is the follow-up rule?

After each answer, analyze gaps and ask follow-up questions via ask_question.py until the user's request is fully covered.

Is Notebooklm safe to install?

skills.sh reports 1 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

AI & Agent Buildingresearchautomation

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.