agentleFS
AtmoskunAtmoskun/claude-skills/skills/notebooklm/SKILL.md

notebooklm

Skill0 starsChanged 9 months agoMITView on GitHub

Query Google NotebookLM for source-grounded, citation-backed answers. Manage sources, generate audio/reports/quizzes. Pure API via notebooklm-py SDK — no browser automation.

72 other projects use a version of this, 23 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use django-verification, django-security and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • mstuder-slalomSkill

    django-verification

    Verification loop for Django projects: migrations, linting, tests with coverage, security scans, and deployment readiness checks before release or PR.

    Also in 3 projects that use this

  • mstuder-slalomSkill

    django-security

    Django security best practices, authentication, authorization, CSRF protection, SQL injection prevention, XSS prevention, and secure deployment configurations.

    Also in 3 projects that use this

  • sirakinbSkill

    last30days

    Research a topic from the last 30 days on Reddit + X + Web, become an expert, and write copy-paste-ready prompts for the user's target tool.

    Also in 4 projects that use this

  • younghaiSkill

    google-calendar

    Google Calendar 일정 조회, 검색, 등록. "일정", "스케줄", "캘린더" 등을 언급하면 자동 실행. Daily Note 작성, Weekly Review에 사용.

    Also in 3 projects that use this

  • royaluniondesign-sysSkill

    deployment-patterns

    Deployment workflows, CI/CD pipeline patterns, Docker containerization, health checks, rollback strategies, and production readiness checklists for web applications.

    Also in 3 projects that use this

  • LuisSambranoSkill

    firecrawl

    Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 69 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If auth errors occur later, just run notebooklm login again.

    line 47
  2. Distinctive:

    When user wants to add a notebook without providing details:

    line 171
  3. Distinctive:

    NEVER guess or use generic descriptions!

    line 181
  4. Distinctive:

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

    line 185
  5. Very specific:

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

    line 222
  6. Distinctive:

    After any ingestion skill adds new content (substack, podcast, earnings transcript, meeting transcript), suggest:

    line 277

“Common” is measured: kept by at least 6 in 10 of the 69 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

NotebookLM Research Assistant Skill

Query Google NotebookLM notebooks for source-grounded answers from Gemini. Manage sources programmatically. Generate audio overviews, reports, quizzes, flashcards, and more. All via the notebooklm-py SDK — pure API calls, no browser automation.

When to Use This Skill

Trigger when user:

  • Mentions NotebookLM explicitly
  • Shares a NotebookLM URL (https://notebooklm.google.com/notebook/...)
  • Asks to query their notebooks/documentation
  • Wants to add sources (URLs, files, text) to a notebook
  • Wants to generate audio, reports, quizzes from notebook content
  • Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"

Critical: Always Use run.py Wrapper

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

# Correct:
python scripts/run.py ask_question.py --question "..."
python scripts/run.py notebook_manager.py list

# Wrong (will fail without venv):
python scripts/ask_question.py --question "..."

The run.py wrapper automatically creates .venv, installs dependencies, and runs the script in the correct environment.

Authentication

One-time setup — the SDK handles everything:

# Run this in the skill's venv:
cd ~/.claude/skills/notebooklm && .venv/bin/notebooklm login
# (Windows: .venv\Scripts\notebooklm login)

This opens a browser for Google login and saves credentials to ~/.notebooklm/. No further auth steps needed.

If auth errors occur later, just run notebooklm login again.

Core Workflow

1. Check Notebook Library

python scripts/run.py notebook_manager.py list

2. Ask a Question (with citations)

# Using library ID (preferred):
python scripts/run.py ask_question.py --question "What is the main thesis?" --notebook-id my-notebook

# Using active notebook:
python scripts/run.py ask_question.py --question "What is the main thesis?"

# Direct URL:
python scripts/run.py ask_question.py --question "..." --notebook-url "https://notebooklm.google.com/notebook/UUID"

# Multi-turn follow-up (reuse conversation):
python scripts/run.py ask_question.py --question "Elaborate on point 2" --notebook-id my-notebook --conversation-id "CONV_ID"

# Restrict to specific sources:
python scripts/run.py ask_question.py --question "..." --notebook-id my-notebook --source-ids "SRC_ID1,SRC_ID2"

Output includes:

  • The answer text
  • Citations with source references and quoted passages
  • conversation_id for follow-up questions

3. Manage Notebook Library

# Add notebook (all params required):
python scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/UUID" \
  --name "PM Earnings 2025" \
  --description "Philip Morris earnings calls and conferences" \
  --topics "PM,earnings,ZYN,IQOS"

# Sync from Google (auto-discover all notebooks):
python scripts/run.py notebook_manager.py sync

# Show notebook details + live source list:
python scripts/run.py notebook_manager.py info --id my-notebook

# Other commands:
python scripts/run.py notebook_manager.py list
python scripts/run.py notebook_manager.py search --query "earnings"
python scripts/run.py notebook_manager.py activate --id my-notebook
python scripts/run.py notebook_manager.py remove --id my-notebook
python scripts/run.py notebook_manager.py stats

4. Manage Sources

# List sources in a notebook:
python scripts/run.py source_manager.py --notebook-id my-notebook list

# Add URL source:
python scripts/run.py source_manager.py --notebook-id my-notebook add-url --url "https://example.com/article" --wait

# Add file (PDF, DOCX, etc.):
python scripts/run.py source_manager.py --notebook-id my-notebook add-file --file "/path/to/document.pdf" --wait

# Add pasted text:
python scripts/run.py source_manager.py --notebook-id my-notebook add-text --title "My Notes" --content "Text content here..." --wait

# Get full indexed text of a source:
python scripts/run.py source_manager.py --notebook-id my-notebook fulltext --source-id SOURCE_ID

# Delete a source:
python scripts/run.py source_manager.py --notebook-id my-notebook delete --source-id SOURCE_ID

5. Generate Artifacts

# Audio overview (podcast-style):
python scripts/run.py generate.py --notebook-id my-notebook audio --format deep_dive --length default
python scripts/run.py generate.py --notebook-id my-notebook audio --format brief --instructions "Focus on ZYN growth"

# Reports:
python scripts/run.py generate.py --notebook-id my-notebook report --format briefing
python scripts/run.py generate.py --notebook-id my-notebook report --format study_guide
python scripts/run.py generate.py --notebook-id my-notebook report --format blog_post
python scripts/run.py generate.py --notebook-id my-notebook report --format custom --prompt "Compare ZYN vs IQOS margins"

# Quiz and flashcards:
python scripts/run.py generate.py --notebook-id my-notebook quiz --difficulty medium --output-format markdown
python scripts/run.py generate.py --notebook-id my-notebook flashcards --difficulty hard --output-format json

# Mind map (instant, no polling):
python scripts/run.py generate.py --notebook-id my-notebook mind-map

# Infographic:
python scripts/run.py generate.py --notebook-id my-notebook infographic --orientation landscape --detail detailed

# Slide deck:
python scripts/run.py generate.py --notebook-id my-notebook slide-deck --format detailed

# Data table:
python scripts/run.py generate.py --notebook-id my-notebook data-table --instructions "Extract all financial metrics"

# Check status / list existing artifacts:
python scripts/run.py generate.py --notebook-id my-notebook status --task-id TASK_ID
python scripts/run.py generate.py --notebook-id my-notebook list --type audio

Generated files are saved to data/output/{type}/.

6. Q&A History

python scripts/run.py history_manager.py list --limit 10
python scripts/run.py history_manager.py search --query "ZYN"
python scripts/run.py history_manager.py stats

History is auto-saved to:

  • data/history.json — structured JSON for search
  • ~/Documents/Obsidian Vault/导航/NotebookLM/{notebook_name}.md — human-readable Obsidian log

Smart Add (Recommended for New Notebooks)

When user wants to add a notebook without providing details:

# 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]"

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

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 another question (include --conversation-id for multi-turn context)
  5. REPEAT — Continue until information is complete
  6. SYNTHESIZE — Combine all answers before responding to user

Decision Flow

User mentions NotebookLM
    |
    v
Check library --> python scripts/run.py notebook_manager.py list
    |
    v
If no notebooks --> sync: python scripts/run.py notebook_manager.py sync
                    or add: python scripts/run.py notebook_manager.py add ...
    |
    v
Activate notebook --> python scripts/run.py notebook_manager.py activate --id ID
    |
    v
Ask question --> python scripts/run.py ask_question.py --question "..."
    |
    v
See "Is that ALL you need?" --> Ask follow-ups until complete
    |
    v
Synthesize and respond to user

Data Storage

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

  • library.json — Local notebook metadata (descriptions, topics, use counts)
  • history.json — Q&A history
  • output/ — Generated artifacts (audio, reports, quizzes, etc.)

SDK auth stored at ~/.notebooklm/storage_state.json (managed by SDK).

Troubleshooting

ProblemSolution
ModuleNotFoundErrorUse run.py wrapper, not direct script calls
Authentication errorRun notebooklm login in the skill's venv
Rate limitWait a few minutes, or switch Google account
Source still processingUse --wait flag, or check back in ~30 seconds
Notebook not foundCheck with notebook_manager.py list or sync
Empty citationsNot all queries produce citations; rephrase for specificity

Auto-Source Sync

Automatically discover and sync new ticker-related files to the right notebook. Uses shared/notebooklm_sync.py.

Register a Ticker → Notebook Mapping

cd ~/.claude/skills && python shared/notebooklm_sync.py register PM --notebook-id pm-philip-morris-2025-transcripts

This auto-discovers scan locations:

  • 研究/财报分析/{TICKER}*/ — analysis .md files
  • 研究/研究笔记/ — files matching ticker in name/frontmatter
  • 研究/供应链/{TICKER}_mentions.md
  • PORTFOLIO/research/companies/{TICKER}/ — thesis, notes
  • Earnings Transcripts/ — PDF transcripts
  • Custom paths via --scan-path

Sync Commands

cd ~/.claude/skills
python shared/notebooklm_sync.py status              # Show all registered tickers
python shared/notebooklm_sync.py scan PM              # Preview what would be synced
python shared/notebooklm_sync.py sync PM              # Add new sources to notebook
python shared/notebooklm_sync.py sync PM --dry-run    # Preview only
python shared/notebooklm_sync.py sync-all             # Sync all registered tickers
python shared/notebooklm_sync.py sync-all --dry-run   # Preview all

How It Works

  1. Scans configured directories for new files related to a ticker
  2. Compares against previously synced sources (tracked in shared/data/notebooklm_sync.json)
  3. Adds new files via source_manager.py add-file --wait
  4. Rate-limits at 3s between adds to avoid NLM API throttling
  5. Warns if approaching 50-source-per-notebook limit

Integration with Ingestion Skills

After any ingestion skill adds new content (substack, podcast, earnings transcript, meeting transcript), suggest:

"New files available for NLM sync. Run `python shared/notebooklm_sync.py sync-all` to update notebooks?"

Script Reference

ScriptPurpose
run.pyVenv wrapper — always use this
ask_question.pyChat with citations, multi-turn support
notebook_manager.pyLibrary management + Google sync
source_manager.pyAdd/list/delete sources (URLs, files, text)
generate.pyAudio, reports, quizzes, flashcards, mind maps, infographics, slides, data tables
history_manager.pyQ&A history search/list + Obsidian output
thesis_challenger.pyDevil's advocate thesis analysis

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.