feat: Add shiny skills CLI subcommand (list/get/path) (#2343)

Author: schloerke

.claude/references/agent-skills.md

@@ -5,8 +5,11 @@ The shiny package ships [Agent Skills](https://agentskills.io) under
 following the [Agent Skills specification](https://agentskills.io/specification).
 They are **package data**: they ship in the wheel and are discovered by
 installers such as [library-skills](https://library-skills.io) (which symlinks
-them into a project's `.agents/skills/` or `.claude/skills/`). A `shiny skills
-list|get` CLI subcommand is planned as a zero-dependency way to read them.
+them into a project's `.agents/skills/` or `.claude/skills/`). The `shiny
+skills list|get|path` CLI subcommands (implemented in `shiny/_main_skills.py`)
+are a zero-dependency way to read them: `get <name>` prints the SKILL.md, and
+`path <name>` prints the skill's directory so supporting files
+(`references/`, `scripts/`) can be read from the installed package.
 
 **Audience:** coding agents *using* shiny to build, test, and debug apps — not
 contributors to shiny itself. Contributor-facing guidance belongs in

CHANGELOG.md

@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * The shiny package now ships [Agent Skills](https://agentskills.io) under `shiny/.agents/skills/` (the [library-skills](https://library-skills.io) convention), starting with a `debugging` skill that teaches coding agents to inspect running apps via test mode, `shiny.testmode.export_test_values()`, and the test snapshot endpoint. (#2339)
 
+* Added a `shiny skills` CLI command group to discover the Agent Skills bundled in the shiny package: `shiny skills list` shows each skill's name and description, `shiny skills get <name>` prints its `SKILL.md` to stdout, and `shiny skills path <name>` prints the skill's directory (for reading its `references/` and `scripts/`). (#2340)
+
 * Added `offcanvas()` for creating sliding Bootstrap Offcanvas panels that appear from a viewport edge. Panels can be triggered by a UI element, revealed programmatically with `show_offcanvas()`, or controlled by id with `hide_offcanvas()` and `toggle_offcanvas()`. (#2279)
 
 ### Improvements

shiny/_main.py

@@ -21,6 +21,7 @@
 
 from . import __version__, _autoreload, _launchbrowser, _static, _utils
 from ._docstring import no_example
+from ._main_skills import skills
 from ._uvicorn import (
     ReloadArgs,
     _run_uvicorn,
@@ -38,6 +39,9 @@ def main() -> None:
     pass
 
 
+main.add_command(skills)
+
+
 stop_shortcut = "Ctrl+C"
 
 RELOAD_INCLUDES_DEFAULT = (

shiny/_main_skills.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+SKILLS_DIR = Path(__file__).parent / ".agents" / "skills"
+"""Location of the Agent Skills bundled in the shiny package."""
+
+
+def _available_skills() -> list[Path]:
+    if not SKILLS_DIR.is_dir():
+        return []
+    return sorted(
+        p for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").is_file()
+    )
+
+
+def _skill_description(skill_dir: Path) -> str:
+    """Extract the one-line `description:` from a SKILL.md's YAML frontmatter."""
+    text = (skill_dir / "SKILL.md").read_text()
+    if not text.startswith("---\n"):
+        return ""
+    frontmatter = text.split("---", 2)[1]
+    for line in frontmatter.splitlines():
+        if line.startswith("description:"):
+            return line.removeprefix("description:").strip()
+    return ""
+
+
+def _find_skill(name: str) -> Path:
+    """Return the directory of the named skill, or raise a helpful error."""
+    skill_dirs = _available_skills()
+    if not skill_dirs:
+        raise click.ClickException(
+            "No skills are bundled in this installation of shiny."
+        )
+    skill_dir = next((p for p in skill_dirs if p.name == name), None)
+    if skill_dir is None:
+        available = ", ".join(p.name for p in skill_dirs)
+        raise click.ClickException(
+            f"Unknown skill {name!r}. Available skills: {available}"
+        )
+    return skill_dir
+
+
+@click.group(
+    "skills",
+    help="""List and read the Agent Skills bundled in the shiny package.
+
+    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/`.
+    """,
+)
+def skills() -> None:
+    pass
+
+
+@skills.command("list", help="List the bundled Agent Skills.")
+def skills_list() -> None:
+    skill_dirs = _available_skills()
+    if not skill_dirs:
+        print("No skills are bundled in this installation of shiny.")
+        return
+    width = max(len(p.name) for p in skill_dirs)
+    for skill_dir in skill_dirs:
+        print(f"{skill_dir.name:<{width}}  {_skill_description(skill_dir)}")
+
+
+@skills.command("get", help="Print a bundled Agent Skill's SKILL.md to stdout.")
+@click.argument("name", type=str)
+def skills_get(name: str) -> None:
+    sys.stdout.write((_find_skill(name) / "SKILL.md").read_text())
+
+
+@skills.command(
+    "path",
+    help="""Print the directory of a bundled Agent Skill.
+
+    Use this to read a skill's supporting files (`references/`, `scripts/`,
+    `assets/`) directly from the installed package.
+    """,
+)
+@click.argument("name", type=str)
+def skills_path(name: str) -> None:
+    print(_find_skill(name))

tests/pytest/test_main_skills.py

@@ -0,0 +1,75 @@
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from shiny import _main_skills
+from shiny._main import main
+
+SKILLS_DIR = Path(_main_skills.__file__).parent / ".agents" / "skills"
+
+
+def test_skills_list_shows_names_and_descriptions() -> None:
+    result = CliRunner().invoke(main, ["skills", "list"])
+
+    assert result.exit_code == 0
+    assert "debugging" in result.output
+    # The one-line description from the skill's frontmatter is shown
+    debugging_line = next(
+        line for line in result.output.splitlines() if "debugging" in line
+    )
+    assert "test mode" in debugging_line or "debugging a Shiny" in debugging_line
+
+
+def test_skills_get_prints_skill_md() -> None:
+    result = CliRunner().invoke(main, ["skills", "get", "debugging"])
+
+    assert result.exit_code == 0
+    expected = (SKILLS_DIR / "debugging" / "SKILL.md").read_text()
+    assert result.output == expected
+
+
+def test_skills_get_unknown_name_lists_available_skills() -> None:
+    result = CliRunner().invoke(main, ["skills", "get", "does-not-exist"])
+
+    assert result.exit_code != 0
+    assert "does-not-exist" in result.output
+    assert "debugging" in result.output
+
+
+def test_skills_path_prints_skill_directory() -> None:
+    result = CliRunner().invoke(main, ["skills", "path", "debugging"])
+
+    assert result.exit_code == 0
+    assert result.output == f"{SKILLS_DIR / 'debugging'}\n"
+    assert Path(result.output.strip()).is_absolute()
+
+
+def test_skills_path_unknown_name_lists_available_skills() -> None:
+    result = CliRunner().invoke(main, ["skills", "path", "does-not-exist"])
+
+    assert result.exit_code != 0
+    assert "does-not-exist" in result.output
+    assert "debugging" in result.output
+
+
+def test_skills_list_with_empty_skills_dir(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(_main_skills, "SKILLS_DIR", tmp_path)
+
+    result = CliRunner().invoke(main, ["skills", "list"])
+
+    assert result.exit_code == 0
+    assert "No skills" in result.output
+
+
+def test_skills_get_with_missing_skills_dir(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(_main_skills, "SKILLS_DIR", tmp_path / "nope")
+
+    result = CliRunner().invoke(main, ["skills", "get", "debugging"])
+
+    assert result.exit_code != 0
+    assert "No skills" in result.output