feat(cli): unify agent skill installation

Author: teng-lin

README.md

@@ -27,7 +27,7 @@
 
 ## What You Can Build
 
-🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code or other LLM agents. Ships with [Claude Code skills](#agent-skills-claude-code) for natural language automation (`notebooklm skill install`), or build your own integrations with the async Python API.
+🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code, Codex, and other compatible agent-skill runtimes. Ships with a root [NotebookLM skill](SKILL.md) for GitHub and `npx skills add` discovery, plus `notebooklm skill install` for local agent directories.
 
 📚 **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.
 
@@ -159,7 +159,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
@@ -195,18 +195,25 @@ async def main():
 asyncio.run(main())
 ```
 
-### Agent Skills (Claude Code)
+### Agent Skills
 
 ```bash
-# Install via CLI or ask Claude Code to do it
+# Install into local user-level Claude + .agents skill directories
 notebooklm skill install
 
-# 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 / `npx skills add` 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`.
+
 ## Documentation
 
 - **[CLI Reference](docs/cli-reference.md)** - Complete command documentation

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`.
 
 ### Features Beyond the Web UI
 

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

@@ -82,6 +82,7 @@ replacement = '](https://github.com/teng-lin/notebooklm-py/blob/v$HFPR_VERSION/L
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/notebooklm"]
+force-include = {"SKILL.md" = "src/notebooklm/data/SKILL.md"}
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]