<!-- Line count target: keep SKILL.md body under 400 lines (hard limit: 500). --> <!-- Run: wc -l SKILL.md to check. Move overflow sections to references/ with links below. -->

NotebookLM

Orchestrates NotebookLM workflows over the notebooklm-mcp MCP server. Two modes: high-level workflow recipes (## Research, ## Artifacts, etc.) and direct MCP tool calls (## Tool Index in Phase 34+). Requires notebooklm-mcp server running and authenticated — see references/setup.md for installation.

Auth

When any MCP tool returns an error containing "authentication", "cookies", "expired", or "401":

1. Stop immediately — do not retry the tool call
2. Tell user: "NotebookLM session expired (~20 min sessions). Attempting token refresh..."
3. Call refresh_auth (MCP tool — no parameters)
4. If refresh_auth succeeds: retry the original tool call from the beginning of the failed step
5. If refresh_auth fails or is unavailable: tell user "Run: nlm login in your terminal, then tell me when done"
6. After user confirms login: call refresh_auth again, then retry

To proactively check auth before a long workflow: nlm auth status via Bash tool (non-destructive). Auth sessions last approximately 20 minutes from last activity.

Compatibility

All tool names in this skill use unprefixed logical names (e.g., notebook_create).

• Claude Code prefix: mcp__notebooklm-mcp__ | Cowork prefix: mcp__notebooklm__
• Claude resolves the correct prefix from available tools at runtime — no changes needed when switching environments.
• Note: server must be registered in MCP config. See references/setup.md for installation.

Long-Running Operations

When calling studio_create, research_start, or any operation that returns a task/artifact ID and runs in background:

1. Kick off the operation
2. Check status ONCE after ~15 seconds
3. If complete: proceed with result
4. If still running: tell user "This usually takes 3-10 minutes. I'll note it and we can check back later."
5. Save a reminder to session memory: "Check NotebookLM [operation] — started at [time]"
6. Move on to next task or ask user what else they need

Do NOT poll more than once. The single check catches fast completions; everything else finishes in background.

To check later: user can say "check my NotebookLM operation" and you call the relevant status tool.

Query Rules

Sequential execution — CRITICAL:

1. NEVER run multiple NotebookLM queries in parallel. Execute one at a time: notebook_query, cross_notebook_query, source_get_content — any tool that returns large text content.
2. After each query, process and summarize the result BEFORE making the next query.
3. If you need data from multiple notebooks or sources, plan the query order first, then execute one-by-one.

Large response handling: If a single query returns a very large response (3000+ words), summarize it to essential points before proceeding to the next query. This prevents context window bloat when chaining multiple queries.

Why: NotebookLM responses can be large. Running 2-3 queries in parallel can exceed context limits and force compaction, losing critical session state.

Research

Workflow 1: Research a topic (RSRH-01)

"Research [topic]" or "quick research [topic]":

1. notebook_create(title="[topic] Research") — save returned notebook_id
2. If user provided URLs/files, add them: source_add(notebook_id, source_type="url", url=..., wait=True) for each
3. research_start(query="[topic]", notebook_id=..., mode="deep") — returns task_id
   • Use mode="fast" if user says "quick research" (~30s, ~10 sources)
   • Use mode="deep" by default (~5 min, ~40-80 sources)
4. research_status(notebook_id, task_id=..., max_wait=0) — check once after ~15s (see ## Long-Running Operations). If still in_progress, save reminder and move on.
5. research_import(notebook_id, task_id=...) — MANDATORY: research discovers sources but does NOT add them until imported
   • To restart pending research: research_start(..., force=True)
6. notebook_query(notebook_id, "Summarize the key findings and main themes") — return to user

Workflow 2: Query an existing notebook (RSRH-02)

"Ask my [notebook name] about [question]":

1. notebook_list() — resolve notebook name: fuzzy-match user's name against titles
   • If no match: list available notebooks and ask user to clarify
2. notebook_query(notebook_id=..., query="[user's question]") — return answer with citations
   • Add conversation_id only if user wants query history to persist in NotebookLM web UI

Workflow 3: Add sources to a notebook (RSRH-03)

"Add [source] to my [notebook]":

1. Resolve notebook name via notebook_list() (see Workflow 2 step 1)
2. Detect source type and call source_add(notebook_id, ..., wait=True):
   • URL: source_type="url", url="https://..."
   • Text block: source_type="text", text="...", title="[descriptive title]"
   • Google Drive: source_type="drive", document_id="[extracted from URL]", doc_type="doc"|"slides"|"sheets"|"pdf"
   • Local file: source_type="file", file_path="[absolute path]"
   • Supported file types: PDF, TXT, MD, DOCX, CSV, MP3, M4A, WAV, AAC, OGG, OPUS, MP4, JPG, JPEG, PNG, GIF, WEBP
3. Multiple sources: loop source_add for each, all with wait=True
4. Confirm: notebook_describe(notebook_id) to verify ingestion count

Artifacts

ASYNC: studio_create returns immediately — generation runs in background. Check status ONCE per ## Long-Running Operations. Do NOT poll repeatedly.

Creation pattern (all artifact types)

1. Get user confirmation before proceeding (studio_create is costly and irreversible)
2. studio_create(notebook_id, artifact_type="[type]", confirm=True, [type params]) — returns artifact_id
3. studio_status(notebook_id) — check once after ~15s (see ## Long-Running Operations) — "complete" → proceed | "failed" → report error | "in_progress" → save reminder, move on
4. On complete: inform user, offer to download

Artifact types

Type	Use for	Key params
audio	Podcast / deep dive	audio_format (deep_dive|brief|critique|debate), audio_length (short|default|long)
video	Explainer video	video_format (explainer|brief), visual_style (auto_select, classic, whiteboard, kawaii, anime, ...)
report	Written summary	report_format (Briefing Doc|Study Guide|Blog Post|Create Your Own), custom_prompt
slide_deck	Presentation	slide_format (detailed_deck|presenter_slides), slide_length (short|default)
infographic	Visual summary	orientation, detail_level, infographic_style (11 styles)
quiz	Study test	question_count, difficulty (easy|medium|hard)
flashcards	Flash review	difficulty (easy|medium|hard)
mind_map	Topic map	title (optional)
data_table	Structured data	description (REQUIRED — no default; call fails without it)

Common params on all types: source_ids (limit to specific sources), language, focus_prompt

Download

After status="complete": download_artifact(notebook_id, artifact_type, artifact_id, output_path) — if user omits path: suggest ~/Downloads/<notebook-title>.<ext> — for reports/data tables: export_artifact(notebook_id, artifact_id, export_type="docs"|"sheets") to export to Google Docs/Sheets

Slide revision

studio_revise(artifact_id, slide_instructions=["Slide 1: ...", "Slide 3: ..."], confirm=True) — creates a NEW artifact (original unchanged); poll studio_status for the new artifact_id

Source Management

Listing and inspection:

• List Drive sources: source_list_drive(notebook_id) — shows Drive sources with freshness status
• Describe source: source_describe(source_id) — AI summary + keywords
• Get raw text: source_get_content(source_id)
• Add source: use source_add per the Research workflow patterns (always wait=True)

Sync stale Drive sources (two-step):

1. source_stale(notebook_id) — identify Drive sources that need re-syncing
2. Ask user to confirm sync before proceeding
3. source_sync_drive(notebook_id, source_ids="[ids from step 1]", confirm=True)

Rename: source_rename(notebook_id, source_id, new_title)

Delete (irreversible):

1. Show user what will be deleted (source title, notebook it belongs to)
2. Ask for explicit confirmation — do NOT call source_delete until user confirms
3. source_delete(source_id, confirm=True)

Notebooks

• List: notebook_list() — returns all notebooks with IDs and titles
• Create: notebook_create(title="[name]") — returns notebook_id
• Describe: notebook_describe(notebook_id) — AI summary + suggested query topics
• Rename: notebook_rename(notebook_id, new_title="[new name]")

Delete (irreversible — deletes notebook and ALL its sources and artifacts):

1. Call notebook_describe(notebook_id) to show user what will be permanently deleted
2. Ask for explicit confirmation — do NOT call notebook_delete until user confirms
3. notebook_delete(notebook_id, confirm=True)

Advanced

Cross-notebook search (ADVN-01)

"Search all my notebooks for [topic]" or "which of my notebooks covers [topic]":

• All notebooks: cross_notebook_query(query="[topic]", all=True) — aggregated answer with per-notebook citations
• Filtered: cross_notebook_query(query="[topic]", notebook_names="Notebook A, Notebook B")
• By tag: cross_notebook_query(query="[topic]", tags="ml, research")
• Tag discovery: tag(action="select", query="machine learning") to find relevant notebooks first

Built-in pipelines (ADVN-02)

For common multi-step flows, use the pipeline tool instead of manual orchestration:

• pipeline(action="list") — see available pipelines
• pipeline(action="run", notebook_id=..., pipeline_name="ingest-and-podcast", input_url="https://...")
• pipeline(action="run", notebook_id=..., pipeline_name="research-and-report")
• pipeline(action="run", notebook_id=..., pipeline_name="multi-format") — creates audio + report + slides

For non-standard sequences, use the manual workflow steps from ## Research and ## Artifacts. See references/workflows.md for batch operations and extended pipeline patterns.

Notebook sharing (ADVN-03)

1. Check current access: notebook_share_status(notebook_id) — see collaborators + public status
2. Invite: notebook_share_invite(notebook_id, email="user@example.com", role="viewer"|"editor")
3. Public link: notebook_share_public(notebook_id, enabled=True) to enable, enabled=False to disable
4. Confirm result: call notebook_share_status(notebook_id) again and report the new access state to user

Other tools

• Notes: note(action="create"|"list"|"update"|"delete", notebook_id=..., ...) — manage notes in a notebook
• Tags: tag(action="add"|"remove"|"list", notebook_id=..., tags="...") — organize notebooks for discovery
• Chat config: chat_configure(notebook_id, goal="learning_guide"|"custom", custom_prompt="...") — tune chat behavior
• Server info: server_info() — check version and whether an update is available

References

• See references/setup.md for installation and auth configuration
• See references/tools.md for full MCP tool parameter reference (35 tools — populated in Phase 34)
• See references/workflows.md for extended pipeline, batch, and tag patterns