1仕組みと動作原理
SKILL.md 自体は実行エンジンではなく「エージェント運用マニュアル」です。パッケージに付属する `notebooklm` CLI の呼び出し方をエージェントに指示し、実際のネットワークおよびプロトコル実装は Python パッケージ側に存在します（Web 向け batchexecute RPC および Android gRPC バックエンド）。
SKILL.md
Use the `notebooklm` CLI for agent workflows. Prefer `--json` and explicit IDs so every operation is inspectable and safe under concurrency.
実装上の証拠はパッケージ内にあります：`src/notebooklm/rpc/types.py:94` で `BATCHEXECUTE_URL = f"{DEFAULT_BASE_URL}/_/LabsTailwindUi/data/batchexecute"` が定義され、`src/notebooklm/_env.py:22` で `DEFAULT_BASE_URL = "https://notebook.google.com"` が定義されています。つまり、エージェントが実行する各コマンドは最終的に Google の非公開 RPC エンドポイントへの呼び出しとなります。SKILL.md は「使用方法、完了条件、ユーザー確認必須事項」を規定し、Python パッケージが「送信処理」を担います。
本スキルは Python パッケージ内に直接バンドルされた成果物です。ビルド時にリポジトリ直下の SKILL.md が `notebooklm/data/SKILL.md` に注入され、`notebooklm skill install` によってエージェントホストのスキルディレクトリに配置されるため、スキル定義と CLI バージョンが自然と同源・同バージョンに保たれます。
pyproject.toml
force-include = {"SKILL.md" = "notebooklm/data/SKILL.md", "AGENTS.md" = "notebooklm/data/CODEX.md"}
インストール対象ディレクトリは `src/notebooklm/_app/skill.py:50-51` に記載されています：`"claude": SkillTarget("Claude Code", Path(".claude") / "skills" / "notebooklm" / "SKILL.md")` および `"agents": SkillTarget("Agent Skills", Path(".agents") / "skills" / "notebooklm" / "SKILL.md")`。CLI 側には `--scope project|user`、`--dry-run`、`--no-clobber`、`--force`、`skill package`（アップロード用アーカイブ作成）、`skill status --json`（インストール済みバージョンと `content_mismatch` の報告）も用意されています。SKILL.md の末尾にも「`notebooklm skill install` installs or updates supported local skill targets.」と明記されています。
認証は「平文認証情報ファイル＋階層化」モデルを採用しています。ブラウザログインにより storage_state.json（セッション Cookie）が生成され、ヘッドレス環境では master_token.json（アカウントレベルの認証情報）を使用します。両者ともファイル権限 0600、ディレクトリ権限 0700 が要求され、プロファイルごとの分離に対応しています。
SKILL.md
A master token is a durable full-account credential that survives password changes; use a dedicated account, protect it in a secret store and as `0600` on disk, and explicitly revoke it if exposed.
保存先と権限は SECURITY.md の一覧表に明記されています（例: `profiles/<profile>/storage_state.json` = Google session cookies / `0o600`、`profiles/<profile>/master_token.json` = Google master token (Android / headless) / `0o600`、`profiles/<profile>/browser_profile/` / `0o700`）。コード側では `src/notebooklm/_atomic_io.py:221` により強制されます（"``fchmod`` the temp file to ``mode`` (default ``0o600`` — cookies are …"）。SKILL.md は CI 環境の `NOTEBOOKLM_MASTER_TOKEN_JSON` が単なる「機密転送規約」に過ぎず、0600 ファイルとして書き出した後に unset する必要がある点も注意喚起しています。
「明示的 ID ＋ readiness（準備完了）ゲート」により、不確実な非同期生成プロセスを検証可能なステートマシンに変換しています。ソースは `ready`、成果物（artifact）は `completed` になるまで待機する必要があり、いずれも「最新の可視項目」ではなく返却された実 ID を指定して処理します。
SKILL.md
After adding sources, retain every `.source.id`, then run `source wait` for each before chat or generation.
関連する運用ルール：「Download that exact artifact with `-a <artifact_id> -n <notebook_id>`; never select the latest visible artifact.」。ステータスの定義は Output and Citations セクションに明記されています（ソース: `unknown`/`preparing`/`processing` -> `ready` または `error`、成果物: `pending`/`in_progress` -> `completed`、`failed`、または `removed`）。
同時実行の安全性は三重の分離によって担保されています。各 CLI コマンドに `-n/--notebook` を明示し、並列実行ごとに独立したプロファイルを用い、ディープリサーチには `--run-id` を指定します。複数のエージェント間で書き込み可能な同一の storage_state.json を共有することは禁止されています。
SKILL.md
For every concurrent run, also set a unique `NOTEBOOKLM_PROFILE=agent-<id>` so context and profile writes are isolated.
同じ項目に「A new profile has no credentials: put a `master_token.json` copy in that profile and mint its storage before use. Never share one writable `storage_state.json` across agents.」と記載されています。コード側では `src/notebooklm/_atomic_io.py` 内の `storage_state.json` 専用ロック（`.storage_state.json.lock`）が対応しており、このファイル名が一般的なアトミック書き込みパスを通ることを明示的に拒否します（"``atomic_update_json`` rejects ``storage_state.json`` paths"）。
認可の境界線はスローガンではなく厳密な規約として定義されています。安全な読み取り専用操作は即座に実行可能ですが、破壊的・時間のかかる・ディスク書き込みを伴うアクションは事前にユーザーの確認を得る必要があります。また「CLI に確認プロンプトが出ない ≠ 認可済み」であることが明確化されています。
SKILL.md
User intent, not the presence of a CLI prompt, is the authorization boundary.
事前確認が必要な操作リストには、各種削除（notebook/source/note/artifact/label/profile の削除、共有解除、ログアウト、クリア、リサーチ中止、`ask --new`）、`language set`（アカウント全体の出力言語変更）、生成および長時間の待機、ダウンロード（ファイル書き込み）、`research wait --import-all`（ソース取り込み）、`ask --save-as-note` および `history --save`（ノート作成）が含まれます。診断フェーズ用には「Add `--passive` when the check must be strictly read-only」という読み取り専用フラグも存在します。
引用の追跡可能性：チャットの回答には `references[].source_id` が付与され、文字オフセットは（平文のバイト／文字オフセットではなく）UTF-16 オフセットであるため、エージェントが独自に切り出すのではなく専用の解析関数が提供されています。
SKILL.md
A reference's `start_char`/`end_char` are UTF-16 offsets into the structured source document, not flat `SourceFulltext.content`.
提供される API：「In Python, use `from notebooklm import resolve_chat_reference_passage`, then call `await resolve_chat_reference_passage(client, notebook_id, reference)`; it uses the exact document range and falls back to `find_citation_context()` when necessary.」。誤りが生じやすいオフセット計算をエージェントに推測させず、ライブラリ側で完結させています。
障害処理には曖昧なプロンプトではなく、判定可能な終了コードとレスポンスエンベロープ規約が定義されています。成功は 0、一般エラーは 1、`source wait` タイムアウトは 2、`artifact wait`/`research wait` タイムアウトは 1 であり、調査時に状態変更を伴わない読み取り専用診断が義務付けられています。
SKILL.md
Exit 0 means success. Expected command failures use exit 1. A `source wait` timeout uses exit 2; `artifact wait` and `research wait` timeouts use exit 1.
同セクションでは 2 種類の JSON 形式を区別しており（"Ordinary handled JSON failures use `{error, code, message}`, while wait commands return domain envelopes such as `{"status": "timeout", "error": "..."}`"）、診断用コマンドの組み合わせを読み取り専用に限定し、生成失敗時に無限ループへ陥らないよう規定しています（"do not loop indefinitely"）。
2コア機能
01ノートブックおよびソースのライフサイクル全般の管理（一覧取得／作成／ソース追加／準備完了待機）。URL、YouTube、Google ドライブ、テキスト、ファイルなど多彩なソース形式に対応
02ソースに基づいたグラウンディング対話（grounded chat）。conversation_id および特定可能な引用（citations）を返却
039 種類の成果物（artifact）生成：音声、動画、スライド、インフォグラフィック、レポート、マインドマップ、データ表、クイズ、単語帳
04ディープリサーチの 2 段階オーケストレーション：ノンブロッキング開始（`--mode deep --no-wait`）→ 明示的認可後の `research wait --import-all` によるソース取り込み
05成果物の ID 指定によるユーザー指定パスへのダウンロード（`--all` 対応、競合処理、ドライランあり）
062 系統のプログラミングインターフェース：CLI（`--json` 構造化出力）＋ 型付けされた非同期 Python API（`NotebookLMClient.from_storage()`、各種名前空間: notebooks/sources/chat/research/artifacts/mind_maps/notes/settings/sharing/labels/collections）
074 種類の認証パス：ブラウザ OAuth ログイン、ブラウザ Cookie 抽出（`--browser-cookies <browser>`）、master-token によるヘッドレス認証、CI 環境変数 JSON
08同一のビジネスロジックを共有するマルチフロントエンド：Click CLI、FastMCP MCP サーバー（リモート／OAuth トランスポート対応）、FastAPI REST サーバー、Android gRPC バックエンド
09自己インストール／検証：本 SKILL.md を `.claude/skills/notebooklm/SKILL.md` または `.agents/skills/notebooklm/SKILL.md` に配置し、配布アーカイブの作成やインストール済みバージョンと内容の乖離（drift）を検出
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | notebooklm CLI（本包 entry point，agent 全程调用它） |
| cli | pip / uv tool install / pipx（安装包本体，可选 extra 决定能力面） |
| cli | uv / uvx（桌面版 MCP 扩展启动器，用于拉起 notebooklm-mcp） |
| network | NotebookLM Web batchexecute RPC 端点（默认 notebook.google.com，可切 notebooklm.google.com / 企业域） |
| network | Google 账户与 OAuth 端点（浏览器登录 / master token 换取 / 令牌校验） |
| network | Google Drive 导入下载端点（加 Drive 源时拉文件） |
| network | Google APIs（Android 后端 Drive 暂存上传与请求） |
| api | gpsoauth（无头 master-token 认证，换取 Google 会话 cookie） |
| package | 运行时依赖 httpx / click / rich / filelock |
| package | 可选 extra：browser(playwright) / cookies(rookie-cookies) / headless(gpsoauth) / impersonate(curl_cffi) / android(grpcio+protobuf) / mcp(fastmcp==3.4.2) / server(fastapi+uvicorn+python-multipart) / markdown(markdownify) |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
隔離環境で実行、都度明示的な認可
管理者向け
厳格な認可、全量監査、コンプライアンス確認
判定根拠（ファイルパスと抜粋）
- 本地凭据 / 浏览器配置: ユーザーログイン Cookie／セッション／キーリングの読み取り: `~/.notebooklm/profiles/<profile>/storage_state.json`（Google セッション Cookie、デフォルト p
- scripts/: ローカルスクリプトまたはコマンドの実行: SKILL.md はホストシェル上で `pip install "notebooklm-py[browser]"` / `[c` を実行するようエージェントに指示
- scripts/ 或 SKILL.md: 外部言語パッケージ依存関係の動的インストールを宣言
- 网络端点: 外部ネットワークアクセスの宣言: https://notebook.google.com/_/LabsTailwindUi/data/batchexecute（デフォルトの Web RPC、
- 本地工作目录: ファイルの読み書きおよび成果物の出力: 成果物をユーザー指定パスへダウンロード（`notebooklm download <type> <path> -n <nb> -a <artifact>`）、SKI
監査ノート： およびそのアクション境界を検証。判定基準：本スキルは単なるプロンプトスキルではなく、大量の実コード（530 個の Python ファイル）を同梱し、ネットワーク RPC の実行、アカウントと同等の権限を持つ認証情報（storage_state.json / master_token.json / ブラウザ Cookie ストア）の読み取り、ユーザー指示によるファイル書き出し（成果物のダウンロード、.claude/skills への SKILL.md インストール）を行い、オプション機能では認証情報を含むサービスを MCP/REST ＋ Tailscale Funnel を通じて公開エンドポイントとして提供可能です。オレンジ／レッドに至らない理由：影響範囲は広いものの厳格に制限されています。認可境界（破壊的操作／ディスク書き込み／長時間の待機／`language set`／`--import-all` はユーザー確認が必須、「プロンプトなし ≠ 同意」）、ファイルパーミッション（0600/0700）、アトミック書き込み、読み取り専用診断フラグ `--passive`、終了コード規約、SECURITY.md に記載された運用者向け脅威モデルと脆弱性報告手順が整っており、Google サービスに対する非公式性も明記されています。グリーンではなくイエローとした主因は 2 点あります。認証情報がアカウントレベルであり漏洩時にパスワード変更による無効化が必要である点、および「ソース文書のコンテンツインジェクション」に対する隔離措置が存在しない点です（injection_surface 参照）。MCP/REST のパブリック公開を有効化している場合は、オレンジ相当（当該プロセスにアクセス可能な全ユーザーが該当 Google アカウントの NotebookLM 権限を保持することになる）として扱う必要があります。
5二重目の独立検証
- [ok] skill.path 定位 — 候选位置检查：仓库根有 SKILL.md（存在，314 行）；无 skills/ 目录、无 .claude/skills/、无 plugins/；另在包内发现它的分发副本位置 `notebooklm/data/SKILL.md`（构建期注入，非仓库源文件）。故按批次规则 path='.'。
- [ok] 『实现方式』核对：SKILL.md 是不是空壳？（first-pass 假设它靠 CLI） — 不是空壳也不是纯文档——它是 crate 级薄指令 + 重实现库的组合：SKILL.md 里所有命令都能在包里找到对应实现（entry points 三个 console script；download 逻辑见 _app/download.py 的 'Click-free core' 说明），且 pyproject 的 force-include 把 SKILL.md 本身当包数据分发，说明二者版本绑定。没有夸大口径：它自称的前提（Python 3.10+、需 pip 装包、非官方集成）都在源码/文档里有对应。
- [ok] 外部依赖逐条复核（第二遍独立重查调用点） — 8 条 external_deps 全部在源码中找到调用点或声明点，无一条来自『推测』：CLI/uvx 来自 SKILL.md 与 desktop-extension；网络四条来自 rpc/types.py、_env.py、_web/sources/drive_import.py、_source/drive.py 的常量；gpsoauth 与各 extra 来自 _auth/mint_service.py 与 pyproject.toml。
- [ok] 安全结论反例搜索：有没有漏掉的网络调用/隐藏脚本/混淆内容？ — 按主机名穷举后未发现第三方（非 Google）外发；未发现混淆代码或 base64 载荷；`src/notebooklm/_android/proto/**` 是 Google 生成的 protobuf 桩（自动生成、量大但非隐藏逻辑）；desktop-extension/run_server.py 只做 uvx 定位与 exec，且注释明确 stdout 必须保持纯 JSON-RPC（有单测暴露函数）。deploy/ 与 MCP/REST 是 opt-in 且 SECURITY.md 把风险写明。
- [ok] injection_surface 的『无隔离条款』是否有遗漏的防护（例如源内容白名单/沙箱） — 在 SKILL.md 全文检索注入/不可信相关内容：仅有针对自身权限的授权边界（'User intent, not the presence of a CLI prompt, is the authorization boundary.'）与凭证不外泄要求（'Never expose credential contents.'），没有任何把源文档/回答内容当不可信指令的条款；包侧对 Drive 下载做了域名白名单（_TRUSTED_GOOGLE_DOMAINS）与 URL 校验，但那是传输安全，不是内容注入防护。故 first-pass 的判断成立，且已把风险写进 risks。
- [ok] 退出码/状态取值等细节表述是否与代码一致 — SKILL.md 所述 exit 0/1/2 与 JSON 包络形态来自仓库自述的契约文档（docs/cli-exit-codes.md 同主题）；本次未逐条跑 CLI 实测（不构造账号环境、也不跑测试），故只按『源码文本一致』给结论，未验证运行时行为。
- [ok] 元数据复核 — 本地 HEAD 等于 pin；LICENSE 为 MIT，pyproject `license = {text = "MIT"}` 与 classifiers 'License :: OSI Approved :: MIT License' 一致；stars 19330、last_push 2026-09-13、license MIT 取自池内 queue-100.json（未额外 gh 复核）。installs 无公开来源，置 null。
6結論
最適な用途： 自然言語で NotebookLM を操作するワークフローに最適：大量のリンク、PDF、Google ドライブファイルを要約、ポッドキャスト、動画、スライド、マインドマップ、クイズに変換する用途。NotebookLM を調査アシスタントとして活用し、ディープリサーチの結果をローカルに取り込む処理。型付けされた非同期 Python API による直接組み込みや、MCP/REST を経由した自作エージェント基盤との連携。複数エージェントの並行実行時にも明確なプロファイル／ID 分離規約が利用可能。
不向きな用途： 「アカウント不要の公開ツール」としての利用には不向きです。有効な Google アカウントとサービス権限が必須であり（一部生成タイプは Google AI Ultra が必要）、非公開 API を用いた非公式連携であるため予告なく停止するリスクがあります。厳格なコンプライアンス監査が求められる環境には適しません（ローカル平文認証情報 ＋ 非公開 RPC ＋ シングルテナント前提の MCP/REST はエンタープライズのマルチテナント要件を満たしません）。信頼できない第三者に公開する環境には適しません（アカウント権限を共有するのと同義）。汎用 Gemini API の呼び出しのみを目的とするユーザーにも適しません（SKILL.md に「Do not use for the generic Gemini API or unrelated content creation.」と明記されています）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload notebooklm-python.tar.gz
sha256:
Option B · Copy Guide for Agent2231081c4d43c0ea…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 5472d7cfcc.