Home › Skill name rules
The name field has the shortest specification of anything in SKILL.md, and it causes the most damage. A name that breaks the character rules is rejected at upload, so you find out immediately. A name that does not match its folder uploads cleanly and never runs, so you find out weeks later. Both are on this page.
The four rules:
Rule 4 is the one that fails without a message. Check it before you upload.
Only three character classes are permitted:
| Allowed | Examples |
|---|---|
| Lowercase letters a–z | report · convert · skill |
| Digits 0–9 | pdf2csv · v2 · ocr3 |
| Hyphens | pdf-extractor · status-update |
Everything else is rejected. The characters people reach for by mistake:
| Not allowed | What people write instead |
|---|---|
| Uppercase letters | PDFExtractor |
| Underscores | pdf_extractor |
| Spaces | pdf extractor |
| Slashes | tools/pdf |
| Dots | pdf.extractor |
| Non-Latin characters | 文档转换 |
| Emoji | pdf-📄 |
Non-Latin names are a genuine limitation. A Chinese or Japanese skill name cannot be written in its own script. Use a Latin transliteration or an English slug — wendang-zhuanhuan rather than 文档转换 — and put the native name in the body or the description instead, where it can still be read.
1 to 64 characters. One character is legal but useless. Sixty-four is the ceiling and nothing good uses it.
| Length | Verdict |
|---|---|
| 1 | Legal. Never useful. |
| 2 to 20 | Too short to be descriptive. Collides with other skills. |
| 20 to 45 | The useful range. Two or three words joined by hyphens. |
| 45 to 64 | Acceptable, usually carrying detail that belongs in the description. |
| 65 or more | Rejected |
Rejected — comprehensive-multi-format-document-processing-and-extraction-helper is 76 characters. The rejected length is only the first problem; the name also says nothing the description could not say better.
Accepted — document-extractor is 19 characters, and the specifics live in the description where they can be written in full sentences.
Three hyphen mistakes, each producing an upload rejection:
Leading hyphen — -pdf. Rejected.
Trailing hyphen — pdf-. Rejected. This one happens constantly when a name is built by stripping a suffix off a longer string.
Doubled hyphen — pdf--extractor. Rejected. This is what a replaced separator leaves behind when one becomes two.
Accepted — pdf-extractor. Single hyphens, none at either end.
A quick mental check: the string should read the same forwards and backwards with no awkward joins. If any position has two hyphens in a row, one of them belongs somewhere else.
This is the rule that does not produce an error. The upload succeeds. The skill appears in your list. It never runs.
Your folder on disk and the name field in the frontmatter must be identical, character for character.
gemskills-site/← folder name on disk
├── SKILL.md
└── reference.md
---
name: gemskills-site ← must be identical
description: ...
---| Folder | Name field | Difference |
|---|---|---|
pdf-extractor | pdf_extractor | Hyphen versus underscore |
pdf-extractor | PDF-Extractor | Uppercase |
pdf extractor | pdf-extractor | Space in the folder |
pdf-extractor | pdf-extractor-2 | Suffix added later |
pdf-extractor | extractor | Substring of the folder name |
pdf-extractor | pdf-extractor-old | Trailing suffix on the field |
pdf-extractor | pdf--extractor | Doubled hyphen |
pdf-extractor- | pdf-extractor | Trailing hyphen on the folder |
v2-pdf-extractor | pdf-extractor | Version prefix added to the folder only |
There is no warning for any of these. Nothing in the interface reports a mismatch, the file stays in your list indefinitely, and the only symptom is that the skill never responds to anything. The not triggering page has the full diagnosis; paste the file into the validator with your folder name to catch it in seconds.
Either, as long as both end up the same. Pick based on what is harder to change later:
| Situation | Change |
|---|---|
| Folder is awkward, name is fine | Rename the folder |
| Folder is referenced in other files or scripts | Change the name field to match the folder |
| Already uploaded with a mismatch | Rename the folder, re-upload, allow a few minutes, re-enable, retest |
Renaming the folder is almost always simpler. Nothing else in a skill folder references its own name, apart from the frontmatter.
Names are the identity of the skill. Once you have several, clarity beats brevity.
| Weak | Why | Stronger |
|---|---|---|
helper | Tells you nothing at a glance | table-extractor |
tool | Same | json-formatter |
converter | Converts what to what? | csv-to-json |
v2 | Version numbers belong in your file history | status-update-writer |
new-skill-2 | Describes nothing | Name it for what it does |
Pattern that works: noun-noun or verb-noun, in the 20 to 40 character range, describing the output rather than the mechanism.
Accepted — csv-to-json · pdf-table-extractor · weekly-status-writer · diff-reviewer · invoice-date-normalizer
Three questions, in order. If any answer is no, stop there.
Lowercase letters, digits, single hyphens only? No spaces, no underscores, no capitals.
Between 1 and 64 characters? No hyphen at the start or the end, none doubled up?
Read the folder name off your disk and compare it to the field, one character at a time.
Do step 3 by eye, not by memory. The mismatch is invisible precisely because you believe the two are the same. Read one, read the other, compare. Ten seconds here saves the two hours of rewriting a skill that was never going to work.
All three checks run automatically in the validator. Paste the file in and give it the folder name; it reports the character rules, the length, and the match separately.
Yes, anywhere. pdf2csv and ocr3 are both valid. Only the character class is restricted, not the digits.
Yes. Only lowercase letters are permitted, so PDF-Extractor is invalid even though it looks harmless. This is the most common rejection, usually because the name was copied from a title.
Make the names more specific. Colliding names are legal but confusing in a list, and they make it harder to tell which skill triggered. Include the output format or the domain in the name.
It has to be in Latin lowercase letters, digits, and hyphens. A fully non-Latin name is not valid. Use an English slug and put the native language name in the description.
The folder that contains SKILL.md. Not the file, and not the parent directory. If you upload the SKILL.md from inside the folder rather than the folder itself, the match may not be established as you expect.
Two possibilities. The skill is still disabled after upload, which is the default state for both manual uploads and migrated skills. Or the description is too vague to match anything even though the name is correct. See the diagnosis and description examples.
Yes, because it is your file. Rename the folder, update the frontmatter, re-upload, and enable it again. There is no rush — skills are not editable on any deadline, unlike Gems which stopped being editable on October 13, 2026.