Agent skill

NotebookLM Research Assistant

by PleasePrompto in PleasePrompto/notebooklm-skill

Lets Claude Code ask questions of your Google NotebookLM notebooks through browser automation and return answers grounded in your uploaded sources.

MITAuto-check: notesKnowledge Management

Install NotebookLM Research Assistant

skills CLI
$ npx skills add PleasePrompto/notebooklm-skill --skill notebooklm -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install PleasePrompto/notebooklm-skill notebooklm --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
notebooklm
GitHub stars
7.8k
Used in
14 other repos
Token cost
~2.4k tokens
SKILL.md length
563 words
Files
21 (incl. scripts, references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Lets Claude Code ask questions of your Google NotebookLM notebooks through browser automation and return answers grounded in your uploaded sources.

  • Works in 4 steps: Check Authentication Status → Authenticate (One-Time Setup) → Manage Notebook Library → …
  • Asking questions about documentation you keep in NotebookLM
  • SKILL.md covers When to Use This Skill, ⚠️ CRITICAL: Add Command -…, Critical: Always Use run.py… and Core Workflow, plus 10 more sections
  • Runs Python scripts from its folder; calls python and pip; reaches notebooklm.google.com

What it does

This skill connects the agent to NotebookLM. Each question opens a fresh browser session, asks the chosen notebook, collects Gemini's answer drawn only from the documents you uploaded there, and closes again. A local library keeps track of your notebooks; when you add one without details, the skill first asks the notebook to describe its own contents instead of making up a description.

Everything runs through a wrapper, scripts/run.py, which creates a virtual environment and installs dependencies on first use. Authentication is a one-time manual Google login in a visible browser window, after which the session persists. Reference files cover the API, usage patterns and troubleshooting.

When your agent uses it

  • Asking questions about documentation you keep in NotebookLM
  • Getting cited answers limited to your own sources
  • Adding a NotebookLM notebook to the agent's library

Example prompts

  • “Ask my onboarding notebook how we rotate API keys.”
  • “Add this NotebookLM link to my library and figure out what it covers.”
  • “Check my product-docs notebook for the refund policy wording.”

Requirements

  • Python
  • A Google account with NotebookLM notebooks
  • A visible browser for the first login

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Check Authentication Status
  2. Authenticate (One-Time Setup)
  3. Manage Notebook Library
  4. Ask Questions

What it can do on your machine

Read from SKILL.md and the folder at commit c80722d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 7 files in scripts/ (Python, from the files we listed), which the agent can run.

    Shell commands in SKILL.md call:

    • python
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • notebooklm.google.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

NotebookLM Research Assistant loads about 2.4k tokens when it runs, and up to ~8.9k if it reads all its reference files. Until then it costs about 69 tokens; SKILL.md has 563 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~69
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~8.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:202
    Optional `.env` file in skill directory:

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from PleasePrompto/notebooklm-skill at commit c80722d, republished under its MIT licence (© PleasePrompto). 563 words, ~2,352 tokens.

Download SKILL.mdSave it as .claude/skills/notebooklm/SKILL.md (or your agent's skills folder). This skill also uses 20 other files; get the full folder from GitHub.
name
notebooklm
description
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.

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:

bash
# 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]:

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:

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

  • 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
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
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
bash
# 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:
    bash
    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)
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
Show full SKILL.md (238 more words)Show less

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

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

© PleasePrompto, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 20 other files (scripts, references) in the repository root of PleasePrompto/notebooklm-skill.

  • SKILL.md
  • .gitignore
  • AUTHENTICATION.md
  • CHANGELOG.md
  • LICENSE
  • README.md
  • images/example_notebookchat.png
  • references/api_reference.md
  • references/troubleshooting.md
  • references/usage_patterns.md
  • requirements.txt
  • scripts/__init__.py
  • scripts/ask_question.py
  • scripts/auth_manager.py
  • scripts/browser_session.py
  • scripts/browser_utils.py
  • scripts/cleanup_manager.py
  • scripts/config.py
  • … and 3 more

Open the folder on GitHubat commit c80722d

Used in 14 other repositories

We found 17 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 14 other GitHub owners. This page covers the copy in PleasePrompto/notebooklm-skill, which our catalogue first saw on October 7, 2026.

Compare with similar skills

NotebookLM Research Assistant next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

NotebookLM Research Assistant compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
NotebookLM Research Assistant this skillPleasePrompto/notebooklm-skill7.8k14 repos~2.4kAutomated safety check: NotesMIT
NotebookLM Automationteng-lin/notebooklm-py20k—~4.1kAutomated safety check: PassMIT
NblmLeoYeAI/openclaw-master-skills2.2k—~5.9kAutomated safety check: NotesMIT
Cninfo To Notebooklmjarodise/CNinfo2Notebookllm363—~1.1kAutomated safety check: PassNone
Notebooklmroomi-fields/notebooklm-mcp189—~1.1kAutomated safety check: PassMIT
Notebooklmsanjay3290/ai-skills431—~655Automated safety check: PassApache-2.0

Similar skills

  • NotebookLM Automation

    teng-lin/notebooklm-py

    Installs, authenticates and operates Gemini Notebook (NotebookLM) through the notebooklm-py CLI or its typed async Python API, for notebooks, sources, grounded chat and generated artifacts.

    20k GitHub stars~4.1k tokensUpdated yesterday
    Knowledge ManagementAuto-check passed
  • Nblm

    LeoYeAI/openclaw-master-skills

    A skill your agent uses to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini.

    2.2k GitHub stars~5.9k tokensUpdated 2 mo ago
    Knowledge ManagementAuto-check: notes
  • Cninfo To Notebooklm

    jarodise/CNinfo2Notebookllm

    A skill your agent uses when user wants to analyze China stock reports (A-share or Hong Kong), upload annual/quarterly reports to NotebookLM, or research a Chinese listed company's financials

    363 GitHub stars~1.1k tokensUpdated 3 mo ago
    Knowledge ManagementAuto-check passed
  • Notebooklm

    roomi-fields/notebooklm-mcp

    This skill should be used when the user wants to query their Google NotebookLM notebooks for citation-backed, source-grounded answers, or manage notebooks, sources, and Studio content (audio…

    189 GitHub stars~1.1k tokensUpdated 1 mo ago
    Knowledge ManagementAuto-check passed
  • Notebooklm

    sanjay3290/ai-skills

    Query and manage Google NotebookLM notebooks with persistent profile auth, source sync, batch/multi queries, and structured exports.

    431 GitHub stars~655 tokensUpdated 27 days ago
    Knowledge ManagementAuto-check passed
  • Notebooklm

    alirezarezvani/claude-skills

    Browser automation skill for controlling Google's NotebookLM.

    28k GitHub stars~4k tokensUpdated 1 mo ago
    Knowledge ManagementAuto-check passed

Questions about NotebookLM Research Assistant

What does NotebookLM Research Assistant do?

Lets Claude Code ask questions of your Google NotebookLM notebooks through browser automation and return answers grounded in your uploaded sources. This skill connects the agent to NotebookLM. Each question opens a fresh browser session, asks the chosen notebook, collects Gemini's answer drawn only from the documents you uploaded there, and closes again.

When should I use NotebookLM Research Assistant?

NotebookLM Research Assistant fits situations like: asking questions about documentation you keep in NotebookLM; getting cited answers limited to your own sources; adding a NotebookLM notebook to the agent's library.

How do I install NotebookLM Research Assistant in Claude Code?

Run `npx skills add PleasePrompto/notebooklm-skill --skill notebooklm -a claude-code`. Or copy the skill folder (the PleasePrompto/notebooklm-skill repository) into .claude/skills/notebooklm in your project. Claude Code loads it when a task matches its description.

How do I install NotebookLM Research Assistant in Codex?

Run `npx skills add PleasePrompto/notebooklm-skill --skill notebooklm -a codex`. Or copy the skill folder (the PleasePrompto/notebooklm-skill repository) into .agents/skills/notebooklm in your project. Codex loads it when a task matches its description.

Can I use NotebookLM Research Assistant in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add PleasePrompto/notebooklm-skill --skill notebooklm -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/notebooklm, .gemini/skills/notebooklm, .github/skills/notebooklm and .opencode/skills/notebooklm in your project.

What does NotebookLM Research Assistant need to run?

Going by SKILL.md and its folder, NotebookLM Research Assistant needs Python for the scripts in its folder and the command-line tools its instructions call (python and pip). Our summary lists: Python; A Google account with NotebookLM notebooks; A visible browser for the first login.

Does NotebookLM Research Assistant access the network?

SKILL.md names 1 domain. In commands or code: notebooklm.google.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is NotebookLM Research Assistant safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does NotebookLM Research Assistant use?

NotebookLM Research Assistant is published under the MIT licence (from the LICENSE file in the skill folder). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does NotebookLM Research Assistant use?

About 2.4k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 6.5k tokens, read only when the agent opens those files.

What are the alternatives to NotebookLM Research Assistant?

Skills that share tags, products or a category with NotebookLM Research Assistant: NotebookLM Automation (teng-lin/notebooklm-py, 20k stars), Nblm (LeoYeAI/openclaw-master-skills, 2.2k stars), Cninfo To Notebooklm (jarodise/CNinfo2Notebookllm, 363 stars) and Notebooklm (roomi-fields/notebooklm-mcp, 189 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains NotebookLM Research Assistant?

PleasePrompto (a GitHub user) maintains it in PleasePrompto/notebooklm-skill, which has 7,782 GitHub stars. The repository was last updated on September 10, 2026.

Source: PleasePrompto/notebooklm-skill on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.