Home › Skill not triggering
A skill that will not trigger almost always has one cause: the name in the frontmatter does not match the name of the folder it sits in. The upload succeeds, the skill shows in your list, and nothing fires — with no warning anywhere. This page shows how to confirm that in about two minutes and how to fix it.
Do this first: look at the folder the skill lives in and compare its name, character for character, with the name field in its SKILL.md. They must be identical. A difference of one character, one hyphen, or one letter case is enough to stop the skill from ever running.
Paste your file into the validator with your folder name and it will tell you directly whether they match.
Because nothing is reported, people often assume the skill was not saved. That leads to uploading it again, renaming it, and eventually rebuilding it from scratch, none of which helps.
| What you see | What it means |
|---|---|
| Upload completes with no error | The file was accepted. Acceptance is not validation. |
| The skill appears in your list | It was registered. Appearing in the list does not mean it can run. |
| No output when you send a matching request | This is the symptom. It is not caused by the wording of your request. |
| No error, warning, or log entry anywhere | Expected. A name mismatch is not treated as an error condition. |
| The skill runs after you fix the folder name | Confirms the cause. Nothing else was wrong. |
The important consequence: because there is no feedback, a skill with this problem can sit in your list for months. You will assume the skill is the problem, when the problem is a folder you never checked.
The name field is how a skill is addressed. The loader reads the frontmatter to learn which skill is being invoked, then looks for the content inside the directory that carries that name. If the directory is called pdf-tools and the frontmatter says name: pdftool, the loader looks for pdftool and finds nothing that matches its expectation.
Nothing about this is recoverable at runtime. The skill is registered and listed, but it can never be selected.
Read the actual directory name from your file manager, not from your own memory of what you called it.
Open SKILL.md and read the name: line. Copy it rather than retyping it.
Look for spaces, underscores, capital letters, trailing hyphens, and doubled hyphens.
Rename the folder or change the field. Renaming the folder is usually safer because the name field has format rules.
Every one of these is enough on its own. None of them produces an error.
| Folder | name field | Difference |
|---|---|---|
pdf-tools | pdf-tools | Matches |
pdf-tools | pdf_tools | Hyphen versus underscore |
pdf-tools | PDF-Tools | Letter case |
pdf-tools | pdf tools | Space in the field |
pdf-tools | pdf-tools- | Trailing hyphen |
pdf-tools | pdf--tools | Doubled hyphen |
PDF-tools | pdf-tools | Capital folder name |
pdf_tools | pdf-tools | Underscore folder |
pdf tools | pdf-tools | Space in folder |
Note the two rows marked as matching. A folder named pdf-tools with a field of pdf-tools is correct even if the name is not very descriptive — descriptiveness is not part of the rule, agreement is.
Separately from matching the folder, the name itself must satisfy the format. These cause rejection at upload, which is at least visible.
| Rule | Detail |
|---|---|
| Length | 1 to 64 characters |
| Characters | Lowercase letters, digits, and hyphens only. No spaces, no underscores, no capitals. |
| Hyphens | Cannot start with one, end with one, or appear twice in a row |
| Must equal | The parent folder name, exactly |
So PDF-Processing, -pdf, pdf-, pdf--tools, and pdf_tools are all invalid regardless of the folder. The format reference documents every field.
If the folder name matches, these are the remaining candidates.
Selection is driven by the description. It needs both what the skill does and when it applies. A description like "Helps with PDFs" gives the loader nothing to match against. Write it as what plus when:
description: Extracts text and tables from PDF files.
Use when the user mentions a PDF, a scanned document,
or needs text pulled out of a file.This is the most common cause after the folder mismatch, and unlike the folder problem it is not always silent — the skill simply never gets selected. The validator warns when a description lacks a trigger condition.
Anything that came through the automatic migration from Gems arrives as a disabled draft. It appears in your list and does nothing until you enable it. This looks identical to a broken skill.
Gemini App skills and Workspace skills are separate systems. A skill uploaded to the App is not available in Workspace, and the reverse is also true. The same skill must be uploaded twice. This is not documented prominently and produces a convincing false impression that the skill is broken.
Up to 100 skills can be active at once. If you are at the limit, newly uploaded skills may not become active. Check how many are currently enabled rather than assuming this particular skill is the problem.
The cause behind most failures. Confirm this before anything else.
1 to 64 characters, lowercase, digits and hyphens, no leading, trailing, or doubled hyphen.
Without a trigger condition the loader has nothing to match.
Migrated skills start disabled. Check this before assuming the file is wrong.
App and Workspace are separate. Upload to both if you use both.
100 active skills maximum.
Checking one file by hand takes a minute. If you have several, the validator does the folder comparison for you: paste the file, type the folder name, and it reports whether they match along with every other rule the file breaks.
There is also a deliberately broken example on that page — a file with capitals, an underscore, an external network call, a binary attachment, and a folder mismatch. Loading it shows exactly what each problem looks like in the output.
Almost always because the name field does not match its folder name. The upload registers the skill but it cannot be selected, and nothing is reported. Compare the two strings character by character.
No. This is the reason the problem is so often missed. The upload succeeds, the entry appears in the list, and there is no error, warning, or log message. If the names differ you get no signal at all.
Rename the folder. The name field has format restrictions — lowercase, digits and hyphens only, no leading, trailing, or doubled hyphen — while folder names on most systems are unrestricted. Changing the folder is less likely to introduce a new problem.
Only if the name field differs in case. A folder called PDF-tools with a field of pdf-tools is a mismatch. Capital letters inside the name field itself are invalid and will be rejected at upload.
Work through the remaining causes in order: description quality, whether the skill is enabled, whether you are in the same surface you uploaded to, and whether you are at the 100 active skill limit. The validator covers the format and description issues in one pass.
Everything that came through the automatic migration from Gems arrives as a disabled draft. It must be enabled individually. This is easy to miss because the skill is listed and looks normal.
No. They are separate systems and do not sync. The same skill must be uploaded to both if you use both surfaces. This is the reason behind a convincing false impression that a correctly built skill is broken.
State what the skill does and when to use it, in the third person. "Extracts text and tables from PDF files. Use when the user mentions a PDF, a scanned document, or needs text pulled out of a file." A description like "Helps with PDFs" gives the loader nothing to match against.
Up to 100 active at once, with up to 100 MB of uploads in total. At the limit, newly uploaded skills may not become active. Both limits are on the format reference page.
Yes. Scripts inside a skill must not fetch external URLs, and binary formats such as .docx, .doc, and .xlsx are not supported as attachments. Both are caught by the validator. Unlike a name mismatch, these produce an upload error rather than silence.
Renaming the folder takes under a minute. Allow a few minutes for the change to take effect, then test with a request that should match the description. The backup checklist is worth reading first if you are about to rebuild anything from scratch.