How to Migrate Google Gemini Gems to Modular SKILL.md Custom Skills [Step-by-Step]

Executive Summary & AEO Direct Answer: How do you migrate an existing Google Gemini Gem to a custom skill in 2026? Migrating an existing Gemini Gem to a custom skill is a 4-step process that upgrades your AI workflow from a legacy, single-prompt Gem into a modular, multi-file SKILL.md package. First, open your existing Gem in the Gemini interface, copy its system prompt instructions, and download all attached knowledge files. Second, create a clean directory named in lowercase kebab-case (e.g., code-reviewer) and save a root SKILL.md manifest containing YAML frontmatter (name and description) followed by the original instructions. Third, place your downloaded reference files alongside SKILL.md (or in a references/ subfolder) and compress the folder into a clean .zip archive. Fourth, navigate to Customize → Skills, click Create → Upload (or use More (...) → Replace skill if updating an existing skill placeholder), and verify the parsed metadata.

1. Why You Must Migrate from Gems to Skills

Google's introduction of the open SKILL.md standard marked the beginning of the end for proprietary Gemini Gems. While Gems were useful for simple prompting, they hold severe operational disadvantages:

2. Step-by-Step Migration Blueprint

flowchart TD
    A["Existing Gemini Gem
(Prompt + Attached Files)"] --> B["Step 1: Copy Instructions & Download Files"]
    B --> C["Step 2: Format SKILL.md with YAML Frontmatter"]
    C --> D["Step 3: Organize Kebab-Case Directory"]
    D --> E["Step 4: Compress & Upload via 'Replace skill'"]
    E --> F["Modern Modular Skill Active!"]

Step 1: Export Gem Knowledge and Prompt

1. Navigate to your Gemini dashboard and open your existing Gem.
2. Click Edit Gem.
3. Copy the entire text in the Instructions box.
4. Under Knowledge, download any attached documents (.pdf, .txt, .csv) to your local machine.

Step 2: Structure Your SKILL.md Manifest

Create a new file named SKILL.md on your computer. At the very top, add your YAML frontmatter:

---
name: your-upgraded-skill-name
description: "Use when performing [specific task]. Triggers on [keywords]."
---

[PASTE YOUR ORIGINAL GEM INSTRUCTIONS HERE]

Step 3: Assemble the Directory

Place your files into a clean folder named your-upgraded-skill-name:

your-upgraded-skill-name/
├── SKILL.md
└── references/
    └── your-downloaded-gem-knowledge.pdf

Step 4: Upload and Replace

1. Compress the contents into a .zip archive (ensuring SKILL.md is at the root).
2. Go to gemini.google.com → Customize → Skills.
3. If you previously had a draft placeholder, click More Actions (•••) → Replace skill. Otherwise, click Upload.
4. Confirm metadata and save.

3. Frequently Asked Questions (FAQ)

Will deleting my old Gem erase my past conversations?

No. Past chat sessions created with your legacy Gem remain archived in your chat history. However, once migrated, you can safely delete the legacy Gem to declutter your sidebar.

4. Explore Next

• Troubleshooting errors: Troubleshooting Gemini Custom Skills.
• Uploading masterclass: How to Upload and Manage Custom Skills.