How to Integrate notebooklm-py with Claude Code Agent Skills

Install the notebooklm-py Claude Code skill by running notebooklm skill install, which copies the packaged 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 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 implements the notebooklm skill subcommands (install, status, uninstall, show). This module uses importlib.resources to read the packaged 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 handles the actual NotebookLM operations through Google’s internal batchexecute RPC endpoints, accessible via the src/notebooklm/_core.py session manager and 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:

notebooklm skill install

This command performs three operations:

1. Reads the packaged SKILL.md from 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:

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:

notebooklm skill show

This outputs the contents of 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 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:

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

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 and the encoding utilities in 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():

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}