beam-ai-team/notebooklm-master

NotebookLM Master

This is NOT a user-facing skill. It's a shared resource library referenced by NotebookLM integration skills.

Purpose

Provides shared resources to eliminate duplication across:

• notebooklm-connect - Meta-skill for NotebookLM operations
• notebooklm-create-notebook - Create a new notebook
• notebooklm-get-notebook - Get notebook details
• notebooklm-list-notebooks - List recently viewed notebooks
• notebooklm-delete-notebooks - Batch delete notebooks
• notebooklm-share-notebook - Share notebook with users
• notebooklm-add-sources - Add sources (Drive, web, YouTube, text)
• notebooklm-upload-file - Upload file as source
• notebooklm-get-source - Get source details
• notebooklm-delete-sources - Delete sources
• notebooklm-create-audio - Generate audio overview (podcast)
• notebooklm-delete-audio - Delete audio overview

Instead of loading this skill, users directly invoke the specific skill they need above.

---

Architecture: DRY Principle

Problem solved: NotebookLM skills would have duplicated content (setup instructions, API docs, auth flow, error handling).

Solution: Extract shared content into notebooklm-master/references/ and notebooklm-master/scripts/, then reference from each skill.

Result: Single source of truth, reduced context per skill.

---

Shared Resources

All NotebookLM skills reference these resources (progressive disclosure).

references/

setup-guide.md - Complete setup wizard

• Enabling NotebookLM Enterprise API
• Google Cloud project configuration
• gcloud CLI authentication

api-reference.md - NotebookLM API patterns

• Base URL and authentication
• All API endpoints documented
• Request/response examples

error-handling.md - Troubleshooting

• Common errors and solutions
• HTTP error codes
• Authentication issues

authentication.md - Auth management

• OAuth 2.0 via gcloud CLI
• Token refresh flow
• Required IAM roles

scripts/

check_notebooklm_config.py - Pre-flight validation

• Checks for gcloud CLI
• Verifies project configuration
• Tests API connection
• Supports --json flag for structured AI-consumable output

setup_notebooklm.py - Interactive setup wizard

• Guides through Google Cloud setup
• Configures project and location
• Tests connection

notebooklm_client.py - API client

• Handles OAuth 2.0 via gcloud
• Provides get/post/delete methods
• Automatic token refresh

---

Intelligent Error Detection Flow

When a NotebookLM skill fails due to missing configuration, the AI should:

Step 1: Run Config Check with JSON Output

uv run python 00-system/skills/notebooklm/notebooklm-master/scripts/check_notebooklm_config.py --json

Step 2: Parse the ai_action Field

The JSON output includes an ai_action field that tells the AI what to do:

| ai_action | What to Do | |-----------|------------| | proceed_with_operation | Config OK, continue with the original operation | | install_gcloud | Guide user to install Google Cloud SDK | | run_gcloud_auth | Run: gcloud auth login | | configure_project | Set project: gcloud config set project PROJECT_ID | | run_setup_wizard | Run: python .../setup_notebooklm.py |

Step 3: Help User Fix Issues

If ai_action is configure_project:

1. Tell user: "NotebookLM needs your Google Cloud project configured."
2. Ask: "What is your Google Cloud project ID?"
3. Run: gcloud config set project PROJECT_ID
4. Update .env with project settings
5. Re-run config check to verify

---

Environment Variables

Required in .env:

GOOGLE_CLOUD_PROJECT_NUMBER=123456789012
NOTEBOOKLM_LOCATION=global
NOTEBOOKLM_ENDPOINT_LOCATION=global

---

API Base URL

All API requests go to: https://{ENDPOINT_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/{PROJECT_NUMBER}/locations/{LOCATION}

Endpoint location prefixes: us-, eu-, or global-

---

Version: 1.0 Created: 2025-12-27 Status: Generated by add-integration skill