skilld

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:

skilld search <query> --json

Read data.items before choosing a Skill. Use each item's selector for a Skill run. 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:

skilld run <selector> --json

The command prints SKILL.md and writes no Skill files. It retains no remote Skill files after the command exits. Read the printed SKILL.md, then follow it for the current task. Prefer skilld run for a one-off task.

Read data.files for each supporting file's path, kind, and size. The initial load prints no supporting file content. Read one only when the instructions name it:

skilld run <selector> --revision <data.revision> --file <path> --json

Run the exact data.files[].readArgv array when possible. It contains the source, exact revision, file path, and --json. 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 skilld wrote no Skill files. Read data.sourceStatus, data.origin, and data.revision. 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:

skilld install <selector>

Install into global Agent targets:

skilld install <selector> --global

Install this skilld-maintained Skill globally:

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

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

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.