devkit-skill-authoring
skills/devkit-skill-authoring/
references/troubleshooting.md
When it is rejected
Errors are prefixed with the slug, as my-skill: <message>.
The folder
| Message | Cause | Fix |
|---|---|---|
no SKILL.md in <path> - is this a skill folder? | Pointed at the wrong directory, or the file is named skill.md | The file is SKILL.md, at the folder root, case-sensitive |
no SKILL.md at the folder root | It exists, but nested - docs/SKILL.md | Move it to the root |
no files | Empty folder | — |
too many files (max 64) | A skill is documentation, not a package | Cut, or split into two skills |
<path> is N bytes (max 524288) | One file over 512 KB | Usually an image or a dump that should not ship |
skill is N bytes (max 2097152) | Whole folder over 2 MB | Same |
duplicate file: <path> | Two entries resolve to one path | — |
Paths
The install writes into ~/.claude/skills/<slug>/, so these are a security boundary and are not negotiable.
| Message | Cause |
|---|---|
absolute file path: /x | Leading / |
backslash in file path: a\b | Windows separator; use / |
path traversal or empty segment: ../x | .., ., or an empty segment |
NUL in file path | — |
path too long to package (>100 bytes): <path> | <slug>/<path> exceeds ustar's 100-byte name field. Shorten the path, or the slug |
bad file path "…" | Leading or trailing whitespace, or empty |
The slug
| Message | Cause |
|---|---|
slug must be lowercase-hyphenated, 3-64 characters | Uppercase, underscore, a leading or trailing hyphen, or too short or long. The folder name is the slug |
"cli" is reserved by the registry - the install URL is already taken | all and cli are served by the registry itself |
Frontmatter
| Message | Fix |
|---|---|
missing frontmatter: file must start with a --- line | Nothing before the opening ---, not even a blank line |
unterminated frontmatter: no closing --- line | Add the second --- |
line N: indentation is not supported | A nested map or a - item list. Use an inline list: tags: [a, b] |
line N: "key" needs an inline value (multi-line scalars are not supported) | An empty value, or | / >. Everything goes on one line |
line N: duplicate key "x" | Delete one |
line N: empty entry at position K of the list | Trailing or doubled comma |
line N: quoted entries are not supported in a list | Remove the quotes; a quoted comma would be split in half |
line N: unterminated list - expected a closing ] | — |
missing required frontmatter key "x" | name, description, version, author, license, status, tags are all required |
"x" must be a string | A list or boolean where a scalar belongs |
Field values
| Message | Fix |
|---|---|
frontmatter "name" is "a" but the folder is "b" - they must match | Rename one. The folder is the slug |
"description" must be 10-200 characters (got N) | And on one line |
"version" must be SemVer (got "x") | 1.0.0, not 1.0 or v1.0.0 |
"author" may use letters, digits, _ . - and be at most 40 characters | No spaces, no @, no email |
license "x" is not a recognised SPDX identifier | MIT, Apache-2.0, BSD-3-Clause, … Not a URL, not free text |
"status" must be one of stable, beta, deprecated | — |
"tags" must be a non-empty list, e.g. [ai, claude] | Inline list, not a block sequence |
"tags" may have at most 8 entries | — |
tag "X" must be lowercase alphanumeric, . or - | Lowercase it; no spaces or underscores |
"created" must be YYYY-MM-DD (got "x") | — |
SKILL.md has no body below the frontmatter | The body is the skill |
Publishing
| Symptom | Cause | Fix |
|---|---|---|
409 | That version already exists. Versions are immutable | Bump version: and publish again |
401 / 403, exit 77 | Missing, wrong, or unscoped token | devkit whoami. Publishing needs the publish scope |
| Published to the wrong registry | The default was not what you assumed | devkit whoami first; pin the repo with .devkitrc.json |
this is not the latest version | You published an older line | Expected; latest is unchanged |
no registry configured | Never logged in, or the name does not exist | devkit login <url> --as <name> |
Installing
| Symptom | Cause | |
|---|---|---|
sent no X-Devkit-Digest header … refusing to install unverified content | Not talking to a devkit registry - a proxy or an error page in front of it | |
digest mismatch for <skill> | The archive does not hash to what the server claimed. Something rewrote it in transit; do not install | |
| Ambiguous bare name | Two accounts own that slug | Use @owner/slug |
A skill missing from devkit update | Its .devkit.json marker is unreadable | The CLI lists these separately rather than dropping them; reinstall it |
It validates but Claude never loads it
Not a validation problem. The description is the only thing matched against, so this is nearly always a description that says what the skill is rather than when to use it. See writing-well.md.