gpu4agents 0.5.0__py3-none-any.whl

gpu4agents/agent/skill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: gpu
+description: Rent a temporary cloud GPU, serve an open-weights model on it behind an OpenAI-compatible API, run experiments or evals against it, and shut it down so it stops billing. Use when the user wants to run, test, benchmark or compare a HuggingFace model (Qwen, Llama, Mistral, ...) on a GPU, needs an LLM endpoint for an experiment, or asks about GPU instances gpu/gpu4agents created. Works through the `gpu` MCP tools (gpu_setup, gpu_run, ...) or the `gpu` CLI.
+---
+
+# gpu: temporary GPUs for experiments
+
+`gpu` (the `gpu4agents` package) rents a machine on Vast.ai, serves a model with vLLM behind an OpenAI-compatible API, and installs a watchdog on the machine that stops it once nothing has used it for `idle_timeout` (15 min by default). A machine you forget stops by itself, so billing ends even if this conversation does.
+
+Each project directory has a `jambu.yaml` (what to rent and serve) and a `.gpu/` directory (what was rented). One project, one machine.
+
+## Two ways to drive it
+
+- **MCP tools** (`gpu_*`), when the `gpu` MCP server is connected. Prefer them.
+- **CLI**, from a shell: `gpu --json <command>` prints one JSON document on stdout; errors go to stderr as `error: ...` with a non-zero exit code. Run it from the project directory.
+
+| Step | MCP tool | CLI |
+| --- | --- | --- |
+| create jambu.yaml | `gpu_init(model)` | `gpu init --model ORG/NAME` |
+| check config and credentials | `gpu_validate` | `gpu --json validate` |
+| see prices, rent nothing | `gpu_offers` | `gpu --json offers` |
+| start / ensure ready | `gpu_setup` | `gpu --json setup` |
+| endpoint without starting | `gpu_connection` | `gpu --json env` |
+| run a job against it | `gpu_run(command=[...])` | `gpu run python job.py` |
+| state, cost, idle time | `gpu_status` | `gpu --json status` |
+| boot / server logs | `gpu_logs(source)` | `gpu --json logs --source onstart` |
+| stop (keep disk) | `gpu_stop` | `gpu --json stop` |
+| delete | `gpu_destroy(confirm=true)` | `gpu --json destroy --yes` |
+| everything billing in the account | `gpu_ls` | `gpu --json ls` |
+
+## Rules: this spends the user's money
+
+1. **Ask before renting.** Before the first `gpu_setup` / `gpu setup` / `gpu run` in a conversation, show the model, the GPU and the price (`gpu_offers`) and the cap (`budget.max_hourly_cost_usd`), and get a yes. Never raise the budget in `jambu.yaml` without asking.
+2. **Setup is slow, and that is normal.** The first setup takes 5–15 minutes (image pull, model download); a bad host is replaced automatically. The MCP `gpu_setup` returns `status: "running"` while it works: call it again to keep waiting. From a shell, run `gpu --json setup` in the background with no timeout. Never start a second project, `--recreate`, or destroy because setup is slow. `gpu_status` (it shows `busy: true` during setup) and `gpu_logs(source="onstart")` show progress. If the user wants to give up, `gpu_stop` or `gpu_destroy` cancel the setup and destroy the half-booted machine.
+3. **Never handle the provider key.** Do not print, echo or ask for `VAST_API_KEY`. It is read from the environment, the project `.env` or `~/.gpu/credentials`. If it is missing (exit code 5), tell the user where to put it.
+4. **Clean up.** When the work is done, offer `gpu_stop` (cheap to resume: about a minute, same key) or `gpu_destroy` (nothing billed; next time rents and downloads again). Destroy only with the user's explicit yes. Before finishing, run `gpu_ls` and report anything still running.
+
+## A typical experiment
+
+1. If there is no `jambu.yaml`: `gpu_init(model=..., max_hourly_cost_usd=...)`. Size the GPU for the model: about 2 GB of VRAM per billion parameters in bf16, plus room for the KV cache (a 7–9B model wants 24 GB; a 0.5–3B model fits on 16–24 GB). `gpu inspect-model ORG/NAME` suggests VRAM and a tool-call parser.
+2. `gpu_validate`, then `gpu_offers`. Show the user the price; ask.
+3. `gpu_setup` until `status: "ready"`. You get `base_url`, `api_key`, `model`.
+4. Run the work:
+   - a script: `gpu_run(command=["python", "eval.py"])` (or `gpu run python eval.py`). It gets `OPENAI_BASE_URL`, `OPENAI_API_KEY` and `JAMBU_MODEL_ID` in its environment, which any OpenAI SDK reads, and the watchdog keeps the machine up while it runs. Write the script to read those variables instead of pasting the key into code.
+   - single requests: `curl "$base_url/chat/completions" -H "Authorization: Bearer $api_key"` with `"model": model`. Every request counts as activity.
+5. Report results and cost (`gpu_status` has `session_cost_usd`), then step 4 of the rules.
+
+## When something fails
+
+Exit codes are the same for the CLI and the MCP tools (`exit_code` in the error):
+
+| Code | Meaning | Do |
+| --- | --- | --- |
+| 2 | config error, or jambu.yaml changed since setup | fix it; `gpu_setup(recreate=true)` replaces a machine built from the old config |
+| 3 | no machine / no endpoint | `gpu_setup` |
+| 4, 8 | provider API error or timeout | retry with backoff |
+| 5 | provider auth failed | the user fixes `VAST_API_KEY` |
+| 6 | no capacity matches | retry later, or relax `compute.gpu` / the budget (ask first) |
+| 7 | provisioning failed | retry; the failed machine is already destroyed |
+| 10 | over budget | ask the user before raising it |
+| 11 | model server did not start | the error carries the vLLM log tail: usually too little VRAM, a gated model without `HF_TOKEN`, or a bad `runtime` option. The machine was destroyed |
+| 12 | another gpu command (a setup) holds the project | follow it with `gpu_setup`; `gpu_stop` / `gpu_destroy` cancel it |
+
+- Requests fail with connection refused or a timeout: the machine was stopped for being idle. Call `gpu_setup` again (about a minute), take the **new** `base_url` from its output, and retry once.
+- `401`: a new machine was rented and the key changed; take it from `gpu_connection`.
+- A long job with quiet stretches longer than `idle_timeout`: `gpu_lock(duration="2h")`, then `gpu_unlock`.
+
+Full contract: https://github.com/jambuai/gpu4agents/blob/main/docs/INTEGRATION.md

gpu4agents/cli/_common.py

@@ -0,0 +1,131 @@
+"""Shared CLI plumbing: config loading, output and error rendering."""
+
+from __future__ import annotations
+
+import json as jsonlib
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from ..core.config import RuntimeConfig, load_config
+from ..core.engine import Engine
+from ..core.errors import JambuError
+from ..core.state import to_iso
+
+console = Console()
+err_console = Console(stderr=True)
+
+STATE_STYLES = {
+    "ready": "bold green",
+    "busy": "bold cyan",
+    "idle": "yellow",
+    "starting": "cyan",
+    "provisioning": "cyan",
+    "stopped": "dim",
+    "destroyed": "dim",
+    "failed": "bold red",
+    "unknown": "magenta",
+    "none": "dim",
+}
+
+
+class Context:
+    """Per-invocation state carried on the typer context object."""
+
+    def __init__(self) -> None:
+        self.config_path: Optional[Path] = None
+        self.json: bool = False
+        self.verbose: bool = False
+        self._config: Optional[RuntimeConfig] = None
+        self._engine: Optional[Engine] = None
+
+    def config(self) -> RuntimeConfig:
+        if self._config is None:
+            self._config = load_config(self.config_path)
+        return self._config
+
+    def engine(self) -> Engine:
+        if self._engine is None:
+            self._engine = Engine(self.config(), echo=self.echo)
+        return self._engine
+
+    def echo(self, message: str) -> None:
+        if self.json:
+            return
+        style = ""
+        if message.startswith("!"):
+            style = "yellow"
+        elif message.startswith("+"):
+            style = "green"
+        elif message.startswith("-"):
+            style = "red"
+        elif message.startswith(">"):
+            style = "cyan"
+        console.print(Text(message, style=style) if style else message)
+
+
+def get_context(ctx: typer.Context) -> Context:
+    if ctx.obj is None:
+        ctx.obj = Context()
+    return ctx.obj
+
+
+def fail(message: str, code: int = 1) -> None:
+    err_console.print(Text(f"error: {message}", style="bold red"))
+    raise typer.Exit(code)
+
+
+def handle(exc: Exception) -> None:
+    """Render a JambuError the same way regardless of which provider raised it."""
+    if isinstance(exc, JambuError):
+        err_console.print(Text(f"error: {exc}", style="bold red"))
+        raise typer.Exit(getattr(exc, "exit_code", 1))
+    raise exc
+
+
+def print_json(payload: Any) -> None:
+    sys.stdout.write(jsonlib.dumps(payload, indent=2, default=str) + "\n")
+
+
+def state_text(state: str) -> Text:
+    return Text(state.upper(), style=STATE_STYLES.get(state, "white"))
+
+
+def kv_table(title: str, rows: list[tuple[str, Any]]) -> Table:
+    table = Table(title=title, show_header=False, box=None, title_justify="left", pad_edge=False)
+    table.add_column("field", style="dim", no_wrap=True)
+    table.add_column("value")
+    for key, value in rows:
+        if value is None:
+            continue
+        table.add_row(key, value if isinstance(value, Text) else str(value))
+    return table
+
+
+def fmt_time(ts: Optional[float]) -> Optional[str]:
+    return to_iso(ts) if ts else None
+
+
+def fmt_money(value: Optional[float], suffix: str = "") -> Optional[str]:
+    if value is None:
+        return None
+    return f"${value:.3f}{suffix}"
+
+
+def register_project(context: Context) -> None:
+    """Put this project in $GPU_HOME/projects.json so `gpu sweep` guards it.
+
+    Done before provisioning: a setup that dies halfway must still leave an
+    instance the sweep judges by this project's policy, not as an orphan.
+    """
+    from ..core.sweep import register_project as _register
+
+    try:
+        _register(context.config())
+    except OSError as exc:
+        context.echo(f"! could not register the project for `gpu sweep`: {exc}")

gpu4agents/cli/account.py

@@ -0,0 +1,330 @@
+"""`gpu ls` / `gpu sweep` - every jambu instance in the account, not just this project's."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.table import Table
+from rich.text import Text
+
+from ..core import sweep as sweep_mod
+from ..core.config import RuntimeConfig, find_config
+from ..core.credentials import CredentialResolver
+from ..core.durations import format_duration, parse_duration
+from ..core.engine import Engine
+from ..core.errors import ConfigError, JambuError
+from ..core.events import EventLog
+from ..providers.registry import load_builtin_providers
+from . import timer
+from ._common import Context, console, fmt_money, get_context, handle, print_json, state_text
+
+DEFAULT_PROVIDER = "vast"
+
+
+class Account:
+    """A provider handle that works with or without a project around it."""
+
+    def __init__(self, context: Context, provider_name: Optional[str] = None) -> None:
+        self.config: Optional[RuntimeConfig] = None
+        if context.config_path is not None or find_config() is not None:
+            self.config = context.config()
+        if self.config is not None:
+            project_dir = self.config.project_dir
+            profile = self.config.provider.profile
+            name = provider_name or self.config.provider.name
+            config = self.config
+        else:
+            # No project: a placeholder config only carries the provider name.
+            project_dir = Path.cwd()
+            profile = "default"
+            name = provider_name or DEFAULT_PROVIDER
+            config = RuntimeConfig.model_validate(
+                {"provider": {"name": name}, "model": {"id": "jambu/account"}}
+            )
+        self.credentials = account_credentials(project_dir, profile)
+        self.provider = make_provider(config, self.credentials, name)
+
+    def project_paths(self) -> list[Path]:
+        """Registered projects, plus the one this command runs in (ad hoc)."""
+        paths = sweep_mod.ProjectRegistry().paths()
+        if self.config is not None and self.config.source_path is not None:
+            here = Path(self.config.source_path).resolve()
+            if here not in paths:
+                paths.append(here)
+        return paths
+
+
+def account_credentials(project_dir: Path, profile: str = "default") -> CredentialResolver:
+    """The environment, ./.env, ~/.gpu/credentials, then registered projects' .env.
+
+    The timer runs from ~ without the shell's environment; a key kept only in
+    a project's .env must still reach the account-wide orphan sweep.
+    """
+    extra = [
+        ("registered project .env", path.parent / ".env")
+        for path in sweep_mod.ProjectRegistry().paths()
+    ]
+    return CredentialResolver(project_dir, profile=profile, extra_sources=extra)
+
+
+def make_provider(config: RuntimeConfig, credentials: CredentialResolver, name: str):
+    """Seam for tests: they swap in a FakeProvider here."""
+    return load_builtin_providers().get(config, credentials, name=name)
+
+
+def make_engine(config: RuntimeConfig, echo=None) -> Engine:
+    """A project's own engine: its config, its credentials, its state."""
+    credentials = CredentialResolver(config.project_dir, profile=config.provider.profile)
+    provider = make_provider(config, credentials, config.provider.name)
+    return Engine(config, provider=provider, echo=echo, credentials=credentials)
+
+
+def ls_command(
+    ctx: typer.Context,
+    provider: Optional[str] = typer.Option(
+        None, "--provider", help="Provider to list (default: jambu.yaml's, else vast)."
+    ),
+) -> None:
+    """List every jambu instance in the provider account."""
+    context = get_context(ctx)
+    try:
+        account = Account(context, provider)
+        instances = sweep_mod.list_jambu_instances(account.provider)
+        owners = sweep_mod.tracked_by_projects(account.project_paths())
+    except JambuError as exc:
+        handle(exc)
+        return
+    name = account.provider.name
+    tracked = {iid: path for (pname, iid), path in owners.items() if pname == name}
+    rows = sweep_mod.account_rows(instances, tracked)
+
+    if context.json:
+        print_json({"provider": name, "instances": rows})
+        return
+    if not rows:
+        console.print(Text(f"no jambu instances on {account.provider.display_name}", style="dim"))
+        return
+    table = Table(title=f"{account.provider.display_name} instances", title_justify="left", box=None)
+    for column in ("ID", "LABEL", "STATE", "GPU", "$/H", "AGE", "PROJECT"):
+        table.add_column(column)
+    for row in rows:
+        table.add_row(
+            row["instance_id"],
+            row["label"],
+            state_text(row["state"]),
+            row["gpu"] or "-",
+            fmt_money(row["hourly_cost_usd"]) or "-",
+            format_duration(row["age_seconds"]),
+            Text(row["project"], style="green") if row["tracked"] else Text("orphan", style="yellow"),
+        )
+    console.print(table)
+
+
+def _seconds(flag: Optional[str], name: str) -> Optional[float]:
+    try:
+        return parse_duration(flag)
+    except ValueError as exc:
+        raise ConfigError(f"{name}: {exc}") from exc
+
+
+def sweep_command(
+    ctx: typer.Context,
+    apply: bool = typer.Option(False, "--apply", help="Act. Without it the sweep only reports."),
+    orphan_max_age: str = typer.Option(
+        "24h", "--orphan-max-age", help="Stop an untracked running instance older than this."
+    ),
+    stopped_ttl: str = typer.Option(
+        "24h", "--stopped-ttl", help="Destroy an untracked instance stopped longer than this."
+    ),
+    provider: Optional[str] = typer.Option(
+        None, "--provider", help="Provider to look for orphans on (default: jambu.yaml's, else vast)."
+    ),
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Also guard this project for this run, registered or not."
+    ),
+    install_timer: bool = typer.Option(
+        False, "--install-timer", help="Write a systemd user timer that runs the sweep."
+    ),
+    every: str = typer.Option("5m", "--every", help="Timer period for --install-timer."),
+    uninstall_timer: bool = typer.Option(
+        False, "--uninstall-timer", help="Remove the systemd user timer."
+    ),
+) -> None:
+    """Guard every registered project, then clean up orphans (dry run by default).
+
+    Each project registered by `gpu setup` is guarded with its own jambu.yaml
+    and state, exactly like `gpu guard` in that directory. An instance no
+    project tracks is an orphan: it is stopped (never destroyed) once it has
+    run longer than --orphan-max-age, and destroyed once it has been seen
+    stopped longer than --stopped-ttl. Instances without a jambu- label are
+    never touched.
+    """
+    context = get_context(ctx)
+    if config is not None:
+        context.config_path = config
+    try:
+        if install_timer or uninstall_timer:
+            _timer(context, install_timer, every)
+            return
+        _sweep(context, apply, orphan_max_age, stopped_ttl, provider)
+    except JambuError as exc:
+        handle(exc)
+
+
+def _require_file_credentials(context: Context) -> None:
+    """The unit runs without the shell's environment: refuse what it cannot see."""
+    checks: list[tuple[str, CredentialResolver, str]] = []
+    if context.config_path is not None or find_config() is not None:
+        cfg = context.config()
+        checks.append(
+            (
+                cfg.provider.name,
+                CredentialResolver(cfg.project_dir, profile=cfg.provider.profile),
+                str(cfg.source_path),
+            )
+        )
+    # The unit runs from ~ with no project: the orphan sweep's own lookup.
+    checks.append((DEFAULT_PROVIDER, account_credentials(Path.home()), "the orphan sweep"))
+    registry = load_builtin_providers()
+    for provider_name, resolver, who in checks:
+        for name in registry.get_class(provider_name).required_credentials:
+            if resolver.file_source(name):
+                continue
+            where = "only in your shell environment" if resolver.get(name) else "not set anywhere"
+            raise ConfigError(
+                f"{name} is {where}, so the timer could not use it for {who}: a systemd "
+                f"user unit does not inherit your shell. Put `{name}=...` in "
+                "~/.gpu/credentials (chmod 600), then re-run --install-timer."
+            )
+
+
+def _timer(context: Context, install: bool, every: str) -> None:
+    if not install:
+        result = timer.uninstall_timer()
+        if context.json:
+            print_json(result)
+            return
+        for path in result["removed"]:
+            console.print(Text(f"- removed {path}", style="red"))
+        if not result["removed"]:
+            console.print(Text("= no timer installed", style="dim"))
+        console.print(f"  then run: {result['disable']}")
+        return
+
+    every_s = _seconds(every, "--every")
+    if not every_s:
+        raise ConfigError("--every must be a positive duration, e.g. 5m")
+    registry = sweep_mod.ProjectRegistry()
+    project = None
+    if context.config_path is not None or find_config() is not None:
+        project = registry.register(context.config().source_path)
+    _require_file_credentials(context)
+    result = timer.install_timer(every_s)
+    # Units written before the registry carried one guard line per project.
+    for legacy in result["legacy_guard_configs"]:
+        if Path(legacy).is_file():
+            registry.register(Path(legacy))
+    result["project_config"] = str(project) if project else None
+    result["projects"] = [str(p) for p in registry.paths()]
+    if context.json:
+        print_json(result)
+        return
+    console.print(Text(f"+ wrote {result['service']}", style="green"))
+    console.print(Text(f"+ wrote {result['timer']}", style="green"))
+    if project:
+        console.print(Text(f"+ registered {project}", style="green"))
+    console.print(
+        f"  every {format_duration(result['every_s'])}: `gpu sweep --apply`, guarding "
+        f"{len(result['projects'])} registered project(s) and cleaning up orphans"
+    )
+    console.print(Text(f"> enable it: {result['enable']}", style="cyan"))
+    console.print(
+        Text(
+            "  user timers stop at logout unless lingering is on: loginctl enable-linger $USER",
+            style="dim",
+        )
+    )
+
+
+def _sweep(
+    context: Context,
+    apply: bool,
+    orphan_max_age: str,
+    stopped_ttl: str,
+    provider_name: Optional[str],
+) -> None:
+    orphan_max_age_s = _seconds(orphan_max_age, "--orphan-max-age")
+    stopped_ttl_s = _seconds(stopped_ttl, "--stopped-ttl")
+    account = Account(context, provider_name)
+    registry = sweep_mod.ProjectRegistry()
+    registered = registry.paths()
+    # A project whose jambu.yaml is gone has nothing left to guard it by.
+    gone = [p for p in registered if not p.is_file()]
+    registry.remove(gone)
+    for path in gone:
+        context.echo(f"- unregistered {path} (config file is gone)")
+    paths = [p for p in account.project_paths() if p not in gone]
+
+    if not context.json and paths:
+        context.echo(f"> guarding {len(paths)} project(s)" + ("" if apply else " (dry run)"))
+    guards, owned = sweep_mod.guard_projects(
+        paths, lambda cfg: make_engine(cfg, echo=context.echo), apply=apply, echo=context.echo
+    )
+    name = account.provider.name
+    tracked = {iid for (pname, iid) in owned if pname == name}
+
+    if not context.json:
+        context.echo(
+            f"> sweeping {account.provider.display_name} for orphans: running > "
+            f"{format_duration(orphan_max_age_s) if orphan_max_age_s else 'never'} is stopped, "
+            f"stopped > {format_duration(stopped_ttl_s) if stopped_ttl_s else 'never'} is destroyed"
+            + ("" if apply else " (dry run)")
+        )
+    try:
+        result = sweep_mod.sweep(
+            account.provider,
+            orphan_max_age_s=orphan_max_age_s,
+            stopped_ttl_s=stopped_ttl_s,
+            apply=apply,
+            tracked=tracked,
+            events=[EventLog(sweep_mod.jambu_home() / "logs").bind(provider=name)],
+            echo=context.echo,
+        )
+    except JambuError as exc:
+        # The projects were guarded already; report that, then fail the run.
+        if context.json:
+            print_json(
+                {
+                    "provider": name,
+                    "error": str(exc),
+                    "projects": [g.to_dict() for g in guards],
+                    "unregistered": [str(p) for p in gone],
+                }
+            )
+            raise typer.Exit(getattr(exc, "exit_code", 1)) from exc
+        raise
+    failed = any(a.error for a in result.actions) or any(g.error for g in guards)
+    if context.json:
+        payload = result.to_dict()
+        payload["projects"] = [g.to_dict() for g in guards]
+        payload["unregistered"] = [str(p) for p in gone]
+        print_json(payload)
+        if failed:
+            raise typer.Exit(1)
+        return
+    pending = [a for a in result.actions if a.action != "none"] + [
+        g for g in guards if (g.decision or {}).get("action", "none") != "none"
+    ]
+    if not pending:
+        console.print(
+            Text(
+                f"= {result.seen} jambu instance(s), {result.tracked} tracked, nothing to do",
+                style="green",
+            )
+        )
+    elif not apply:
+        console.print(Text(f"! {len(pending)} action(s) pending; re-run with --apply", style="yellow"))
+    if failed:
+        raise typer.Exit(1)

gpu4agents/cli/agent.py

@@ -0,0 +1,74 @@
+"""`gpu mcp` and `gpu agent` - let coding agents drive gpu."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.text import Text
+
+from ..core.errors import JambuError
+from ._common import console, get_context, handle, print_json
+
+agent_app = typer.Typer(
+    help="Give Claude Code, Cursor or Claude Desktop the gpu skill and MCP tools.",
+    no_args_is_help=True,
+)
+
+
+def mcp_command(
+    project: Optional[Path] = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Default project directory for the tools (default: $GPU_PROJECT_DIR, else the cwd).",
+    ),
+) -> None:
+    """Run the local MCP server on stdio (started by the agent's client, not by hand)."""
+    from ..agent.mcp import Server
+
+    Server(project=project).serve()
+
+
+@agent_app.command("install")
+def install_command(
+    ctx: typer.Context,
+    target: List[str] = typer.Option(
+        ["claude"],
+        "--target",
+        "-t",
+        help="claude (Claude Code), cursor, desktop (Claude Desktop). Repeat for several.",
+    ),
+    global_scope: bool = typer.Option(
+        False, "--global", "-g", help="For every project of this user, not just this directory."
+    ),
+    directory: Path = typer.Option(
+        Path("."), "--dir", help="Project directory (default: the current one)."
+    ),
+) -> None:
+    """Install the gpu skill and register the gpu MCP server."""
+    from ..agent.install import install
+
+    context = get_context(ctx)
+    try:
+        result = install(list(target), directory, global_scope=global_scope)
+    except JambuError as exc:
+        handle(exc)
+        return
+    if context.json:
+        print_json(result)
+        return
+    for item in result["installed"]:
+        style = "dim" if item["action"] == "unchanged" else "green"
+        console.print(Text(f"+ {item['what']}: {item['path']} ({item['action']})", style=style))
+    for note in result["notes"]:
+        console.print(Text(f"  {note}", style="cyan"))
+
+
+@agent_app.command("skill")
+def skill_command() -> None:
+    """Print the bundled SKILL.md (to copy into another agent's skill directory)."""
+    from ..agent.install import skill_text
+
+    print(skill_text(), end="")