Gemini Skills Just Landed in Workspace: Your First SKILL.md, Moving a Gem, and Why a Migrated Gem Isn't a Working Skill

Attributed compile (not original research)

Primary sources: Let skills in Gemini tackle your most repetitive tasks by Deven Tokuno, Senior Product Manager, Gemini App (Google, 2026-09-30); Introducing skills in the Gemini app and Workspace, plus what's next for Gems (Google Workspace Updates, 2026-09-30, with the Workspace rollout starting 2026-10-05); Google's help pages Create & manage skills for Gemini Apps and Write effective skills for Gemini Apps; the open Agent Skills specification

Secondary coverage: Google Gemini Skills Start Rolling Out Today, Replacing Gems by Abhilasha Raut (Affitronix, 2026-10-05); Google starts retiring Gemini Gems in November (On The Wire, 2026-10-03); Google launches Skills in Gemini by Brian Beckmann (2026-10-01)

This post restates Google's announcements and help docs in my own words, with a practical first-skill checklist. I did not create, upload, or migrate a skill in Gemini or Workspace for this article. Feature descriptions, dates, and limits are vendor-reported or attributed to the named source. The SKILL.md and folder examples are adapted patterns based on the spec. The small Python checker was run locally against a sample folder only. It is not a Google tool and was not tested against Gemini's uploader.

---

Google is retiring Gems. Their replacement, skills, started reaching Workspace Rapid Release domains on October 5. Personal accounts in the Gemini app have been getting them gradually since the September 30 announcement.

The headline is convenience: save an instruction set once, then call it with / in any chat. The more interesting part for engineers is the format. Google says skills are "built entirely on the open, Markdown-native SKILL.md standard." That is the same folder-plus-Markdown format used by the Agent Skills spec, which Beckmann notes is also read by Claude, GitHub Copilot, and Google's own Gemini CLI.

So a skill you write for Gemini can be a plain file in a Git repo. It is no longer a setting trapped in one product.

What changed (and when)

Here are the dates from Google's Workspace Updates post and blog:

Date	What happens (vendor-reported)
Sep 30, 2026	Skills announced; rolling out "directly into Gemini chat globally" for personal accounts, 18+
Oct 5 – Oct 12	Skills in Workspace apps, Rapid Release domains
Oct 13 – mid-Nov	Skills in the Gemini app for Workspace domains
Oct 19 – mid-Nov	Skills in Workspace apps, Scheduled Release domains
Nov 17, 2026	Gems move into the Gemini app's Settings panel (still usable)
November 2026	Gem support removal begins for personal accounts
No sooner than Mar 1, 2027	Business/enterprise: Gems stop working; leftovers auto-migrate to draft skills
No sooner than Jun 1, 2027	Education: same, plus Classroom and LTI integrations

If your Gemini looks different from your coworker's, this staggered schedule is probably why. Personal account, Workspace domain, and release channel each land on a different date.

The mental model: skills are loaded lazily

A Gem was a separate assistant with its own chat. A skill is closer to a plugin that the model pulls into the current conversation. Google's help page describes three stages, which line up with the "progressive disclosure" section of the Agent Skills spec:

1. Match. Gemini reads only each skill's name and description to decide whether it is relevant.
2. Load. If it matches, Gemini reads the full instructions.
3. Fetch. Attached files (templates, style guides, data) are opened only when a step needs them.

The practical consequence: your description is your router. Gemini can apply skills automatically, and a vague description means the skill never fires. Google's writing guide says to start with a third-person capability statement, add "Use when…" triggers, and stay under 1,024 characters. The spec sets the same 1,024-character limit.

You can also stack skills. Google's example pairs a writing-style skill with a brand-guidelines skill in one prompt. Because each skill should do one job, this pushes you toward small, composable files rather than one giant system prompt.

Your first SKILL.md (adapted pattern)

Per the spec, a skill is a folder whose name matches the skill's name, with SKILL.md at the root:

draft-weekly-update/
├── SKILL.md
└── references/
    └── tone.md

---
name: draft-weekly-update
description: Drafts a weekly status update from meeting notes and task lists. Use when the user asks for a weekly update, status report, or Friday summary.
metadata:
  author: your-name
  version: "1.0"
---

# Weekly update

1. Read the notes the user provides (or the attached doc).
2. Group items under: Shipped, In progress, Blocked, Next week.
3. Use the tone rules in [references/tone.md](references/tone.md).

## Common mistakes
- Do not invent dates or owners. If one is missing, ask.
- Keep it under 200 words unless the user asks for more.

The "common mistakes" section and the "ask instead of guessing" rule both come straight from Google's best-practices page. They are the cheapest anti-hallucination measures you can add.

Pre-upload check (adapted pattern)

Google's upload rules: a SKILL.md in the root folder, a lowercase-hyphenated name, plain-text files only (no .docx or .xlsx), 100 MB total, and a tip to strip hidden files like .DS_Store and .pyc. Scripts can't reach external websites. One surprise: .env appears on the supported-file list, so nothing stops you from uploading a secret by accident. This checker flags all of that before you click Upload:

# check_skill.py: pre-upload sanity check for a SKILL.md folder
import re, sys
from pathlib import Path

NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")    # lowercase, single hyphens
BLOCKED = {".DS_Store", ".env"}                        # junk + secrets
BINARY_EXT = {".docx", ".doc", ".xlsx", ".pyc"}         # not plain text
MAX_BYTES = 100 * 1024 * 1024                          # Gemini's 100 MB total

def check(folder: Path) -> list[str]:
    errs, skill = [], folder / "SKILL.md"
    if not skill.is_file():
        return ["SKILL.md missing from folder root"]
    m = re.match(r"^---\n(.*?)\n---\n", skill.read_text(), re.S)
    meta = dict(re.findall(r"^(\w[\w-]*):\s*(.+)$", m.group(1), re.M)) if m else {}
    name, desc = meta.get("name", ""), meta.get("description", "")
    if not NAME_RE.fullmatch(name) or len(name) > 64:
        errs.append(f"bad name: {name!r}")
    if name != folder.name:
        errs.append(f"folder {folder.name!r} != name {name!r}")
    if not 0 < len(desc) <= 1024:
        errs.append("description must be 1-1024 chars")
    files = [p for p in folder.rglob("*") if p.is_file()]
    for p in files:
        if p.name in BLOCKED or p.suffix in BINARY_EXT:
            errs.append(f"remove before upload: {p.relative_to(folder)}")
    if sum(p.stat().st_size for p in files) > MAX_BYTES:
        errs.append("total size over 100 MB")
    return errs

if __name__ == "__main__":
    problems = check(Path(sys.argv[1]))
    print("\n".join(problems) or "OK")
    sys.exit(1 if problems else 0)

Run python check_skill.py draft-weekly-update. On my sample folder it printed OK. On a copy renamed to Weekly_Update with a stray .DS_Store, it flagged the folder/name mismatch and the hidden file. It is a lint, not a full YAML parser. For spec-level validation, the Agent Skills project points to skills-ref validate ./my-skill.

The trap: a migrated Gem is a draft, not a working skill

Google says remaining Gems will be auto-migrated, and the Workspace post calls the result draft skills. Read the fine print before you count on that:

• Some Gem tools don't carry over yet. As relayed by On The Wire, Google's help page says most default Gem tools don't work with skills for now, naming Create video, Create music, Canvas, Deep Research, and Guided Learning.
• Skills don't sync. Google says skills in the Gemini app and skills in Workspace apps are separate. You have to create each one twice.
• Sharing and Drive files are "coming weeks." Both are promised but not shipped yet, per Google's blog.
• Labs Gems and Opal don't migrate. Google's footnote says Gems by Google Labs will not become skills, and Opal shuts down in November.
• Editing files means re-uploading. To change a skill's files, you upload the whole folder again (Skill actions → Replace skill).

Checklist for moving a Gem early

1. Open each Gem and download its Knowledge files into a folder named exactly like the future skill (lowercase, hyphens).
2. Create the skill in Settings → Skills → Create manually, then paste in the name, description, and instructions. Use the web app; Google lists manual creation on mobile as a known bug.
3. Rewrite the description as a router: what it does, then "Use when…".
4. Download the new skill's .zip, move SKILL.md into your folder, run the checker, then use Replace skill to upload the folder.
5. Commit the folder to a repo. That copy is your source of truth for Workspace, for Gemini CLI, and for anything else that reads SKILL.md.
6. Test any Gem that relied on Deep Research or Canvas before November, not after.

Why this matters

Gems were product configuration. Skills are files. Once Google, Anthropic, and GitHub all read the same SKILL.md layout, your prompt engineering stops belonging to one vendor's settings page and becomes something you can version, review, and lint. The work that pays off is the description, because it decides when a skill fires, and the "ask instead of guessing" rules, because they decide whether the output can be trusted.

---

Byline: YongBo Yu — Toronto AI engineer (agents, LLM workflows). GitHub: YongBoYu1.