feat(cli): add skilld run for transient Skills

CLAUDE.md

@@ -24,9 +24,12 @@ cargo clippy --workspace --all-targets -- -D warnings
 
 ## Product boundary
 
-The native `skilld` CLI searches, installs, lists, views, removes, updates, and verifies Skills.
+The native `skilld` CLI searches, runs, installs, lists, views, removes, updates, and verifies Skills.
 It also manages account authentication and Agent target configuration.
 
+`skilld run` loads a transient Skill: it prints the Skill and installs nothing.
+The calling Agent follows the instructions. The CLI never executes them.
+
 The skilld CLI contains no Skill generation logic or Agent runtime.
 
 `skilld-harness` runs visible skilld-maintained Skills for generation and review.

CONTEXT.md

@@ -6,7 +6,7 @@ Use the terms in `GLOSSARY.md` exactly.
 
 - The skilld CLI is Rust.
 - skilld-maintained Skills support direct Agent generation, review, search, and install.
-- `skilld install skilld --global` installs search and install guidance for Agents.
+- `skilld install skilld --global` installs search, run, and install guidance for Agents.
 - Harness is the JavaScript `skilld-harness` package.
 - `skilld.dev` resolves Repositories into Artifacts with attestations.
 

GLOSSARY.md

@@ -9,6 +9,7 @@ Every public export, command, error, route, and document uses these terms.
 | Term | Export or owner | Stability | Consumers | Customer word |
 | --- | --- | --- | --- | --- |
 | Skill | Agent Skills specification | external standard | Agent, skilld CLI, Harness | Skill |
+| transient Skill | `skilld run` | published command | Agent, developer | transient Skill |
 | skilld-maintained Skill | `skills/*` | published asset | Agent, Harness | skilld-maintained Skill |
 | skilld CLI | `skilld` | published CLI | developer, CI | skilld CLI |
 | Harness | `skilld-harness` | published package | application, CI | Harness |
@@ -25,6 +26,8 @@ Every public export, command, error, route, and document uses these terms.
 | Identifier | Term |
 | --- | --- |
 | `skilld search` | Skill search |
+| `skilld run` | transient Skill load |
+| `skilld run --file` | supporting file read |
 | `skilld install` | Skill install |
 | `skilld list` | installed Skills |
 | `skilld view` | Skill details |
@@ -72,7 +75,10 @@ flowchart LR
 
 Collisions
 
-None recorded.
+`Skill run` and `transient Skill` sound alike and mean different things.
+A Skill run is one Harness execution.
+A transient Skill is one Skill that `skilld run` loads for a session.
+The Rust type for the second is `TransientSkill`, never `SkillRun`.
 
 ## Terms
 
@@ -96,6 +102,16 @@ None recorded.
 
 **Casing:** `skilld-maintained Skill` in prose.
 
+### transient Skill
+
+**Is:** a Skill that `skilld run` loads for the current Agent session.
+
+**Use for:** any Skill used without an install. A remote transient Skill never reaches disk.
+
+**Never:** ephemeral skill, temporary install, one-off install, Skill run.
+
+**Casing:** `transient Skill` in prose, `TransientSkill` in Rust.
+
 ### skilld CLI
 
 **Is:** the Rust command line interface that searches, installs, updates, and removes Skills.

README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld)
 [![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/skilld-dev/skilld/blob/main/LICENSE)
 
-Search, install, and keep Agent Skills current.
+Search, run, install, and keep Agent Skills current.
 
 skilld v3 has two products:
 
@@ -22,7 +22,13 @@ npm install --global skilld
 The npm package selects a native executable for the current system.
 It has no JavaScript CLI engine or JavaScript fallback.
 
-Install the skilld-maintained Skill for your Agent:
+Ask your Agent to run the skilld-maintained Skill for the current session:
+
+```sh
+skilld run skilld
+```
+
+Install it only when you want your Agent to keep it across sessions:
 
 ```sh
 skilld install skilld --global
@@ -34,12 +40,52 @@ Use `--agent` when you want an explicit Agent target:
 skilld install skilld --global --agent codex
 ```
 
+## Run a Skill without installing it
+
+`skilld run` is the default way to use a Skill.
+It prints `SKILL.md` to stdout.
+Ask your Agent to run the command and follow the printed instructions.
+If you run it yourself, pass the output to your Agent.
+
+```sh
+npx skilld run skilld:skilld-dev/skills/vue
+```
+
+A remote run writes no Skill files.
+It creates no lockfile entry, Agent target, project file, or Skill cache.
+The command retains no Skill files after it exits.
+
+skilld names the supporting files a Skill carries and prints none of them.
+Read one when the instructions call for it:
+
+```sh
+npx skilld run skilld:skilld-dev/skills/vue --revision <commit> --file references/api.md
+```
+
+Use the revision and file-read command from the initial output.
+skilld never prints executable or binary files.
+A Skill that must run its own script needs an install.
+
+Install the Skill when you want it in every session:
+
+```sh
+skilld install skilld:skilld-dev/skills/vue
+```
+
+An install writes files. Ask the user first.
+
 ## Use the skilld CLI
 
 ```sh
 # Find a Skill
 skilld search vue
 
+# Run a Skill for this session only
+skilld run skilld:skilld-dev/skills/vue
+
+# Read one supporting file that Skill carries
+skilld run skilld:skilld-dev/skills/vue --revision <commit> --file references/api.md
+
 # Install a Skill in the current project
 skilld install skilld:skilld-dev/skills/vue
 
@@ -84,6 +130,7 @@ The API does not expose private storage addresses.
 ### Direct mode
 
 `--direct` fetches a public GitHub Repository without the skilld.dev API.
+Explicit GitHub selectors use hosted Artifact delivery unless you add `--direct`.
 
 ```sh
 skilld install github:skilld-dev/skilld/skills/skilld --direct --agent codex
@@ -95,6 +142,9 @@ The user reviews the Skill before use.
 Direct mode never handles private Repositories.
 It never falls back to skilld.dev.
 
+Generated commands use POSIX shell quoting on Unix.
+They use PowerShell quoting on Windows.
+
 ## Source status
 
 - `verified`: skilld checked a skilld.dev Artifact and its attestation.