Skip to content
Get packs

Guide · Agent skill

How to use the Gemini Notebook Automation agent skill (notebooklm)

Updated · written with AI from the project's own documentation and checked against our catalogue data

This skill teaches an AI agent to operate Gemini Notebook, Google's AI notebook tool, through the notebooklm-py command-line tool or its typed async Python API. It covers creating notebooks, adding and waiting for sources, asking grounded questions, generating artifacts such as mind maps, and downloading results. After following this guide you will know how to install the skill, trigger it with plain requests, and understand the authentication and safety rules it enforces.

Gemini Notebook Automationteng-lin/notebooklm-py · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Or upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
  2. 2Install notebooklm-py. Run pip install "notebooklm-py[browser]" in your existing Python 3.10+ environment, or use uv tool install or pipx for CLI-only use.
  3. 3Verify authentication. Run notebooklm auth check --test --json and confirm status is ok and token_fetch is true. Fix login if it fails.
  4. 4Ask for a task in plain language. Mention Gemini Notebook or the notebooklm CLI and describe the outcome, such as adding sources or asking a question.
  5. 5Confirm risky actions. When the agent asks before deleting, downloading or generating, reply yes only for actions you intend.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an AI coding agent specific instructions for one kind of task. This skill, named notebooklm, is for driving Gemini Notebook from the command line or Python instead of through the web interface.

It tells the agent how to check that login works before starting, how to create notebooks and add sources, how to ask grounded questions, how to generate and download artifacts, and how to handle research runs. It is not for the generic Gemini API or for unrelated content creation.

  • Manage notebooks and sources through the notebooklm CLI, preferring --json output and explicit IDs.
  • Ask grounded chat questions and run research.
  • Generate artifacts such as mind maps and download them.
  • Follow safety rules: verify authentication, pin commands to exact IDs, and ask before deleting, downloading, or starting long-running generation.

Install the notebooklm agent skill

Download the skill ZIP from this page and unzip it into one of these locations: ~/.claude/skills/ for all your projects, or .claude/skills/ inside a specific project. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the ZIP.

The skill relies on the notebooklm-py package, which must be installed separately. The source gives these install commands; the browser extra is needed for browser login:

  • Requires Python 3.10 or newer.
  • Optional extras: [browser], [cookies], [headless].
  • Alternatives for CLI-only use: uv tool install or pipx, as the skill describes.
  • Use the PyPI release rather than an unreleased main checkout.
pip install "notebooklm-py[browser]" pip install "notebooklm-py[cookies]" # optional browser-cookie extraction

Set up authentication before any workflow

The agent must confirm that login really works before it starts. Parsing a cookie file is not enough. Run the check below and expect status "ok" and token_fetch true.

If the check fails, the skill suggests running notebooklm login when a display is available. On a headless machine it suggests installing [cookies] and logging in with notebooklm login --browser-cookies <browser>, and if cookies went stale, notebooklm auth refresh. Note that the normal check may refresh and save cookies; add --passive for a strictly read-only check.

  • Auth files such as storage_state.json and master_token.json are bearer credentials. Never print, log, or commit them.
  • A master token is a durable full-account credential that survives password changes. Use a dedicated account, store it in a secret store, keep it at 0600 on disk, and revoke it if exposed.
  • notebooklm status shows selected-notebook context, not whether you are authenticated.
notebooklm auth check --test --json

Trigger the skill with natural requests

You do not need special syntax. The skill activates when you mention Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Describe the outcome you want and name the notebook when you can.

Good requests name the goal, the notebook, and any sources. The agent will then use exact IDs and ask you before anything destructive or long-running.

  • "Using the notebooklm CLI, create a notebook called Q3 Research and add these three URLs as sources."
  • "In my Gemini Notebook project, ask the notebook whether the report mentions churn and cite the answer."
  • "Generate a mind map from notebook abc123 and download it once it is finished."

Understand the operating rules the agent follows

The skill uses a few rules to keep work inspectable and safe, especially when several agents run at once. The agent retains full UUIDs returned by commands, passes -n with the notebook ID on every notebook-scoped command, and waits for each source to reach status "ready" before chatting or generating.

For concurrent runs, each agent should use its own NOTEBOOKLM_PROFILE so credentials and context are not shared. Downloads target a specific artifact ID, never the latest visible one.

  • Use --json for discovery and mutations.
  • Wait for sources with source wait; require exit 0 and status "ready".
  • Pass the artifact ID to artifact wait and download with -a <artifact_id> -n <notebook_id>.
  • Use --run-id for overlapping research runs.
  • Mind-map generation returns its result directly and needs no artifact wait.

Know what needs confirmation

The agent asks for confirmation before actions the user has not clearly authorized. Your request is the authorization boundary, not whether a CLI prompt appears.

Actions that need confirmation include deleting notebooks, sources, notes, artifacts, labels or profiles; removing sharing; logout; research cancellation; generation or long waits; downloads; importing research sources; and saving notes. Some destructive JSON commands run without prompting, so the agent must not treat a missing prompt as consent.

  • Destructive commands such as delete, clear, logout and research cancel.
  • Generation and long foreground waits, which can be rate-limited.
  • Downloads, which write files to disk.
  • language set, which changes the account-wide output language.

Safety notes: scripts and network access

This skill runs scripts and uses the network. It works by talking to Gemini Notebook on your behalf through notebooklm-py, which is an unofficial package. The source notes that Google's internal RPC method IDs are undocumented and change periodically, so the package may break.

Use it only with an account you are willing to automate, and avoid unattended master-token use on shared or untrusted machines. The source also says not to use the skill's master-token CI pattern outside a trusted setup.

  • Runs scripts: yes. Uses network: yes.
  • Keep auth files out of logs, repositories and shared machines.
  • Use a dedicated account for durable master-token auth.

What people use it for

  • Add a set of web sources to a notebook, wait until they are ready, and ask grounded questions about them.
  • Generate a mind map from a notebook and download the finished result.
  • Run a research query against a notebook and import findings after you approve.
  • Script repeatable notebook workflows in CI, using a dedicated profile and an exact notebook ID.

Frequently asked questions

Is the notebooklm agent skill free?

The source file does not state pricing for the skill. It is released under the MIT licence. The skill uses the notebooklm-py package, which is installed with pip, uv or pipx; check the package and repository for its current terms.

What do I need to use the notebooklm skill?

You need Python 3.10 or newer, the notebooklm-py package, a Google account with access to Gemini Notebook, and either a browser login or exported auth files such as storage_state.json or master_token.json.

Is notebooklm-py an official Google tool?

No. The source describes notebooklm-py as an unofficial async Python client that uses Google's internal RPC protocol. Because the protocol is undocumented and changes, workflows can break.

How do I fix authentication errors with notebooklm?

Run notebooklm auth check --test --json. If it fails with a display, run notebooklm login. Headless machines can install [cookies] and use notebooklm login --browser-cookies <browser>, or run notebooklm auth refresh for stale cookies.

Can this skill replace the Gemini API?

No. The skill says not to use it for the generic Gemini API or unrelated content creation. It is only for driving Gemini Notebook through the CLI or Python API.

Is it safe to use a master token?

Only with care. A master token is a full-account credential that survives password changes, so a leak exposes the whole account. Use a dedicated account, protect the file at 0600, and revoke it if exposed.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you are a developer or researcher who already runs the notebooklm-py CLI and wants an agent to operate Gemini Notebook carefully and repeatably. Pick something else if you only need the official Gemini API, or if you cannot allow a third-party tool to handle your Google session cookies or tokens.

Download the skill