NotebookLM Research Assistant Skill

Description

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

Security Status