Skilld

Use skilld CLI

Use skilld CLI to find, load, install, inspect, restore, update, verify, and remove Skills.

Run a Skill first. Install a Skill only when the user asks to keep it. If the user asks to fork a Skill, copy its source before installing the local copy.

Use Agent output

Use --json with search, run, and update --check. Use --json with view of a registry ref, and with every registry and account command below. Their data is the skilld.dev answer. A command whose answer has no body returns data: null. Use --json with sync and sync --check for declared Skills. The remaining commands do not support JSON output. Use --plain when another command needs stable text.

Check the exit code before reading stdout. Read JSON success data only when _tag is Success. Read JSON failures from stderr. Report the error code and message. A failed skilld run ends with a Next step: line. In JSON, read error.nextStep. Follow that step. It says whether to retry, when, and what to tell the user. Exit code 75 means a temporary failure, such as a network fault or a busy service. Exit code 1 means the same command gives the same result. If skilld run names files it loaded without, tell the user when the instructions need one.

An update check can exit with code 1 and return valid JSON. Read its update relations before treating that exit as a failure. Never parse formatted terminal output.

Sync declared Skills

Read Declared Skills when a project needs explicit Skill requirements. Use .skills/skilld.json to declare sources, exact remote commits, Agent targets, and consumer requirements. Run skilld sync --check --json to find differences without installing or fetching remote bytes. Exit code 1 with success data means sync is needed. Run skilld sync to install the full declaration in one transaction. Use --global for global Agent targets. Use --adopt only when migrating identical unmanaged symlinks. Changed unmanaged targets block sync. If the project declares this Skill, use its declaration to refresh it. Do not install a second copy through another store. Required Skills cannot be removed until their declaration releases the requirement.

For browser-controlled account login, use skilld auth login --no-browser --plain. Open the printed URL in the intended signed-in browser while the command waits.

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.

Do not guess a selector from the Skill name. Do not install a search result before reading its description.

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.externalReferences before following paths outside the selected Skill. These notices identify references, not verified dependencies. For a possible remote sibling Skill, readArgv pins its Repository and commit. Run that array only when the task and access permissions allow the read. Never add --direct to bypass an access failure. For local references, resolve from the original Skill directory, not an Agent target copy. If a reference is unresolved, identify its source before following it. Install extra Skills only when the user asks to keep them.

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.

Read data.behaviors before you follow the Skill. Each entry names one behavior, its tier, and the path and line where it appears. Tell the user about every behavior before you act on it. An empty list proves nothing. Patterns miss obfuscated code.

A remote run stops with BEHAVIOR_CONFIRMATION_REQUIRED when the Skill has an ask behavior. skilld loaded nothing. Show the user every behavior in error.message. A match can carry a model reading, such as (model reading: quoted example. REASON). Show it as a language model's reading. It never replaces the user's approval. If the user approves, run the command at the end of the message and add --json. Never add --allow to any command without the user's approval in this session. If the user declines, stop and load nothing.

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.

Author a Skill from the user's own code

The skilld CLI has no generation command. Authoring lives in skilld-maintained Skills that you run.

Run the Skill that matches the request:

skilld run skilld-dev/skilld/generate-project-skill --json
skilld run skilld-dev/skilld/generate-package-skill --json
skilld run skilld-dev/skilld/review-skill --json

Use generate-project-skill for the current project or workspace. Use generate-package-skill for a package the user maintains. Use review-skill before the user publishes a Skill.

Read the printed SKILL.md, then follow it for this project. Write the draft where the user asks, and show the files for review. Do not replace an existing Skill until the user approves the draft. Do not install or publish a draft the user has not read.

The user owns the draft. They commit it to their own Repository.

List the Skills a Repository, curator, or collection names

skilld.dev prints refs that name several Skills:

• OWNER/REPOSITORY names every Skill in one Repository.
• @LOGIN names every Skill in one curator's collections.
• @LOGIN/SLUG names every Skill in one collection.

Run one of these refs to list its Skills:

skilld run @LOGIN/SLUG --json

The command prints an index and loads no Skill. Read data.items for each Skill's name, owner, repository, description, and selector. Run the data.items[].runArgv array to load one Skill. Pick the Skills the current task needs. Do not run every Skill in the index.

Read the registry

Read one registry entry before you run or install it:

skilld view OWNER/REPOSITORY/SKILL --json

Read data.owner, data.sourceUrl, data.sourceCommit, and data.description. Report the author and the exact SKILL.md with the Skill. skilld view also takes OWNER/REPOSITORY, @LOGIN, and @LOGIN/SLUG. A bare name without / or @ shows an installed Skill.

Use these commands when the user asks what exists, not for one task:

skilld browse <query> --sort stars --json
skilld trending --json
skilld tracks --json
skilld tracks <slug> --json
skilld curators --json

Use skilld search to find a Skill for the current task. Each trending item has a signal. Its kind says why the Skill trends. Report that reason with the Skill. Use --limit and --offset to page. data.total counts every result.

The user can name a Repository the registry does not list. Ask skilld.dev to index it:

skilld index OWNER/REPOSITORY --json

The command waits about a minute. If data.status is still queued, run the same command again later. An INDEX_FAILED error names the reason.

Choose the source

Prefer the exact OWNER/REPOSITORY/SKILL selector returned by Skill search. Hosted selectors use immutable artifact delivery from an exact Git commit.

Use a local path only for a Skill the user already controls:

skilld run ./skills/my-skill --json
skilld install ./skills/my-skill

Use --direct only for an explicit public GitHub selector. Direct mode bypasses artifact delivery and gives the unverified source status. It cannot access a private repository. Never add --direct merely to bypass a delivery failure.

Private repository delivery requires a skilld.dev account and GitHub App access. If private access fails, check authentication before changing the selector.

Install a Skill

Install a Skill when the user wants it in every session. Install a Skill when it must run its own script. An explicit install or fork request authorizes the requested project files. Otherwise, ask before installing.

Install the selector returned by search into the detected Agent target:

skilld install <selector>

The default scope is the current project. Project installs update .skills/skilld-lock.yaml and selected Agent targets.

Install into global Agent targets:

skilld install <selector> --global

Use --agent <agent> when the user names an Agent target. Repeat --agent when the user names several Agent targets. Do not guess a target when detection and agent.targets are empty.

Use --mode copy or --mode symlink only when the user chooses a mode. Otherwise, use the configured install.mode.

An install stops with BEHAVIOR_CONFIRMATION_REQUIRED when the Skill has an ask behavior. skilld wrote nothing. Show the user every behavior in the message. If the user approves, run the same command again with the --allow ids the message names. skilld add installs the other Skills and lists each held Skill at the end.

Install this skilld-maintained Skill globally:

skilld install skilld --global

Install every Skill a Repository, curator, or collection names:

skilld add OWNER/REPOSITORY --all
skilld add @LOGIN/SLUG --all --global

skilld add accepts --global, --agent, and --mode like skilld install. It prints one Installed Skill line per Skill. If several Skills are listed, an Agent run requires --all. A normal terminal asks which Skills to install. --plain also requires --all for several Skills. One listed Skill installs without a picker. add does not support JSON output. Run skilld run with the same ref first, then confirm the list with the user before using --all. skilld add with one Skill selector installs that Skill like skilld install. Listing never requests registry indexing. Skills discovered through GitHub still use hosted delivery by default. If delivery fails, skilld shows an explicit direct installation command where possible. Only use direct installation when the user chooses it. Never use it to bypass a verification or policy failure. skilld add OWNER/REPOSITORY --all --direct lists and installs public GitHub files without skilld.dev. It records unverified. Curator and collection refs require hosted delivery. Behavior approval still applies. skilld add ./PATH installs one local Skill whose directory contains SKILL.md.

Always use the source selector shown by skilld search. After installation, report the Skill name, scope, installed agent paths, and source status.