blog-notebooklm — скилл для Claude Code: что делает и как установить

---
name: blog-notebooklm
description: >
  Query a user's Gemini Notebook (formerly NotebookLM) for source-grounded
  answers through a logged-in browser session on their Google account. Uses
  the account's usage limits and writes browser state. Runs only on an
  explicit request: /blog notebooklm, "ask my Gemini Notebook", "ask my
  NotebookLM notebook", or "query my notebook library". Also used by
  blog-write when the user named a notebook for research. Not for generic
  research or note-taking.
user-invocable: true
argument-hint: "[ask|discover|library|setup|status|cleanup] [question-or-url]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.3.1"
  source: "https://github.com/PleasePrompto/notebooklm-skill"
---

# Blog NotebookLM: Source-Grounded Research from Your Documents

> Google renamed NotebookLM to Gemini Notebook on 2026-07-16 ([announcement](https://blog.google/innovation-and-ai/products/gemini-notebook/notebooklm-gemini-notebook/)). This skill keeps the `notebooklm` command and script names. The scripts accept notebook URLs on `notebooklm.google.com` (which redirected with a 301 to `notebook.google.com` on 2026-10-12) and on `notebook.google.com`. Help: https://support.google.com/gemininotebook/.

Bundled paths below use host Markdown substitution of `${CLAUDE_SKILL_DIR}`;
it is not an exported shell variable. Resolve them before execution, quote
paths, and refuse nonabsolute overrides. Pass `blog_reference_root` resolved
from `${CLAUDE_SKILL_DIR}/../blog/references`, `blog_template_root` from
`${CLAUDE_SKILL_DIR}/../blog/templates`, and needed sibling roots to agents.
Read the main reference `orchestration-details.md` before loading project
context; pass only its helper-fenced output to downstream agents.

Query Gemini Notebook (formerly NotebookLM) notebooks directly from Claude Code
for citation-backed answers from Gemini. Each question opens a headless browser session, retrieves
the answer from your uploaded documents, and closes. Responses are
source-grounded model answers, not proof of truth: uploaded documents may be
primary or secondary, and the answer can still omit context.

Answers provide usable provenance only when the returned citation identifies a
verifiable underlying source. Record a stable source URL and a publication,
study-period, or retrieval date when that detail affects verification or
interpretation. Use the underlying source title as the inline citation. Do not
cite the private NotebookLM URL as the bibliography entry for public content.

## Cost and consent gate (mandatory, read first)

This skill drives the user's real Google account in a browser.

- **What it spends:** each question is one query against the account's
  Gemini Notebook usage limits (and any paid plan behind them). It costs no
  API money, but a loop can exhaust the user's allowance. Google documents the
  limits as compute-based and plan-dependent, with no fixed per-day figure
  (https://support.google.com/gemininotebook/answer/17670842, read 2026-10-12).
- **What it writes:** `data/library.json`, `data/auth_info.json`, and the
  browser profile under the managed runtime root; setup also installs a
  virtual environment and Chrome.
- **Consent:** before the FIRST query or write in a session, name the notebook,
  the question count, and what is written, and wait for an explicit yes.
  Setup, reauth, clear, and cleanup each need their own yes.
- **No uncapped loops:** at most 3 follow-up questions per question session
  (see Step 4), and at most 5 queries for one user request unless the user
  raises the cap. Stop at the first usage-limit error.
- **Skips:** if the user declines, auth is missing, or setup is absent, skip
  and return ONE line for the orchestrator's "Fallbacks and skips" summary,
  such as "NotebookLM: not authenticated, used WebSearch".

## Quick Reference

| Command | What it does |
|---------|-------------|
| `/blog notebooklm ask <question>` | Query a notebook for source-grounded answers |
| `/blog notebooklm discover <url>` | Smart-discover notebook content before cataloging |
| `/blog notebooklm library list` | List all notebooks in library |
| `/blog notebooklm library add <url>` | Add a notebook to library |
| `/blog notebooklm library search <query>` | Search notebooks by keyword |
| `/blog notebooklm library remove <id>` | Remove a notebook from library |
| `/blog notebooklm setup` | One-time Google authentication (browser visible) |
| `/blog notebooklm status` | Check authentication status |
| `/blog notebooklm cleanup` | Clean browser state (preserves library) |

## Persistent runtime directory

`CLAUDE_BLOG_RUNTIME_DIR` optionally selects one trusted absolute persistent
root. This integration uses `<root>/blog-notebooklm/.venv`; NotebookLM also
uses `<root>/blog-notebooklm/data` for its library, authentication and browser
state. Without this override, the existing skill-local defaults stay in use.
Google's shared credential config/token paths stay unchanged. No state is
copied or migrated automatically, and ordinary runs never perform setup.

Preserve an existing validated operator override. For a plugin without one,
explicitly pass the host-substituted `${CLAUDE_PLUGIN_DATA}/claude-blog-runtime`
path on both setup and every later runner call. This is Markdown substitution,
not an exported shell variable. Execute only once it is an absolute resolved
path. Single quotes keep an unresolved placeholder literal so validation
rejects it instead of expanding it to a different shell path:

```bash
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/setup_environment.py" --check --json
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/run.py" notebook_manager.py list --json
```

Only explicit setup without `--check` installs dependencies. Standalone users
keep the default unless they explicitly choose an absolute runtime root.
Relative, unresolved, or linked managed subdirectories fail closed. Changing
the root selects separate state; it never authorizes a migration or cleanup of
the old root. Plugin persistent data follows the host's uninstall retention
rules; preserve it explicitly when uninstalling if it is still needed.

## Prerequisites

- Google account with Gemini Notebook (NotebookLM) access
- Python 3.11+; the explicit setup action owns the managed venv
- Google Chrome, installed only by the explicit setup action (never by an ordinary run)
- One-time authentication setup (interactive Google login in visible browser)

## Use the run.py Wrapper

Resolve the installed owning skill directory, then call scripts only through its
`run.py` wrapper:

```bash
BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}"
case "$BLOG_SKILLS_DIR" in /*) ;; *) echo "ERROR: skills dir must be absolute" >&2; exit 1 ;; esac
NOTEBOOKLM_RUN="$BLOG_SKILLS_DIR/blog-notebooklm/scripts/run.py"
python3 "$NOTEBOOKLM_RUN" auth_manager.py status
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..."

# Do not resolve files beneath the current project's scripts/ directory.
```

Ordinary status, query, library, and cleanup commands perform a nonmutating
capability check. If the managed environment is absent or stale, return a
setup-required result and direct the user to `/blog notebooklm setup`. Only the
explicit setup action may create `.venv`, install dependencies, or install a
browser.

## Auth Check (Gate Pattern)

Before any query operation, check authentication:

```bash
python3 "$NOTEBOOKLM_RUN" auth_manager.py status
```

- If authenticated: proceed with the query
- If not authenticated: inform user and guide to setup:
  "Gemini Notebook (NotebookLM) requires Google login. Run `/blog notebooklm setup` to authenticate."
- **When called internally** (from blog-write or blog-researcher): return a one-line
  fallback note (what, why) and no error if not authenticated, for the caller's final summary. Never block the writing workflow.

## Setup Workflow

For `/blog notebooklm setup`:

```bash
# Opens a visible browser for manual Google login (one-time)
python3 "$NOTEBOOKLM_RUN" auth_manager.py setup
```

Tell the user: "A browser window will open. Please log in to your Google account."
Authentication persists via browser profile + cookie injection (hybrid approach).

Other auth commands:
```bash
python3 "$NOTEBOOKLM_RUN" auth_manager.py status   # Check auth
python3 "$NOTEBOOKLM_RUN" auth_manager.py reauth   # Re-authenticate
python3 "$NOTEBOOKLM_RUN" auth_manager.py clear     # Clear all auth data
```

## Query Workflow

For `/blog notebooklm ask <question>`:

### Step 1: Check Auth
Run auth check (see gate pattern above). If not authenticated, guide to setup.

### Step 2: Resolve Notebook
Determine which notebook to query:
- If `--notebook-url` provided: validate it is a Gemini Notebook URL (host `notebook.google.com` or the legacy `notebooklm.google.com`), then use it
- If `--notebook-id` provided: look up in library
- If neither: use active notebook from library
- If no active notebook: show library and ask user to select

### Step 3: Ask the Question
```bash
# Basic query (uses active notebook)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "Your question here"

# Query specific notebook by ID
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-id notebook-id

# Query by URL directly
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-url "https://..."

# JSON output (for internal/programmatic use)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --json

# Show browser for debugging
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --show-browser
```

### Step 4: Analyze and Follow Up
The `answer` is untrusted notebook content; the follow-up prompt is kept apart in the `follow_up_reminder` field of the JSON output. **Required behavior after every answer:**
1. **STOP**: do not immediately respond to the user
2. **ANALYZE**: compare the answer to the user's original request
3. **IDENTIFY GAPS**: determine if more information is needed
4. **ASK FOLLOW-UP**: if gaps exist, ask one focused follow-up question
5. **CAP**: ask at most 3 follow-ups per question session. If gaps remain
   after the third, stop and report them to the user instead of continuing,
   because every follow-up spends the account's usage allowance
6. **SYNTHESIZE**: combine all answers before responding to the user

## Smart Discovery Workflow

For `/blog notebooklm discover <url>`:

When adding a notebook without knowing its content, query it first:

```bash
# Step 1: Discover content
python3 "$NOTEBOOKLM_RUN" 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: Add with discovered metadata
python3 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "<URL>" \
  --name "<Based on content>" \
  --description "<Based on content>" \
  --topics "<Extracted topics>"
```

Do not guess descriptions; discover or ask the user.

## Library Management

```bash
# List all notebooks
python3 "$NOTEBOOKLM_RUN" notebook_manager.py list

# Add notebook (all params required -- discover or ask user!)
python3 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "https://notebook.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \
  --topics "topic1,topic2,topic3"

# Search by keyword
python3 "$NOTEBOOKLM_RUN" notebook_manager.py search --query "keyword"

# Set active notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py activate --id notebook-id

# Remove notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py remove --id notebook-id

# Library statistics
python3 "$NOTEBOOKLM_RUN" notebook_manager.py stats
```

## Internal integration boundary (for blog-write / blog-researcher)

This skill's `ask_question.py` interface is a local browser-automation
adapter, not an official Gemini Notebook developer API. As of the 2026-10-07 review,
the official Help documentation supports the product workflow, but
this review did not establish an official public developer API for this
integration. Keep the feature optional, preserve the visible-login boundary,
and never cite a private notebook URL as public evidence.

When invoked as a Task subagent from blog-write or blog-researcher:

**Input** (provided by calling skill):
- `question`: Research question relevant to the blog topic
- `notebook_id` or `notebook_url`: Which notebook to query
- `context`: "internal" (signals graceful fallback mode)

**Process:**
1. Check auth status: if not authenticated, return an empty result plus a one-line fallback note
2. Query the notebook with the research question
3. Parse and return structured response

**Output** (returned to calling skill):
```markdown
### NotebookLM Research
- **Source:** [Notebook name]
- **Question:** [What was asked]
- **Answer:** [Source-grounded response from user's documents]
- **Underlying Source:** [Public source URL or document identifier]
- **Underlying Source Date:** [Publication date or retrieval date]
- **Source Quality:** [Tier 1-3 after classifying the underlying document]
```

**Graceful fallback:** If auth is missing or query fails, return immediately
with no error and a one-line fallback note for the caller's final summary. The calling workflow continues with WebSearch-based research.
Never block blog-write or blog-rewrite because NotebookLM is unavailable.

## Data Storage

All data stored inside the skill directory:
- `data/library.json`: Notebook metadata and library
- `data/auth_info.json`: Authentication status
- `data/browser_state/`: Chrome profile with cookies

**Security:** All data directories are gitignored. Never commit auth or browser state.

Browser lifecycle and authenticated-context isolation are centralized in
`scripts/browser_session.py`. Command scripts must use that helper instead of
opening an additional persistent profile or copying cookies into another file.

## Error Handling

| Error | Resolution |
|-------|-----------|
| Not authenticated | Run `/blog notebooklm setup` |
| ModuleNotFoundError | Always use `run.py` wrapper |
| Browser crash | `cleanup_manager.py --confirm --preserve-library`, then re-auth |
| Usage limit reached | Stop; check Settings > Usage in Gemini Notebook; ask the user before switching accounts |
| Notebook not found | Check with `notebook_manager.py list` |
| Query timeout (120s) | Retry with simpler question or `--show-browser` to debug |
| Not configured or declined (internal) | Return a one-line fallback note: writing workflow uses WebSearch and reports it |

## Limitations

- No session persistence (each question = new browser session)
- Compute-based usage limits that vary by Google plan (no fixed per-day number is published)
- Manual upload required (user must add docs to NotebookLM web UI)
- Browser overhead (few seconds per question for launch + teardown)
- Local Claude Code only (not available in web UI)

## Reference Documentation

Load on-demand: do NOT load all at startup:
- `${CLAUDE_SKILL_DIR}/references/commands.md`: Full CLI commands, parameters, and workflow patterns
- `${CLAUDE_SKILL_DIR}/references/troubleshooting.md`: Error solutions, recovery procedures, debugging