25 added, 7 removed. Audit A to A.
---
name: skilld
description: Search, run, view, install, update, verify, and remove Skills with skilld CLI, including private repository access.
---
# Use skilld CLI
Use skilld CLI to search for, run, and install Skills.
Run a Skill first. Install a Skill only when the user asks to keep it.
## Search for a Skill
Run a focused search:
```sh
skilld search <query> --json
```
Read `data.items` before choosing a Skill.
Use each item's `selector` for install.
Refine the query when several Skills cover different tasks.
Always use `--json` when an Agent runs Skill search.
Check the exit code before reading stdout.
If search fails, read the tagged JSON error from stderr.
Use `--plain` only when another command needs stable text.
Never parse formatted terminal output.
## Run a Skill
Run the selector returned by search:
```sh
- skilld run <selector>
+ skilld run <selector> --json
```
- The command prints the Skill and installs nothing.
+ The command prints SKILL.md and writes nothing to disk.
Read the printed SKILL.md, then follow it for the current task.
- The output names a directory that holds the supporting files.
- Read a supporting file from that directory when the instructions name it.
-
Prefer `skilld run` for a one-off task.
- Report which Skill you ran and that nothing was installed.
- If the source status is `unverified`, tell the user before you follow the Skill.
+ Read `data.files` for the supporting files the Skill carries.
+ skilld prints none of them.
+ Read one only when the instructions name it:
+ ```sh
+ skilld run <selector> --file <path> --json
+ ```
+
+ Use the exact path from `data.files[].path`.
+ Repeat `--file` to read several files in one command.
+
+ Check `data.files[].readable` before you ask for a file.
+ A file with `readable: false` never prints.
+ Its `kind` is `executable` or `binary`.
+ Tell the user the Skill needs an install to use that file.
+
+ Report which Skill you ran and that nothing was installed.
+ Read `data.sourceStatus` before you follow the Skill.
+ A `verified` status covers where the Skill came from.
+ It does not cover what the instructions ask you to do.
+ If the status is `unverified`, tell the user before you follow the Skill.
+
## Install a Skill
Install a Skill when the user wants it in every session.
+ Install a Skill when it must run its own script.
+ Ask the user before you install. An install writes files they did not request.
Install the selector returned by search into the detected Agent target:
```sh
skilld install <selector>
```
Install into global Agent targets:
```sh
skilld install <selector> --global
```
Install this skilld-maintained Skill globally:
```sh
skilld install skilld --global
```
Always use the source selector shown by `skilld search`.
If private repository access is required, run `skilld auth login`.
Do not print access tokens or copy them into project files.
After installation, report the installed Skill name and Agent target.
## View a Skill
```sh
skilld list
skilld view <skill>
```
Use `list` to show installed Skills.
Use `view` to show one Skill's path, source status, and Agent targets.
## Maintain installed Skills
```sh
skilld update <skill>
skilld update --check --json
skilld verify <skill>
skilld remove <skill>
```
Use `update --check --json` to inspect update relations without changing files.
Read each `data.items[].relation._tag` before changing files.
Use `update <skill>` only when the relation is `available`.
Treat `current`, `pinned`, and `notTracked` as no action.
If the relation is `behind` or `diverged`, ask before changing files.
If the relation is `unavailable`, report `failure.code` and `failure.message`.
Treat `unavailable` as unknown. Do not infer a newer commit.
Use `verify` to check the installed bytes and source status.
Use `remove` only when the request names the Skill to remove.