How platdrag/notebooklm-claude-skill works
1. What this repo is
- This is not a standalone application; it is a Claude Code plugin package.
- The repository mainly contains plugin metadata, two Claude skills, and a config template that together enable NotebookLM-backed querying from inside Claude Code.
2. Top-level architecture
- The repo has three functional areas:
- Plugin packaging in .claude-plugin/
- Operational skills in skills/setup and skills/query
- Project configuration template in templates/
- There is no backend service in this repo; the runtime work happens locally through Claude Code and an external Python CLI.
3. Plugin distribution boundary
- .claude-plugin/plugin.json defines the plugin for Claude Code.
- .claude-plugin/marketplace.json exposes it through a marketplace flow, so it can be installed via /plugin install.
- This boundary matters because it separates distribution/installation concerns from the skill logic itself.
4. User-facing command surface
- The repo exposes two slash commands:
- /notebooklm:setup
- /notebooklm:query
- These map directly to the two skill folders under skills/.
- Architecturally, these are the entry points into the system.
5. Setup subsystem
- skills/setup/SKILL.md defines the interactive bootstrap flow.
- Its responsibility is to prepare the local project for NotebookLM usage:
- install the notebooklm-py CLI
- authenticate with Google
- discover available notebooks
- write per-project configuration
- This skill is the configuration and onboarding boundary between the user’s project and NotebookLM.
6. Query subsystem
- skills/query/SKILL.md defines the retrieval flow for asking questions.
- It consumes the project config created by setup and uses the configured notebook selection to route requests.
- Its output is described as structured JSON with inline citations and source passages, which is the main data contract for downstream use inside Claude Code.
7. Local project state
- The repository includes templates/notebooklm-config.json, which serves as a starter shape for the project-local config file.
- The actual generated file lives at <project>/.claude/notebooklm-config.json.
- This means notebook selection and query behavior are per-project stateful, not global.
8. External runtime dependency
- The repo depends on the external Python CLI notebooklm-py.
- That CLI is the execution bridge to Google NotebookLM, which is the actual source of grounded answers.
- So the live architecture is: Claude Code → skill logic → notebooklm-py CLI → Google NotebookLM.
9. Data flow
- The setup flow discovers notebooks and stores notebook IDs plus metadata in the project config.
- The query flow reads that config, resolves the target notebook, and submits the user question.
- NotebookLM returns cited source-grounded content, which the skill formats for Claude Code.
- The key data boundary is the config file, which links human-friendly notebook names to NotebookLM notebook IDs.
10. Operational characteristics
- The solution is intentionally local and user-controlled: no service account, no hosted API in this repo, and no repo-managed server.
- Cross-platform behavior is explicitly supported for macOS, Linux, and Windows.
- The setup skill also accounts for environment differences such as Windows UTF-8 handling.
11. Repository structure and maintainability
- The codebase is small and declarative, optimized for distribution rather than heavy implementation.
- Most behavior is encoded in skill documentation rather than traditional source files.
- For diagramming purposes, treat this repo as a Claude Code extension package with local config plus an external NotebookLM integration, not as a conventional app stack.
Main entry points: query/SKILL.md Query skill · setup/SKILL.md Setup skill · plugin.json plugin.json · notebooklm-config.json Config template
Components 11
Distribution
Plugin packaging and marketplace metadata for Claude Code installation.
- plugin.json · Defines the Claude Code plugin package.
.claude-plugin/plugin.json - marketplace.json · Publishes the plugin for install flow support.
.claude-plugin/marketplace.json
Commands
User-facing slash commands that enter the skills.
- /notebooklm:setup · Entry point for bootstrapping local NotebookLM access.
- /notebooklm:query · Entry point for asking questions against a selected notebook.
Skills
Operational flows for setup and querying.
- Setup skill · Interactive onboarding that installs, authenticates, discovers notebooks, and writes config.
skills/setup/SKILL.md - Query skill · Reads project config, routes the question, and formats cited results.
skills/query/SKILL.md
Project State
Per-project NotebookLM configuration created by setup and consumed by query.
- Config template · Template for the per-project NotebookLM configuration.
templates/notebooklm-config.json - Project config · Generated notebook selection and metadata stored under the project.
External Runtime
Local CLI bridge and the NotebookLM service it reaches.
- notebooklm-py · Local execution bridge between Claude Code and Google NotebookLM.
- NotebookLM · The upstream source of grounded notebook answers and citations.
Other components
- Claude Code · The environment that loads the plugin and runs the slash commands.
Connections 15
- Claude Code → plugin.json: loads · Claude Code consumes the plugin manifest to register the extension.
- Claude Code → marketplace.json: installs via · Marketplace metadata enables plugin installation flow.
- plugin.json → /notebooklm:setup: exposes · The plugin publishes the setup command surface.
- plugin.json → /notebooklm:query: exposes · The plugin publishes the query command surface.
- /notebooklm:setup → Setup skill: invokes · Setup command enters the onboarding skill.
- /notebooklm:query → Query skill: invokes · Query command enters the retrieval skill.
- Setup skill → notebooklm-py: uses · Setup delegates installation, auth, and notebook discovery to the CLI bridge.
- Setup skill → Config template: starts from · The template provides the expected config shape.
- Setup skill → Project config: writes · Setup creates or updates the project-local NotebookLM config.
- Config template → Project config: materializes as · Template content becomes the generated project configuration.
- Query skill → Project config: reads · Query resolves the selected notebook from project-local state.
- Query skill → notebooklm-py: uses · Query delegates the actual NotebookLM request to the CLI bridge.
- notebooklm-py → NotebookLM: queries · The local CLI reaches Google NotebookLM for grounded answers.
- Project config → Query skill: selects notebook · Stored notebook IDs and metadata determine which notebook is queried.
- Query skill → Claude Code: returns cited JSON · The skill formats structured answers for Claude Code consumption.