Notebooklm Studio

NotebookLM Studio

Import sources into NotebookLM, generate user-selected artifacts via CLI, download results locally.

Inputs

Collect from user message (ask only for missing fields):

• Sources: URLs, YouTube links, text notes, or file attachments (PDF, Word, audio, image, Google Drive link)
• Artifacts: User selects from 9 types (no default — always ask):
• audio (podcast), video, report, quiz, flashcards, mind-map, slide-deck, infographic, data-table
• Language (optional, default: zh_Hant): applied via notebooklm language set
• ⚠️ This is a GLOBAL setting — affects all notebooks in the account
• Artifact options (discussed in step 1b): format, style, length, difficulty, etc.

See references/artifact-options.md for all options per artifact type.

• Custom instructions (optional): passed as description to generate commands
• Telegram target (optional, OpenClaw only): chat_id for delivery

See references/source-types.md for source type detection rules. See references/artifacts.md for all 9 artifact types and CLI options.

Workflow

Steps are sequential gates — do NOT skip or combine steps. Each numbered step must complete before the next begins. In particular:

• Step 0 (auth precheck) must run and pass before any other CLI command.
• Step 1b (options discussion) must get user confirmation before generation. Do not assume defaults unless the user explicitly says "use defaults."

⚠️ Concurrency: This skill does NOT support concurrent execution on the same NotebookLM account. The CLI uses global state (notebooklm use, language set) that will conflict if two agents run simultaneously.

1. Auth precheck — Verify the session is valid before doing any work:

``bash notebooklm auth check --test --json ``

• "status": "ok" → proceed to step 1.
• "status": "error" → stop immediately. Tell the user:

> NotebookLM 登入已過期，請先重新登入（notebooklm login），完成後告訴我，我再繼續。

• Command itself fails (network error, CLI not found, etc.) → also stop and report the error.
• --test is required — without it, only local checks run, which can pass even with an expired session.
• When the user confirms re-login, re-run this check before continuing.

1. Parse input & configure artifacts —

1a. Select artifacts — Detect source types from user message (URLs, files, text). Confirm which artifacts to generate.

1b. Discuss options — Before generating, confirm key options for each selected artifact. Refer to references/artifact-options.md for priority levels:

• ASK options: must ask the user
• OFFER options: state the default, let user decide whether to change
• SILENT options: use defaults without asking
• Options already specified by the user → skip
• Present all questions in a single message (batch, not one-by-one)

If user says "use defaults" → skip all questions, proceed with default values immediately.

Example agent message (audio + video + report + quiz + flashcards + slides + infographic selected): > Before generating, a few options to confirm: > - Podcast: deep-dive / brief / critique / debate? > - Video: explainer / brief / cinematic? (cinematic uses Veo 3, takes 30-40 min) > - Report: briefing-doc / study-guide / blog-post / custom? > - Slides: detailed / presenter? > - Quiz & Flashcards: difficulty medium, quantity standard — adjust? > - Infographic: style auto, or prefer a specific style (sketch-note, professional, bento-grid...)? > - Language: zh_Hant, OK? > > Or just say "use defaults" to start immediately.

1. Derive slug — Based on the sources and user message, generate a short kebab-case slug (2-4 words) that captures the core topic. This slug is used for both the notebook name and the output directory.

• Examples: react-server-components, feynman-technique, taiwan-semiconductor-q4
• Keep it concise, lowercase, ASCII-only (transliterate non-ASCII if needed)
• Must match: ^[a-z0-9][a-z0-9-]{0,48}[a-z0-9]$ (no slashes, dots, spaces, or path traversal)
• If the user provides a topic or title, prefer that as the basis

1. Create notebook —

``bash notebooklm create " " # → {"notebook_id": "xyz789", ...} ← capture notebook_id notebooklm use mkdir -p ./output/ ``

1. Set language —

``bash notebooklm language set `` Use the language confirmed in step 1b. ⚠️ GLOBAL setting — always set explicitly to avoid residual from previous runs.

1. Add sources — For each source:

```bash # URL, YouTube, or file path notebooklm source add ""

# Google Drive notebooklm source add-drive "" `` For plain text → save to a .txt file first, then source add "./temp_text.txt"`.

1. Generate artifacts — Two-tier strategy for timeout safety:

⚠️ Deduplication gate (Tier 2 only) — Before generating Tier 2 artifacts, call artifact list once and check all requested types in that single response: ``bash notebooklm artifact list --json # → [{"task_id": "abc123", "type": "slide-deck", "status": "processing"}, ...] ` For each Tier 2 artifact you are about to generate, look for entries where type matches (e.g., slide-deck, audio, video). If multiple entries match the same type, the non-terminal status takes priority (processing/pending > completed > failed`):

• processing / pending → do NOT generate again. Take the existing task_id, go to step 9 (wait + deliver).
• completed → do NOT generate again. Skip the wait — go directly to download + deliver in step 9.
• failed → safe to re-generate.
• No matching entry → proceed with generation.

If artifact list itself fails or returns an error, proceed with generation — the dedup check is a safety net, not a hard gate. Duplicate generation wastes resources and causes confusion — this gate prevents the most common operational error.

Tier 1 — Immediate (use --wait, completes within timeout): ```bash # Sync (instant) notebooklm generate mind-map

# Fast async (1-2 min) — use options confirmed in step 1b notebooklm generate report --format --wait notebooklm generate quiz --difficulty --quantity --wait notebooklm generate flashcards --difficulty --quantity --wait notebooklm generate data-table "" --wait

# Medium async (2-5 min) notebooklm generate infographic --style --orientation --wait ```

Tier 2 — Deferred (use --json without --wait, capture task_id for step 9): ```bash # Slow async — use options confirmed in step 1b # Parse JSON output to extract taskid for polling notebooklm generate slide-deck --format --json # → {"taskid": "abc123", "status": "pending"} ← save task_id

notebooklm generate video --format --style --json # → {"taskid": "def456", "status": "pending"} ← save taskid # Note: if cinematic, omit --style (ignored by Veo 3)

notebooklm generate audio "" --format --length --json # → {"taskid": "ghi789", "status": "pending"} ← save taskid `` Options accepted as defaults in step 1b can be omitted (CLI uses its own defaults). Parse each JSON response and save the task_id — you will need it in step 9. Only generate the artifacts the user requested. Skip the rest. See references/artifacts.md` → "Deferred Generation" for Tier 2 details.

Write delivery status — Immediately after all Tier 2 generates are dispatched, write ./output//delivery-status.json so the recovery script can pick up if the agent times out: ``json { "slug": "", "notebook_id": "", "created_at": "", "artifacts": [ {"type": "report", "task_id": null, "status": "delivered", "output_path": "./output//report.md"}, {"type": "slide-deck", "task_id": "", "status": "pending", "output_path": "./output//slides.pdf"}, {"type": "audio", "task_id": "", "status": "pending", "output_path": "./output//podcast.mp3"} ] } ` Include all requested artifacts (both Tier 1 and Tier 2). Tier 1 artifacts start as delivered (already sent). Update Tier 2 status as step 9 progresses: pending → completed (downloaded) → delivered (sent to Telegram), or failed on error. This file is the handoff contract between the agent and scripts/recovertier2delivery.sh. Telegram delivery is agent-only (requires OpenClaw message` tool); the recovery script handles download + status tracking only.

1. Download Tier 1 — Each successful Tier 1 artifact into ./output//:

``bash notebooklm download mind-map ./output//mindmap.json notebooklm download report ./output//report.md notebooklm download quiz --format json ./output//quiz.json notebooklm download flashcards --format json ./output//flashcards.json notebooklm download data-table ./output//data.csv notebooklm download infographic ./output//infographic.png ``

1. Report + Deliver Tier 1 — Present completed Tier 1 artifacts to user.

If Tier 2 artifacts are pending, include a status note: > "Slides/Audio/Video are still generating, I'll send them when ready."

Telegram delivery (OpenClaw only) — If message tool is available:

1. Text summary with Tier 2 pending status (always first)
2. Report → Quiz → Flashcards → Mind Map → Infographic → Data Table

See references/telegram-delivery.md for delivery contract. Skip Telegram delivery if running outside OpenClaw (e.g. Claude Code, Codex).

1. Poll + Deliver Tier 2 — Wait for each deferred artifact in order of expected speed (fastest first), then download and deliver as each completes:

```bash # Wait by expected completion order: slide-deck (fastest) → video → audio (slowest) # Uses --interval 5 (not default 2) since Tier 2 artifacts take minutes, not seconds notebooklm artifact wait --timeout 1800 --interval 5 --json # → {"status": "completed", ...} ← taskid from generate is used as artifactid here notebooklm download slide-deck ./output//slides.pdf # → deliver to Telegram immediately

notebooklm artifact wait --timeout 1800 --interval 5 --json # Note: if cinematic, use --timeout 2400 (generation takes 30-40 min) notebooklm download video ./output//video.mp4 # → deliver to Telegram immediately

notebooklm artifact wait --timeout 1800 --interval 5 --json notebooklm download audio ./output//podcast.mp3 bash scripts/compressaudio.sh ./output//podcast.mp3 ./output//podcastcompressed.mp3 # → deliver to Telegram immediately ```

• Order matters: wait for fastest artifact first (slide-deck → video → audio) to minimize idle time
• On completion: download → post-process → deliver to Telegram → update delivery-status.json status to delivered
• On failure: update status to failed with reason, notify user, continue to next artifact
• On timeout: see timeout recovery below
• Max wait: 30 minutes per artifact (covers worst-case audio/video)
• If agent is about to exit with any artifact still pending, tell the user:

> "Tier 2 補送模式已啟動，recovery script 會每 5 分鐘檢查並自動送達。"

⚠️ Timeout recovery — If artifact wait returns status: "timeout", the artifact is likely still generating. NEVER re-generate. Instead:

1. Re-check status: notebooklm artifact poll --json
2. If processing → re-wait: notebooklm artifact wait --timeout 1800 --interval 5 --json
3. If completed → download and deliver
4. If failed → notify user with error, move to next artifact
5. If re-wait also times out (2+ total timeouts, ~60 min elapsed) → give up, notify user, suggest downloading from NotebookLM directly

A timeout means the wait expired, not that generation failed. The task continues server-side. Re-generating creates duplicates and wastes time.

Error handling

• Auth errors → caught by step 0 precheck. If any CLI command later returns an authentication/session error (HTTP 401, "Not logged in", "session expired", token fetch failure), treat it as a mid-workflow auth failure — stop, ask user to re-login, then re-run step 0 before resuming.
• Tier 1 failure: retry up to 2 times (3 total attempts), then include failure note in step 8 delivery.
• Tier 2 failure: notify user per-artifact in step 9. Tier 1 is already delivered by this point, so Tier 2 failures never block text artifact delivery.
• All sources failed (step 5): if every source add fails, stop immediately — generation without sources is meaningless. Report the failures and ask user to check sources.
• Notebook creation failed (step 3): if notebooklm create fails (API error, rate limit), stop and report. Do not proceed without a valid notebook_id.
• delivery-status.json write failure (step 6): if writing the JSON file fails, log a warning and continue — Tier 2 artifacts are already dispatched. The agent can still poll and deliver, but cron recovery will not be available.
• Audio still > 50MB after compression (step 9): if compress_audio.sh output exceeds 50MB, warn user and provide the local file path instead of attempting Telegram delivery. Suggest downloading from NotebookLM directly.
• Capture failure reason in delivery status.

Delivery confirmation gate

Before reporting "complete" to the user, ALL of the following must be true:

1. Every requested artifact is either successfully delivered or reported as failed with reason
2. For Telegram delivery (OpenClaw): each message tool call (OpenClaw's built-in messaging tool) returned a success response with a messageId

• If a send fails, retry once. If still failing, report the failure to the user — do NOT silently skip

1. No artifact is still in processing or pending status without being tracked

Never say "done" while any artifact is still pending delivery. If Tier 2 artifacts are still generating, say so explicitly and continue waiting. The task is not complete until everything is delivered or accounted for.

Quality gate

Before delivery, verify:

• Sources are concrete article/content pages (not category/index pages).
• Report contains actionable takeaways (not generic summary).
• Quiz tests key concepts and mechanics.
• Flashcards focus on terms, decisions, and trade-offs.
• Output respects requested language and length.

See references/output-contracts.md for format specifications.

Delivery template

1. Selection rationale (<=3 bullets)
2. Artifact list with paths/status (all 9 types if applicable)
3. Key takeaways (3-5 bullets)
4. Failures + fallback note (if any)
5. One discussion question

Changelog

v2.1.3

• Schema unification — delivery-status.json now uses a single schema across SKILL.md, telegram-delivery.md, and recovery script. Eliminates conflicting flat vs structured formats.
• Recovery cooldown — cron script skips artifacts younger than 30 minutes (RECOVERY_COOLDOWN_MIN), preventing agent/cron race conditions.
• Concurrency guard — explicit warning that concurrent execution on the same account is unsupported (CLI global state conflicts).
• Infographic fixed Tier 1 — removed ambiguous "borderline" classification; infographic is now unambiguously Tier 1.
• Critical error handling — added 5 rules for previously silent failures: all-sources-failed, notebook-create-failed, delivery-json-write-failure, audio-over-50MB, and retry count clarification.
• Slug validation — regex ^[a-z0-9][a-z0-9-]{0,48}[a-z0-9]$ prevents path traversal and command injection.
• Recovery logging — ISO 8601 timestamps on all recovery script output.

v2.1.0

• Auth precheck gate — step 0 runs auth check --test --json before any work; expired sessions fail fast instead of blowing up mid-generation.
• Dedup gate — step 6 checks artifact list before Tier 2 generation to prevent duplic

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jasontsaicc
• Source: jasontsaicc/notebooklm-studio-skill
• License: MIT

Install and usage instructions live in the source repository linked above.