Merge pull request teng-lin#207 from teng-lin/improve/skill-installation-for-other-agents

feat: unify skill installation across agents

Author: teng-lin

README.md

@@ -27,7 +27,7 @@
 
 ## What You Can Build
 
-🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code, Codex, and other LLM agents. Ships with a [Claude Code skill](#agent-setup) (`notebooklm skill install`) and repo-level Codex instructions in [`AGENTS.md`](AGENTS.md), or build your own integrations with the async Python API.
+🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code, Codex, and other LLM agents. Ships with a root [NotebookLM skill](SKILL.md) for GitHub and `npx skills add` discovery, local `notebooklm skill install` support for Claude Code and `.agents` skill directories, and repo-level Codex guidance in [`AGENTS.md`](AGENTS.md).
 
 📚 **Research Automation** - Bulk-import sources (URLs, PDFs, YouTube, Google Drive), run web/Drive research queries with auto-import, and extract insights programmatically. Build repeatable research pipelines.
 
@@ -165,7 +165,7 @@ notebooklm language list             # List supported output languages
 notebooklm metadata --json           # Export notebook metadata and sources
 notebooklm share status              # Inspect sharing state
 notebooklm source add-research "AI"  # Start web research and import sources
-notebooklm skill status              # Check Claude Code skill installation
+notebooklm skill status              # Check local agent skill installation
 ```
 
 ### Python API
@@ -206,16 +206,23 @@ asyncio.run(main())
 #### Claude Code
 
 ```bash
-# Install via CLI or ask Claude Code to do it
+# Install into local user-level Claude + .agents skill directories
 notebooklm skill install
 notebooklm agent show claude
 
-# Then use natural language:
-# "Create a podcast about quantum computing"
-# "Download the quiz as markdown"
-# "/notebooklm generate video"
+# Install only the universal .agents/skills target in the current project
+notebooklm skill install --scope project --target agents
+
+# Install from GitHub via the open skills ecosystem
+npx skills add teng-lin/notebooklm-py
 ```
 
+Supported paths:
+
+- `notebooklm skill install` manages local `~/.claude/skills/notebooklm` and `~/.agents/skills/notebooklm` by default.
+- GitHub and `npx skills add teng-lin/notebooklm-py` discover the canonical root [SKILL.md](SKILL.md).
+- Agents that honor `.agents/skills` can consume the universal install path; Claude Code also supports `.claude/skills`.
+
 #### Codex
 
 Codex reads repo-level instructions from [`AGENTS.md`](AGENTS.md), so there is no separate install command. After installing dependencies and authenticating, ask Codex to use the `notebooklm` CLI or Python API directly.

src/notebooklm/data/SKILL.md SKILL.mdsrc/notebooklm/data/SKILL.md renamed to SKILL.md

@@ -23,7 +23,13 @@ pip install "git+https://github.com/teng-lin/notebooklm-py@${LATEST_TAG}"
 
 ⚠️ **DO NOT install from main branch** (`pip install git+https://github.com/teng-lin/notebooklm-py`). The main branch may contain unreleased/unstable changes. Always use PyPI or a specific release tag, unless you are testing unreleased features.
 
-After installation, install the Claude Code skill:
+**Skill install methods:**
+
+- `notebooklm skill install` installs this skill into the supported local agent directories managed by the CLI.
+- `npx skills add teng-lin/notebooklm-py` installs this skill from the GitHub repository into compatible agent skill directories.
+- If you are already reading this file inside an agent skill directory, the skill is already installed. You only need the Python package and authentication below.
+
+**CLI-managed install:**
 ```bash
 notebooklm skill install
 ```
@@ -560,4 +566,4 @@ notebooklm language --help     # Language settings
 **Diagnose auth:** `notebooklm auth check` - shows cookie domains, storage path, validation status
 **Re-authenticate:** `notebooklm login`
 **Check version:** `notebooklm --version`
-**Update skill:** `notebooklm skill install`
+**Refresh a CLI-managed install:** `notebooklm skill install`

docs/cli-reference.md

@@ -195,16 +195,23 @@ notebooklm metadata -n abc123 --json
 
 ### Skill Commands (`notebooklm skill <cmd>`)
 
-Manage Claude Code skill integration.
+Manage NotebookLM agent skill integration.
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `install` | Install/update skill to ~/.claude/skills/ | `skill install` |
-| `status` | Check installation and version | `skill status` |
-| `uninstall` | Remove skill | `skill uninstall` |
-| `show` | Display skill content | `skill show` |
+| `install` | Install/update the skill for `claude`, `.agents`, or both | `skill install --target all` |
+| `status` | Check installed targets and version info | `skill status --scope project` |
+| `uninstall` | Remove one or more installed targets | `skill uninstall --target agents` |
+| `show` | Display the packaged skill or an installed target | `skill show --target source` |
 
-After installation, Claude Code recognizes NotebookLM commands via `/notebooklm` or natural language like "create a podcast about X".
+Defaults:
+
+- `skill install` uses `--scope user --target all`
+- `claude` maps to `.claude/skills/notebooklm/SKILL.md`
+- `agents` maps to `.agents/skills/notebooklm/SKILL.md`
+- `show --target source` prints the canonical packaged skill file
+
+The packaged wheel includes the repo-root `SKILL.md`, so the same skill content powers `notebooklm skill install`, GitHub discovery, and `npx skills add teng-lin/notebooklm-py`.
 
 Codex does not use the `skill` subcommand. In this repository it reads the root [`AGENTS.md`](../AGENTS.md) file and invokes the `notebooklm` CLI or Python API directly.
 

docs/releasing.md

@@ -77,7 +77,7 @@ Proceed with release preparation?
 | Doc | Update when... |
 |-----|----------------|
 | [README.md](../README.md) | New features, changed capabilities, Beyond the Web UI section |
-| [SKILL.md](../src/notebooklm/data/SKILL.md) | New CLI commands, changed flags, new workflows |
+| [SKILL.md](../SKILL.md) | New CLI commands, changed flags, new workflows |
 | [cli-reference.md](cli-reference.md) | Any CLI changes |
 | [python-api.md](python-api.md) | New/changed Python API |
 | [troubleshooting.md](troubleshooting.md) | New known issues, fixed issues to remove |

pyproject.toml

@@ -80,8 +80,13 @@ replacement = '](https://github.com/teng-lin/notebooklm-py/blob/v$HFPR_VERSION/S
 pattern = '\]\(LICENSE\)'
 replacement = '](https://github.com/teng-lin/notebooklm-py/blob/v$HFPR_VERSION/LICENSE)'
 
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\]\(SKILL\.md\)'
+replacement = '](https://github.com/teng-lin/notebooklm-py/blob/v$HFPR_VERSION/SKILL.md)'
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/notebooklm"]
+force-include = {"SKILL.md" = "notebooklm/data/SKILL.md", "AGENTS.md" = "notebooklm/data/CODEX.md"}
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

src/notebooklm/cli/agent_templates.py

@@ -9,13 +9,14 @@
 }
 
 REPO_ROOT_AGENTS = Path(__file__).resolve().parents[3] / "AGENTS.md"
+REPO_ROOT_CLAUDE_SKILL = Path(__file__).resolve().parents[3] / "SKILL.md"
 
 
 def _read_package_data(filename: str) -> str | None:
     """Read a packaged agent template file."""
     try:
         return (resources.files("notebooklm") / "data" / filename).read_text(encoding="utf-8")
-    except (FileNotFoundError, TypeError):
+    except (FileNotFoundError, TypeError, ModuleNotFoundError):
         return None
 
 
@@ -28,6 +29,11 @@ def get_agent_source_content(target: str) -> str | None:
     if normalized == "codex" and REPO_ROOT_AGENTS.exists():
         return REPO_ROOT_AGENTS.read_text(encoding="utf-8")
 
+    # Prefer the repo-root skill when running from a source checkout so both
+    # GitHub discovery and local CLI installs use the same source of truth.
+    if normalized == "claude" and REPO_ROOT_CLAUDE_SKILL.exists():
+        return REPO_ROOT_CLAUDE_SKILL.read_text(encoding="utf-8")
+
     filename = AGENT_TEMPLATE_FILES.get(normalized)
     if filename is None:
         return None