Agent skill

notebooklm

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. Zero hallucinations, just your knowledge base.

View SKILL.md on GitHub Repository

Stars 9

Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/delorenj/skills/tree/main/notebooklm

SKILL.md

NotebookLM Research Assistant Skill

Interact with Google NotebookLM to query documentation with Gemini's zero-hallucination answers. Each question opens a fresh browser session, retrieves the answer, 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 Requirements

When adding a notebook, these parameters are ALL REQUIRED:

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

If you don't know what's in the notebook, ASK THE USER FIRST:

"What does this notebook contain and what topics does it cover?"
"Please describe what's in this notebook so I can add it to the library."

NEVER guess or use generic descriptions like "notebook" or "documentation"!

Critical: Always Use run.py Wrapper

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

bash

# ✅ 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

bash

python scripts/run.py auth_manager.py status

If not authenticated, proceed to setup.

Step 2: Authenticate (One-Time Setup)

bash

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

Important:

NEVER use --headless 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

bash

# 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

Step 4: Ask Questions

bash

# Basic query
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:

bash

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`)

bash

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`)

bash

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`)

bash

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

Data Cleanup (`cleanup_manager.py`)

bash

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):

bash

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:

env

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, no `--headless`
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

scripts/ - All automation scripts
data/ - Local storage (auth, notebooks)
references/ - Extended documentation
.venv/ - Isolated Python environment
.gitignore - Protects sensitive data

Based on notebooklm-mcp adapted for local execution.

Maintainer

delorenj Core maintainer

Source details

Full Name: delorenj/skills
Branch: main
Path in repo: notebooklm

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

delorenj/skills

openclaw-upgrade

Upgrade OpenClaw installations to the latest version. Handles global npm installs, local development setups, release channels (stable/beta/dev), configuration preservation, and platform-specific requirements. Use when updating OpenClaw, switching release channels, or troubleshooting update issues.

9 0

Explore

delorenj/skills

vercel-composition-patterns

React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.

9 0

Explore

delorenj/skills

security-monitor

Real-time security monitoring for Clawdbot. Detects intrusions, unusual API calls, credential usage patterns, and alerts on breaches.

9 0

Explore

delorenj/skills

event-driven-architecture

Kafka, RabbitMQ, SQS/SNS, event sourcing, CQRS, saga patterns, dead letter queues, and idempotency. Use when designing asynchronous systems, implementing message-driven workflows, or building event streaming pipelines.

9 0

Explore

delorenj/skills

shadcn-ui

Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.

9 0

Explore

delorenj/skills

just-fucking-cancel

Find and cancel unwanted subscriptions by analyzing bank transactions. Detects recurring charges, calculates annual waste, and helps you cancel with direct URLs and browser automation. Use when: 'cancel subscriptions', 'audit subscriptions', 'find recurring charges', 'what am I paying for', 'save money', 'subscription cleanup', 'stop wasting money'. Supports CSV import (Apple Card, Chase, Amex, Citi, Bank of America, Capital One, Mint, Copilot) OR Plaid API for automatic transaction pull. Outputs interactive HTML audit with one-click cancel workflow. Pairs with Plaid integration for real-time transaction access without CSV exports.

9 0

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

NotebookLM Research Assistant Skill

When to Use This Skill

⚠️ CRITICAL: Add Command Requirements

Critical: Always Use run.py Wrapper

Core Workflow

Step 1: Check Authentication Status

Step 2: Authenticate (One-Time Setup)

Step 3: Manage Notebook Library

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

Recommended Agent Skills

openclaw-upgrade

vercel-composition-patterns

security-monitor

event-driven-architecture

shadcn-ui

just-fucking-cancel

Authentication Management (`auth_manager.py`)

Notebook Management (`notebook_manager.py`)

Question Interface (`ask_question.py`)

Data Cleanup (`cleanup_manager.py`)