docs: clarify how to install shiny's bundled Agent Skills (#2447)

Author: schloerke

.claude/references/agent-skills.md

@@ -6,8 +6,9 @@ specification](https://agentskills.io/specification). Its `SKILL.md` is a
 grouped router: a short index of topics, each pointing at a
 `references/<topic>.md` file with the actual instructions. It is **package
 data**: it ships in the wheel and is discovered by installers such as
-[library-skills](https://library-skills.io) (which symlinks it into a
-project's `.agents/skills/` or `.claude/skills/`). The `shiny skills
+[library-skills](https://library-skills.io), which a user runs from *their*
+project (not from a clone of this repo) to symlink the skills of their
+installed dependencies into `.agents/skills/` or `.claude/skills/`. The `shiny skills
 list|path` CLI subcommands (implemented in `shiny/_main/_skills.py`) are a
 zero-dependency way to inspect it: `list` shows each bundled skill's name and
 description, and `path <name>` prints the skill's directory so its `SKILL.md`

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Improvements
 
+* The README and the `shiny skills` CLI help now explain that [`library-skills`](https://library-skills.io) must be run from your own project directory, since it installs the bundled Agent Skills of the packages that project has installed. The previous wording left that precondition implicit, so running the command from an empty directory or from a clone of py-shiny silently installed nothing. (#2447)
+
 * Navsets created with an `id` (e.g. `ui.navset_tab(id="tabs")`) now use that `id` as their `data-tabsetid`, so their tab panes get stable `tab-tabs-0` style DOM ids instead of ones built from a random integer. This makes the rendered markup reproducible across renders and easier to target from custom CSS and JavaScript. Navsets without an `id`, and `ui.nav_menu()` dropdowns, keep the random ID. (Thanks, @pevolution-ahmed!) (#2410)
 
 ### Bug fixes

README.md

@@ -40,17 +40,21 @@ You can create and run your first application with `shiny create`, the CLI will
 
 ### Agent Skills
 
-The `shiny` package ships bundled [Agent Skills](https://agentskills.io) — reference docs that teach coding agents (Claude Code, Cursor, and others) how to build, style, test, and debug Shiny for Python apps using shiny's public APIs. They are installed with the package, so once `shiny` is a dependency of your project you can make the skills available to your agent with [`library-skills`](https://library-skills.io):
+Coding agents write better Shiny apps when they can read Shiny's own documentation. The `shiny` package ships bundled [Agent Skills](https://agentskills.io) for exactly that: reference material that teaches agents (Claude Code, Cursor, and others) how to build, style, test, and debug Shiny for Python apps using shiny's public APIs.
+
+The skills ship inside the package, so installing `shiny` installs them too — you only need to point your agent at them. Run one of these from your project directory:
 
 ```sh
-# Claude Code (installs into .claude/skills):
+# Claude Code (installs into .claude/skills/):
 uvx library-skills --claude
 
-# Standard .agents/skills location (add --copy on Windows):
+# Any other agent (standard .agents/skills/ location):
 uvx library-skills
 ```
 
-`library-skills` symlinks the packaged skill into your project, so it stays in sync when you upgrade `shiny`. See `shiny skills --help` for more details.
+Run this from your own project rather than a clone of this repository: [`library-skills`](https://library-skills.io) reads your project's dependencies and installs the skills bundled with the packages you actually have installed. It symlinks rather than copies, so the skills keep tracking your version of `shiny` as you upgrade. On Windows, add `--copy` if symlinks are unavailable.
+
+To see what's bundled without installing anything, run `shiny skills list`.
 
 ## Development
 

shiny/_main/_skills.py

@@ -55,17 +55,18 @@ def _find_skill(name: str) -> Path:
 
     Agent Skills are reference docs that teach coding agents how to use shiny's
     public APIs (debugging, testing, etc.). They ship inside the package under
-    `shiny/.agents/skills/`.
+    `shiny/.agents/skills/`, so installing shiny installs them too.
 
-    To make these skills available to your coding agent, install them with
-    `library-skills` (https://library-skills.io), which symlinks the packaged
-    skill into your project so it stays in sync when you upgrade shiny:
+    To make them available to your coding agent, run `library-skills`
+    (https://library-skills.io) from your project directory. It reads your
+    project's dependencies and symlinks the skills bundled with the packages you
+    have installed, so they keep tracking your version of shiny as you upgrade:
 
     \b
         uvx library-skills --claude   # Claude Code (installs into .claude/skills)
-        uvx library-skills            # standard .agents/skills location
+        uvx library-skills            # any other agent (.agents/skills)
 
-    (add `--copy` on Windows).
+    (add `--copy` on Windows if symlinks are unavailable).
     """,
 )
 def skills() -> None:
@@ -82,9 +83,10 @@ def skills_list() -> None:
     for skill_dir in skill_dirs:
         print(f"{skill_dir.name:<{width}}  {_skill_description(skill_dir)}")
     print(
-        "\nInstall these into your coding agent with `library-skills`:\n"
+        "\nThese ship with the shiny package. To install them into your coding\n"
+        "agent, run `library-skills` from your project directory:\n"
         "    uvx library-skills --claude   # Claude Code (.claude/skills)\n"
-        "    uvx library-skills            # standard .agents/skills location\n"
+        "    uvx library-skills            # any other agent (.agents/skills)\n"
         "See https://library-skills.io for details."
     )