This page maps the errors and surprises you hit when running skills to their cause and fix. Each section starts with the exact message the CLI prints (where one exists), explains why it happens, and gives you a copy-pasteable way out.

If you are new to skills, start with Getting Started. For the full command and flag surface, see the Reference. For what each agent identifier means and where skills land, see Installing Skills.

"No valid skills found. Skills require a SKILL.md with name and description."

You ran dnx skills add <source> and the CLI reached the source but found nothing to install:

$ dnx skills add ./my-skills --yes --agent claude-code
# exit 1

Source: /home/you/my-skills
No valid skills found. Skills require a SKILL.md with name and description.

Cause: a skill is a directory that contains a SKILL.md file with both name and description in its YAML frontmatter. The CLI silently skips any folder that is missing the file, missing either field, or whose name/description collapses to empty. By default, it only looks at the source root (or the subpath you pointed it at), so a SKILL.md buried in a nested directory is not discovered.

To see exactly what the CLI finds without installing anything, run --list:

dnx skills add owner/repo --list

Source: https://github.com/owner/repo.git
Found 2 skill(s)

Available Skills
  alpha
    the alpha skill
  beta
    the beta skill

Use --skill <name> to install specific skills

If --list reports Found 0 skill(s), work through these in order:

--full-depth widens discovery so the CLI scans nested directories for skills. It does not change how much of the repository is cloned. Clones are always shallow regardless of this flag.

"Invalid agents: <name>"

You passed an --agent value that the CLI does not recognize:

$ dnx skills add ./my-skills --yes --agent bogus
# exit 1

Source: /home/you/my-skills
Found 1 skill(s)

┌─Invalid agents───────────────────────────────────────────────────────────────┐
│ Invalid agents: bogus                                                        │
│                                                                              │
│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │
│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │
│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │
│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │
│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │
│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │
│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │
│ warp, windsurf, zencoder                                                     │
└──────────────────────────────────────────────────────────────────────────────┘

Cause: the value is misspelled or uses the wrong case. Agent identifiers are case-sensitive, and several differ from the product's marketing name. The most common mistakes:

The error panel always prints every valid identifier, so copy the correct one from the list. The same Invalid agents: <name> message appears (without the panel) from dnx skills list and dnx skills remove. For the full table of identifiers and where each one installs skills, see Installing Skills and the Reference.

Cloning a private repository fails with "Authentication failed"

dnx skills add reports an authentication error and stops before installing.

Cause: the CLI never prompts for credentials. It shells out to your own git, which uses your existing setup (SSH agent keys, a git credential helper, gh auth, or ~/.netrc). When git cannot authenticate, the CLI surfaces the failure instead of hanging. Any credentials embedded in a URL are redacted from the output, so secrets never appear in errors or in the lock file.

To fix it, confirm your machine can reach the repository, then retry the same dnx skills add command.

For SSH sources ([email protected]:owner/repo.git):

ssh -T [email protected]
# Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.

For HTTPS sources, authenticate with the GitHub CLI or configure a git credential helper. These are one-time setup commands whose output varies by environment:

gh auth login                         # uses the gh credential helper
# or
git config --global credential.helper store

After gh auth login completes, it confirms the authenticated account.

Once git clone <repo> succeeds on its own, dnx skills add <repo> will succeed too.

The clone times out

A large repository can exceed the default clone budget and cause the CLI to abort the fetch.

Cause: the CLI caps each clone at 5 minutes (300000 ms). The clone is always shallow (latest commit only), but a very large repository or a slow connection can still run past the limit.

To raise the timeout, set SKILLS_CLONE_TIMEOUT_MS in milliseconds before running the command:

SKILLS_CLONE_TIMEOUT_MS=600000 dnx skills add owner/big-repo --agent claude-code   # 10 minutes

With the longer budget the clone finishes and the install completes with the usual Installed 1 skill(s) panel.

Alternatively, clone the repository yourself and point skills at the local copy. This skips the network step entirely:

git clone --depth 1 https://github.com/owner/big-repo.git
dnx skills add ./big-repo --agent claude-code

Pointing skills at the local clone installs the skill without touching the network and prints the same Installed 1 skill(s) panel.

A skill does not appear for one agent

dnx skills add reports success, the skill shows up in dnx skills list, but one of your agents does not see it.

Cause: agents that keep skills in their own directory (for example .claude/skills for Claude Code or .windsurf/skills for Windsurf) only get a link when that agent's directory already exists in your project. The CLI will not create a config directory for an agent you do not use. When the directory is missing, it skips the link for that agent but still materializes the skill in the shared .agents/skills store, so the skill is installed; it is only the per-agent link that is missing.

Pick whichever fix matches your intent:

After the directory exists, re-running the install links the skill into .claude/skills. The Installation Summary then lists Symlinked: Claude Code instead of skipping that agent.

Agents that share the universal .agents/skills store (Cursor, Codex, GitHub Copilot, Gemini CLI, and others) always see the skill because their directory is the canonical store.

Symlinks are not created (Windows)

On Windows, skills copies skills into agent directories instead of linking them.

Cause: creating a symlink on Windows requires either an elevated process or Developer Mode. When the CLI cannot create the link, it automatically falls back to copying the skill so the install still succeeds. The skill works either way; the only difference is that copies do not share a single editable source of truth the way symlinks do.

To get symlinks instead of copies, choose one:

• Enable Developer Mode (Settings, "For developers", "Developer Mode"), then re-run the command.
• Run your terminal elevated ("Run as administrator") and re-run the command.

If you prefer copies and want the CLI to copy without attempting a symlink first, pass --copy explicitly:

dnx skills add owner/repo --agent claude-code --copy

The output shows the skill was copied rather than linked: the Installation Summary lists Copied: Claude Code, and the skill is written directly into .claude/skills.

"skills update" cannot check a skill or hits a rate limit

dnx skills update reports that one or more skills could not be checked:

$ dnx skills update -g

Checking for skill updates...


1 skill(s) cannot be checked automatically:
  * legacy (Private or deleted repo)
    To update: skills add https://github.com/owner/repo -g -y

Cause: update checks for newer versions by calling the GitHub API, and unauthenticated calls are rate-limited. It also cannot diff every kind of source. Skills installed from a local path, a generic git URL, a well-known HTTP source, or a private or deleted repository have no checkable remote tree, so they are reported as "cannot be checked automatically" with a manual refresh hint.

To raise the rate limit, give skills a GitHub token and re-run. The CLI reads GITHUB_TOKEN, then GH_TOKEN, then falls back to gh auth token:

export GITHUB_TOKEN=ghp_...   # or: gh auth login
dnx skills update

With the token in place the rate limit clears and the check completes:

Checking for skill updates...

All skills are up to date.

For sources that can never be checked automatically, re-install with dnx skills add to refresh them. The update output prints the exact command to run for each one:

dnx skills add owner/repo/skills/my-skill -y

The refresh re-installs the skill from its source and prints the usual Installed 1 skill(s) panel.

dnx skills update only checks for and reports available updates. It never applies them. Whatever it finds, it prints the precise skills add ... command for you to run (prefix it with dnx when you use dnx). The aliases dnx skills upgrade and dnx skills check behave identically. See the Reference.

"... is newer than this skills supports"

A command refuses to write to a lock file and reports that the on-disk version is newer than this version of skills supports.

Cause: the lock file (skills-lock.json in your project, or the global .skill-lock.json) was written by a newer version of skills than the one you are running. The CLI reads newer lock files but refuses to modify them, so it does not corrupt state written by a version it does not understand.

To fix it, update skills to the latest release:

dotnet tool update -g skills

A successful upgrade reports the version change:

Tool 'skills' was successfully updated from version 0.1.0 to version 0.3.0.

If you no longer need the existing lock state and want to start fresh, delete the lock file and re-install your skills. The project lock lives at skills-lock.json in your working directory; the global lock lives at ~/.local/share/skills/.skill-lock.json (or under $XDG_DATA_HOME/skills if that variable is set).

[!WARNING] Deleting a lock file discards update tracking. The CLI uses the lock file to know what is installed and to check for updates. After deleting it, run dnx skills add again for each skill so the CLI can rebuild the lock. The installed skill folders themselves are not removed by deleting the lock.

Bundled binary assets are missing from a skill

A skill installs, but a binary file it ships (an image, a model, a compiled tool) is a tiny placeholder or absent.

Cause: the CLI disables Git LFS while cloning, so only LFS pointer files are fetched, not the large binaries they track. This keeps clones fast and shallow, but it means LFS-tracked assets do not arrive with the skill.

To fix it, change how the skill stores its assets:

• Store skill assets without Git LFS so they travel as ordinary files in the repository.
• Vendor the assets directly into the skill folder (commit the real files alongside SKILL.md).

If you author the skill yourself, see Authoring Skills for how to lay out bundled resources.

"Failed to remove" a skill

dnx skills remove reports that it could not remove a skill:

$ dnx skills remove "My Skill" --yes
# exit 1

Failed to remove 1 skill(s)
  My Skill: ...

Cause: the CLI removes a skill by the sanitized, lowercase, hyphenated name it uses on disk (for example my-skill). A folder created outside skills whose name does not match that sanitized form is not something the CLI will delete automatically, so it reports the failure rather than falsely claiming success. The CLI also refuses to delete a real non-empty directory or file it did not create, which protects your own data.

To fix it, delete the folder yourself from the skills directory. For a project install that is ./.agents/skills/<folder>; for the corresponding agent directory it is, for example, ./.claude/skills/<folder>. For a global install the canonical store is ~/.agents/skills/<folder>.

rm -rf "./.agents/skills/My Skill"

Run dnx skills list afterward to confirm the skill is gone. The listing no longer shows the removed skill:

$ dnx skills list

No project skills found.
Try listing global skills with -g

Next steps

• Reference: every command, flag, exit code, and environment variable in one place.
• Installing Skills: sources, scopes, agent targeting, and the symlink versus copy model.
• Still stuck? Ask in the ChilliCream Slack.