This page is the complete, precise reference for the skillz command surface, JSON output, exit codes, environment variables, file locations, and supported agents. It is meant for lookup, not for learning. To learn by doing, start at Installing Skills and Authoring Skills.

Every command prints the same per-command help at the terminal. Run dnx skillz <command> --help to see the synopsis, arguments, and options for that command.

dnx skillz add --help

Description:
  Add a skill from a source

Usage:
  skillz add [<source>] [options]

Arguments:
  <source>  Source to fetch skills from (e.g., owner/repo, URL, local path)

Options:
  -g, --global    Install globally
  -a, --agent     Target agent(s)
  -s, --skill     Skill name filter(s)
  -y, --yes       Skip prompts (non-interactive)
  --all           Install all skills to all agents
  --copy          Copy instead of symlinking
  --full-depth    Scan nested directories for skills
  -l, --list      List available skills without installing
  -?, -h, --help  Show help and usage information

The binary on your PATH is skillz. Install it with dotnet tool install -g skillz, or run it without installing via dnx skillz <command> (requires the .NET 10 SDK or later). Both forms accept the same commands, arguments, and options documented below.

Commands

skillz has five commands: add, remove, list, update, and init. Each command's options are independent. There are no shared global options beyond --help and --version (see Global flags).

skillz add <source>

Add skills from a source. Skills are discovered at the source, then materialized into a canonical store and linked into each target agent's skills directory.

dnx skillz add <source> [options]

Arguments

Options

The default install mode is symlink: skillz materializes each skill once into a canonical store and creates a relative symlink from each agent directory back to it. Pass --copy to copy instead. When every selected agent shares one skills directory, copy is used automatically.

For sources, scopes, and install mechanics, see Installing Skills. For agent targeting, see Supported agents.

skillz remove [skills...]

Remove installed skills. With no skill names and an interactive terminal, skillz prompts you to select which skills to remove.

dnx skillz remove [skills...] [options]

Arguments

Options

In interactive mode, skillz shows a multiselect prompt followed by a confirmation prompt. The confirmation defaults to no. Declining the confirmation prints Removal cancelled and exits with code 130 (see Exit codes).

$ dnx skillz remove alpha
# exit 130

Removal cancelled

skillz list

List installed skills. With no options, lists the current project's skills.

dnx skillz list [options]

This command takes no positional arguments.

Options

JSON output is enabled when either --json is present or --format json is set (case-insensitive). Enabling JSON suppresses the banner and writes the array to stdout.

skillz update [skills...]

Check for available updates and print the exact command to apply each one.

dnx skillz update [skills...] [options]

Aliases: upgrade and check. dnx skillz upgrade and dnx skillz check are identical to dnx skillz update.

Arguments

Options

With neither -g nor -p, an interactive terminal prompts you to choose Project, Global, or Both. Passing both flags, or running non-interactively, checks both scopes.

$ dnx skillz update -g

Checking for skill updates...

Checking global skill 1/1: my-skill
Found 1 global update(s)

Update available: my-skill
  Run: skillz add owner/repo/skills/my-skill -g -y

Updates available for 1 skill(s); no updates were applied.

skillz init [name]

Scaffold a new skill directory containing a SKILL.md template. This command has no options.

dnx skillz init [name]

Arguments

If the target SKILL.md already exists, skillz does not overwrite it. It prints Skill already exists at <path> and exits 0.

$ dnx skillz init my-skill

Initialized skill: my-skill

Created:
  my-skill/SKILL.md

Next steps:
  1. Edit my-skill/SKILL.md to define your skill instructions
  2. Update the name and description in the frontmatter

Publishing:
  GitHub: Push to a repo, then skillz add <owner>/<repo>
  URL:    Host the file, then skillz add https://example.com/my-skill/SKILL.md

See Authoring Skills for the SKILL.md format and publishing workflow.

Global flags

These are provided on the root command and on every subcommand.

Running skillz with no arguments shows the banner and exits 0. Running dnx skillz --help shows curated top-level help. A bare -- token is removed before parsing, so dnx skillz add --agent codex -- owner/repo parses the same as without it.

JSON output

dnx skillz list --json (equivalently dnx skillz list --format json) prints a JSON array to stdout. Each element describes one installed skill.

dnx skillz list --json

[
  {
    "name": "alpha",
    "path": "/home/you/project/.agents/skills/alpha",
    "scope": "project",
    "agents": ["Claude Code", "Windsurf"]
  }
]

The array is written to stdout, so you can pipe it to a tool such as jq. Banner and progress output are suppressed in JSON mode.

Exit codes

skillz uses exactly three exit codes.

Environment variables

XDG_CONFIG_HOME (default ~/.config) and XDG_STATE_HOME (default ~/.local/state) affect where skillz keeps its own configuration and logs, and where several agents resolve their global directories.

For private repositories, skillz shells out to git and uses your existing git credentials (SSH agent, credential helper, gh auth). See Troubleshooting for authentication and rate-limit guidance.

File locations

skillz writes a lock file per scope and materializes skills into a canonical store. Project scope is the current working directory; global scope is your home directory.

Non-universal agents receive a symlink from their own directory (for example .claude/skills/<name>) back into the canonical store. Universal agents use the canonical store directly. See Supported agents for per-agent directories.

Supported agents

skillz supports more than 50 agents (55 in total). It detects which agents are installed on your machine by probing each agent's configuration directory, and it detects which agent it is running inside by reading environment variables that agent hosts set. When run inside a detected agent, add runs non-interactively and targets that agent plus the universal agents.

Agent identifiers are case-sensitive (the identifier is github-copilot, not copilot). The --agent option is repeatable and accepts multiple values per token. --agent * targets all agents. "Universal" agents share the .agents/skills store, so installing a skill for one universal agent makes it visible to all of them.

In the table below, project directories are relative to the working directory and global directories are absolute (~ is your home directory, <config> is $XDG_CONFIG_HOME or ~/.config). Agents marked "universal" use the shared .agents/skills store at project scope.

Passing an unknown identifier exits 1 and prints the full list of valid identifiers:

$ dnx skillz add ./local-path --yes --agent bogus
# exit 1

Invalid agents: bogus

See also

• Installing Skills: sources, scopes, and the install workflow in depth.
• Authoring Skills: the SKILL.md format, dnx skillz init, and publishing.
• Troubleshooting: authentication, rate limits, timeouts, and common errors.