# Notebooklm Studio

> >

- **Type:** Skill
- **Install:** `agentstack add skill-jasontsaicc-notebooklm-studio-skill-notebooklm-studio-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jasontsaicc](https://agentstack.voostack.com/s/jasontsaicc)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jasontsaicc](https://github.com/jasontsaicc)
- **Source:** https://github.com/jasontsaicc/notebooklm-studio-skill

## Install

```sh
agentstack add skill-jasontsaicc-notebooklm-studio-skill-notebooklm-studio-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

0. **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.

2. **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

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

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

5. **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"`.

6. **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 task_id for polling
   notebooklm generate slide-deck --format  --json
   # → {"task_id": "abc123", "status": "pending"}  ← save task_id

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

   notebooklm generate audio "" --format  --length  --json
   # → {"task_id": "ghi789", "status": "pending"}  ← save task_id
   ```
   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/recover_tier2_delivery.sh`.
   Telegram delivery is agent-only (requires OpenClaw `message` tool); the recovery script handles download + status tracking only.

7. **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
   ```

8. **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).

9. **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", ...}  ← task_id from generate is used as artifact_id 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/compress_audio.sh ./output//podcast.mp3 ./output//podcast_compressed.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
3. 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](https://github.com/jasontsaicc)
- **Source:** [jasontsaicc/notebooklm-studio-skill](https://github.com/jasontsaicc/notebooklm-studio-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jasontsaicc-notebooklm-studio-skill-notebooklm-studio-skill
- Seller: https://agentstack.voostack.com/s/jasontsaicc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.