# How to Integrate notebooklm-py with Claude Code Agent Skills

> Learn to integrate notebooklm-py with Claude Code Agent skills. Install the notebooklm skill using a simple command for autonomous NotebookLM operations. Get started now.

- Repository: [Teng Lin/notebooklm-py](https://github.com/teng-lin/notebooklm-py)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Install the notebooklm-py Claude Code skill by running `notebooklm skill install`, which copies the packaged [`SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/SKILL.md) definition to `~/.claude/skills/notebooklm/` and enables the `/notebooklm` command trigger for autonomous NotebookLM operations.**

The `notebooklm-py` repository provides a dedicated Claude Code skill that bridges Google's NotebookLM automation with Anthropic's agent framework. By integrating notebooklm-py with Claude Code agent skills, you enable conversational control over notebook creation, source ingestion, and audio artifact generation through natural language commands. This integration requires no external configuration beyond standard authentication.

## Architecture Overview

The Claude Code skill implementation follows a layered architecture that separates the skill definition from the CLI management logic:

- **Skill Definition Layer**: The file [`src/notebooklm/data/SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/data/SKILL.md) contains the Markdown payload that Claude reads to register the skill. It defines the skill name, activation triggers, autonomy rules, and command reference table.

- **CLI Skill Management Layer**: The Click-based command group in [`src/notebooklm/cli/skill.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/cli/skill.py) implements the `notebooklm skill` subcommands (`install`, `status`, `uninstall`, `show`). This module uses `importlib.resources` to read the packaged [`SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/SKILL.md), injects the current package version via `get_package_version()`, and writes the file to `~/.claude/skills/notebooklm/SKILL.md`.

- **Core Execution Layer**: The `NotebookLMClient` class in [`src/notebooklm/client.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/client.py) handles the actual NotebookLM operations through Google’s internal `batchexecute` RPC endpoints, accessible via the [`src/notebooklm/_core.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/_core.py) session manager and [`src/notebooklm/rpc/encoder.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/rpc/encoder.py) utilities.

When installed, Claude’s backend scans `~/.claude/skills/notebooklm/SKILL.md` to register the `/notebooklm` trigger and determine which CLI commands require user confirmation versus autonomous execution.

## Installing the Claude Code Skill

The integration begins with the Click-based skill management interface. Run the install command to copy the skill definition into Claude’s personal skill directory:

```bash
notebooklm skill install

```

This command performs three operations:
1. Reads the packaged [`SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/SKILL.md) from [`src/notebooklm/data/SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/data/SKILL.md) using `importlib.resources`
2. Embeds a version comment (`<!-- notebooklm-py v0.3.2 -->`) via the `get_package_version()` function
3. Creates the directory `~/.claude/skills/notebooklm/` if missing and writes the skill file

### Verifying the Installation

Confirm that Claude recognizes the skill and that the embedded version matches your CLI installation:

```bash
notebooklm skill status

```

This compares the version comment inside `~/.claude/skills/notebooklm/SKILL.md` against the running package version, alerting you if a mismatch requires reinstallation.

### Understanding the Skill Definition

View the raw Markdown that Claude parses:

```bash
notebooklm skill show

```

This outputs the contents of [`src/notebooklm/data/SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/data/SKILL.md), which contains:
- **Activation triggers**: Phrases like "create a notebooklm podcast" that Claude maps to the `/notebooklm` intent
- **Autonomy rules**: Classification of commands as autonomous (safe to run without confirmation) versus restricted
- **Command mapping**: The translation table between natural language requests and specific CLI invocations

## Using the Skill in Claude Conversations

Once installed, Claude detects requests matching the triggers defined in [`SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/SKILL.md) and executes the corresponding CLI commands automatically. The skill distinguishes between quick operations and long-running tasks:

**Quick commands** (return immediately):
- `notebooklm list` – Lists all notebooks
- `notebooklm source list` – Shows sources in a notebook
- `notebooklm status` – Checks client authentication

**Long-running tasks** (follow autonomy rules):
- `notebooklm generate audio` – Creates podcast artifacts
- `notebooklm source add` – Ingests documents (when requiring processing time)

For autonomous execution, Claude spawns the CLI command in its sandbox and returns results directly. For generation tasks, Claude may spawn a background sub-agent to wait for completion using `notebooklm artifact wait` before retrieving the file.

Manual equivalents for testing:

```bash

# Create a notebook

notebooklm create "AI Research" --json

# Add a web source

notebooklm source add "https://example.com/ai-article" --json

# Wait for source indexing (Claude does this automatically when needed)

notebooklm source wait <source_id> -n <notebook_id> --timeout 300

# Generate audio (Claude runs this autonomously via the skill)

notebooklm generate audio "Summarize the key points" --json

# Wait and download the artifact

notebooklm artifact wait <task_id> -n <notebook_id> --timeout 1200
notebooklm download audio ./output.mp3 -a <task_id> -n <notebook_id>

```

## Programmatic Integration with the Python API

Beyond the conversational interface, you can embed notebooklm-py directly into Claude Code tools using the async client. This provides fine-grained control over the NotebookLM workflow:

```python
from notebooklm import NotebookLMClient

async def generate_podcast(topic: str):
    async with await NotebookLMClient.from_storage() as client:
        # Create notebook

        nb = await client.notebooks.create(title=f"{topic} Podcast")
        
        # Add Wikipedia source

        url = f"https://en.wikipedia.org/wiki/{topic}"
        src = await client.sources.add_url(nb.id, url)
        await client.sources.wait(src.id)  # Block until indexed

        
        # Generate audio artifact

        art = await client.artifacts.generate_audio(
            nb.id, 
            instruction=f"Create a concise podcast about {topic}"
        )
        await client.artifacts.wait(art.id)  # Block until rendered

        
        # Download to local filesystem

        await client.artifacts.download(art.id, path="podcast.mp3")
        return "Podcast saved to podcast.mp3"

# Claude Code can execute: await generate_podcast("Artificial_intelligence")

```

The `NotebookLMClient` exposes high-level interfaces for notebooks, sources, artifacts, and chat, all utilizing the RPC stack defined in [`src/notebooklm/_core.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/_core.py) and the encoding utilities in [`src/notebooklm/rpc/encoder.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/rpc/encoder.py).

## Managing Skill Versions

When you upgrade the `notebooklm-py` package, the skill file may become outdated. The CLI detects version mismatches through the embedded comment inserted by `get_package_version()`:

```bash

# Check for drift between package and skill file

notebooklm skill status

# Force update to current version

notebooklm skill install

```

Reinstalling overwrites `~/.claude/skills/notebooklm/SKILL.md` with the latest definitions, ensuring Claude has access to new commands or updated autonomy rules.

## Summary

- The `notebooklm skill install` command copies [`src/notebooklm/data/SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/data/SKILL.md) to `~/.claude/skills/notebooklm/SKILL.md`, enabling the `/notebooklm` trigger
- Claude parses the skill definition to map natural language requests to CLI commands implemented in [`src/notebooklm/cli/skill.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/cli/skill.py)
- **Autonomy rules** in the skill definition distinguish between immediate commands (like `list`) and background tasks (like `generate audio`)
- The `NotebookLMClient` in [`src/notebooklm/client.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/client.py) provides async Python access to NotebookLM's `batchexecute` RPC endpoints for custom tool development
- Version tracking via embedded comments ensures the skill stays synchronized with the CLI package

## Frequently Asked Questions

### Where does notebooklm-py install the Claude Code skill file?

The skill installs to `~/.claude/skills/notebooklm/SKILL.md` as defined by the `SKILL_DEST_DIR` constant in [`src/notebooklm/cli/skill.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/cli/skill.py). This canonical location is where Claude Code scans for user-installed agent skills.

### What commands can Claude run autonomously with the notebooklm skill?

According to the autonomy rules defined in [`src/notebooklm/data/SKILL.md`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/data/SKILL.md), Claude can execute read-only and quick operations like `notebooklm list`, `notebooklm source list`, and `notebooklm status` without confirmation. Long-running generation commands like `notebooklm generate audio` may trigger background sub-agents that wait for completion before returning results.

### How do I update the Claude Code skill when upgrading notebooklm-py?

Run `notebooklm skill install` again after upgrading the package. The command in [`src/notebooklm/cli/skill.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/cli/skill.py) compares versions using `get_package_version()` and overwrites the skill file with the current definition, ensuring Claude recognizes new features and command syntax.

### Can I use the notebooklm-py Python API directly in Claude Code tools?

Yes. The `NotebookLMClient` class from [`src/notebooklm/client.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/client.py) is fully async and can be imported into Claude Code tool definitions. This allows you to programmatically create notebooks, add sources, generate artifacts, and download files using the same RPC stack that powers the CLI commands.