Home › How to upload a skill
Uploading a skill takes about two minutes if the file is already correct, and about two hours if it is not — because a wrong file uploads happily and then silently never runs. This page is the upload step in order: where the button is, what to select, what to enable afterwards, and how to confirm it works.
The upload is the easy part. The two things people miss are: the folder name must match the name field in SKILL.md, and a newly uploaded skill usually arrives disabled. Fix both and you are done in two minutes.
Validate first with the validator — it runs in your browser and catches the errors that produce no upload message at all.
| Requirement | Detail |
|---|---|
| A folder on your machine | Named exactly as the name field in your SKILL.md |
| SKILL.md inside it | YAML frontmatter with name and description, then markdown |
| Text-only attachments | PDF, JPG, PNG allowed. .docx, .doc, .xlsx are not |
| No external calls in scripts | Scripts must not fetch external URLs |
| Under the limits | 100 active skills, 100 MB of uploads total |
The full field list is on the format reference page.
Open SKILL.md and read three things:
name field. Lowercase letters, digits, and hyphens. 1 to 64 characters. No leading, trailing, or doubled hyphen.name, character for character, including case.description field. 1 to 1024 characters, stating what it does and when to use it.gemskills-site/
├── SKILL.md ← name: gemskills-site
└── reference.md
# the name field must equal the folder name
---
name: gemskills-site
description: Checks a SKILL.md against the Gemini format rules. Use when the user mentions a skill that will not upload, will not trigger, or has a formatting problem.
---The folder name above is gemskills-site, not Gemskills Site and not gemskills_site. Spaces, underscores, and capitals all break the match, and nothing tells you they did.
Paste the file into the validator and give it the folder name. If it reports a mismatch, fix that before uploading rather than after.
In the Gemini web app, the path is:
Settings, then find the skills section for your account.
Import is what you want for an existing SKILL.md folder.
Pick the folder containing SKILL.md, not the file inside it. This is the second most common mistake.
The skill is registered. Acceptance is not validation — it does not mean it can run.
Interface labels move around. If your menu looks different, the reliable signal is the outcome, not the path: after this step your skill should appear in your list, in a disabled state.
This is the step that makes people think the upload failed. A newly uploaded skill and a skill produced by Google's automatic migration both arrive switched off. Nothing fires until you turn it on, and there is no error to explain the silence.
Open each new skill in your list and switch it to active. Do this one at a time and test before moving to the next, so you know which one is working.
Not "hello". Use a request you would genuinely send, phrased the way you would phrase it.
| Test | What it tells you |
|---|---|
| Ask for the thing directly | Confirms the skill runs at all. If not, it is disabled or the folder name is wrong. |
| Ask for something adjacent | Confirms the description is not too broad. |
| Ask for something unrelated | Confirms it stays quiet. A skill that fires on everything is as broken as one that never fires. |
That third test is the one people skip. A skill with an over-broad description matches unrelated requests, and you stop trusting it without noticing you have lost a tool.
The Gemini App and Workspace have separate skill systems that do not sync. A skill working in one says nothing about the other.
| Surface | Status |
|---|---|
| Gemini App only | Done. You can stop here. |
| Workspace only | Upload through the Workspace surface instead. |
| Both | Upload twice, enable twice, test twice. Expect to maintain two copies. |
This is a frequent source of false conclusions that a correctly built skill is broken. If it works in one surface, the file is fine — the other surface simply does not have it.
| What you see | Cause | Fix |
|---|---|---|
| Upload succeeds, skill never fires | Folder name does not match the name field |
Rename the folder or the field so they match exactly |
| Upload succeeds, skill never fires | Skill is still disabled | Open it and switch it on |
| Upload succeeds, skill never fires | Description too vague to match a request | Rewrite with what it does and when to use it |
| Rejected: unsupported file type | .docx, .doc, or .xlsx attached | Convert to text or PDF first |
| Rejected: external network call | A script inside the skill fetches a URL | Remove the fetch or pass the data in as a file |
| Rejected: invalid name | Uppercase, spaces, underscores, or a bad hyphen | Lowercase letters, digits, hyphens only |
| Uploads but does not appear | Already at 100 active or 100 MB | Remove skills you no longer use |
| Works in Gemini App, missing in Workspace | Two separate systems | Upload to Workspace too |
The first three are the dangerous ones, because they produce no message. The not triggering page is dedicated to diagnosing exactly those.
Folder name equals name field. Skill is enabled. Tested with a real prompt and one unrelated prompt. Those three checks catch nearly every upload that appears to succeed and does nothing.
Three causes, in order of likelihood: the folder name does not match the name field, the skill is disabled, or the description is too vague. Only the first and third are properties of your file; the second is the default state after upload.
No. You select the folder containing SKILL.md. Zipping the folder is a common source of a nested-directory mistake where the file ends up one level too deep and is not found.
Yes, and you should. Skills are your files — edit them in any text editor and re-upload. This is a real advantage over Gems, which have not been editable since October 13, 2026.
Check three things in order: whether it is still enabled, whether you are at 100 active skills, and whether you were in a different surface than you tested in. Only then look at the file.
They are tied to your account and not publicly listed. Anyone with access to your account can use them, so treat commercial or client instructions accordingly. The validator here runs entirely in your browser for the same reason.
The 100 MB total is account-wide across all uploads, not per skill. Reference documents inside a skill count toward it.