+180 XP

Gemini · Building a gem: your own reusable assistant

A Gem is a saved Gemini configuration: a name, a set of standing instructions, and optionally some reference files. It turns a repeated prompt into a one-click assistant. Instead of pasting the same 300-word "act as our brand editor" preamble every morning, you build it once and open it whenever you need it.

This lesson builds a real one, a "Brand Voice Rewriter" Gem. We will set it up, test it, then look at when a Gem beats a sharp one-off prompt and when it does not.

What a Gem actually is under the hood

A Gem is a persistent system instruction plus optional knowledge, saved in your Gemini app account. When you open a Gem, those instructions apply to every turn in that conversation. The model still runs on the normal Gemini models you have access to, with the full context window and native multimodality. The Gem guarantees the instructions and reference material show up every time without you re-typing them.

Two practical consequences:

  • A Gem is scoped to a behavior, not to a single question. "Rewrite this in our voice" is a behavior. "What's the capital of France" is not.
  • A Gem's instructions are standing context. They eat into the same window your actual task uses, so keep them tight. A bloated 2,000-word instruction set is overhead on every single turn, not thoroughness.

You create and manage Gems from the Gem manager in the Gemini app (the "Explore Gems" / "New Gem" area in the sidebar). You can also share a Gem with colleagues the same way you share a Google Drive file, choosing who can use it and who can edit it. That is the difference between a personal habit and a team standard.

Designing the brand voice rewriter

Before touching the UI, decide three things:

  1. A name and one-line purpose. "Brand Voice Rewriter: turns any draft into our house voice."
  2. The job it does, stated as behavior. What goes in, what comes out, what it should never do.
  3. The knowledge it needs. Your actual style guide, example before/after pairs, banned words.

The most common Gem failure is vague instructions. "Make it sound on-brand" tells the model nothing. You have to encode the brand as rules and examples. The examples matter more than the adjectives.

Writing the instructions

Here is a complete instruction set for the Gem. It is structured and specific, and it shows an example instead of only describing one.

You are the Brand Voice Rewriter for Northwind, a B2B logistics company.

YOUR JOB
Take any draft text the user pastes and rewrite it in Northwind's voice.
Output only the rewritten text, then a one-line note on what you changed.
Never invent facts, prices, dates, or features that were not in the input.

OUR VOICE
- Direct and confident. Lead with the outcome, not the backstory.
- Plain words. Replace "utilize" with "use", "leverage" with "use".
- Short sentences. Max ~20 words. No semicolons.
- Warm but not cute. No exclamation marks, no emoji.

BANNED WORDS: synergy, seamless, world-class, revolutionary, game-changer.

EXAMPLE
Input: "We are excited to leverage our world-class network to seamlessly
deliver your freight in a timely manner!"
Output: "Your freight moves on our network and arrives on schedule."

IF the input is already on-voice, say so and make only minimal edits.
IF the input is ambiguous (e.g. a fragment), ask one clarifying question.

People skip that last block. Edge-case rules (what to do with on-voice text, what to do with fragments) make a Gem reliable across a team instead of just for you on a good day.

Adding knowledge files

Instructions cover the rules. Knowledge files cover the detail you cannot fit inline. Attach your real style guide, a glossary of approved product names, and a document of 10 to 15 before/after rewrite pairs. You can upload files or attach them from Google Drive. Drive files stay linked, so edits to the doc reach the Gem. The Gem reads these as reference, so when someone pastes a sentence about your "FreightSync" product, it uses the correct capitalization and description.

Two attachment habits worth keeping:

  • Prefer clean, structured files (a tidy doc of pairs) over a 90-page brand bible dump. The model grounds better on signal than on volume.
  • Keep an example bank as its own file so you can grow it. Every time the Gem gets a rewrite wrong, add the corrected pair. The Gem gets sharper without you rewriting instructions.

Building it in the Gemini app

The mechanics are quick:

  1. Open Gemini, go to the Gems area, choose New Gem.
  2. Paste the name and the instruction block above.
  3. Add your style guide and example-pair files as knowledge.
  4. Use the preview panel to test before saving.
  5. Save. It now lives in your Gem list, ready to open or share.

The official walkthrough and current UI details are in Google's Gems help documentation. Check it, because the layout shifts as the product evolves.

Create your own custom Gems in the Gemini app

Watch on YouTube

Testing it like an engineer, not a fan

Do not test with the example you already put in the instructions. Test with cases designed to break it:

  • An already-clean sentence (does it leave it mostly alone?).
  • A sentence stuffed with three banned words (does it catch all three?).
  • A one-line fragment (does it ask a clarifying question, or hallucinate context?).
  • A paragraph with a real number in it (does it preserve the number exactly?).

Run these through the preview. When it fails, fix the instruction or add an example pair, then re-test. This loop of adversarial testing and patching is the actual work of building a good Gem. The UI part takes five minutes. The testing makes it trustworthy.

If you want repeatable, automated testing across many inputs, you have outgrown the app. The same instruction text becomes a system_instruction in the Gemini API, with a key from Google AI Studio. Then you can script a test set:

python
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY from env

BRAND_VOICE = open("brand_voice_instructions.txt").read()

drafts = [
    "We leverage our world-class network for seamless delivery!",
    "Shipment 4471 departs Tuesday.",
    "synergy",
]

for draft in drafts:
    resp = client.models.generate_content(
        model="gemini-flash-latest",  # or pin a version from the models page
        config={"system_instruction": BRAND_VOICE},
        contents=draft,
    )
    print(f"IN:  {draft}\nOUT: {resp.text}\n")

For CI, pin a specific model version from the models page so results do not drift when the alias moves. The app Gem and the API share the same idea: a system instruction is the spine of both.

Knowledge check

1. According to the lesson, what fundamentally distinguishes a Gem from a normal one-off prompt?

2. Why does the lesson warn against writing a bloated 2,000-word instruction set for a Gem?

3. The lesson says the most common Gem failure is vague instructions like 'make it sound on-brand.' What is the recommended fix?

MULTIPLE CHOICE

4. Select ALL statements that correctly describe when a Gem is a good fit versus a plain prompt.

Select all the correct answers.

MULTIPLE CHOICE

5. Select ALL of the three core things the lesson says every Gem needs before you touch the UI.

Select all the correct answers.

When a Gem beats a one-off prompt (and when it doesn't)

This judgment call separates people who collect Gems from people who use them.

A Gem wins when:

  • The behavior repeats. You do this task weekly or daily, so reuse pays back the setup cost.
  • Consistency matters across people. Five marketers should produce the same voice. One shared Gem enforces that. Five separately memorized prompts do not.
  • The instructions are long or fiddly. If your prompt has banned words, edge cases, and examples, retyping it is error-prone. A Gem freezes the good version.
  • You want it next to your work. Gems are available in the Gemini app and in the Gemini side panel in Workspace apps like Gmail and Docs, so the Brand Voice Rewriter can sit beside the email you are drafting.

A one-off prompt wins when:

  • The task is genuinely one-time. A Gem you use once is just a slower prompt.
  • Every run needs different instructions. If the "rules" change each time, there is no stable behavior to save.

The side panel matters here. In Docs, Gemini can see the document you are in. For "tighten this paragraph right here" with no house rules, plain Gemini in the side panel is fastest. When house rules matter, open the Gem from that same panel and you get both the document context and your voice rules.

When you have outgrown Gems entirely

Gems are deliberately simple: instructions plus knowledge, no custom code, no connection to your own systems. They can use Gemini's built-in abilities, Google Search included, but you cannot wire in your own tools. You have outgrown a Gem when you need any of these:

  • Programmatic access. Other software calls it. Move to the Gemini API.
  • Your own data or tools. It needs to query your database or call an internal service mid-task. That is an agent, built with the Agent Development Kit (ADK) and deployed on Vertex AI.
  • Scheduled or bulk automation. A Gem runs when a person opens it. To process a Sheet every night, use Apps Script with the Gemini API.
  • Controlled grounding. If you need citations, logged sources, or search grounding you configure yourself, set up grounding with Google Search in the API or AI Studio.

A Gem fits exactly one layer: a fixed behavior you trigger by hand. Once it needs to act on its own or be called by code, you are in agent and API territory, which the rest of this path covers.

Key Takeaways

  • Build a Gem when the behavior repeats and consistency matters, especially across a team. Share it like a Drive file so everyone uses the same version.
  • Encode brand or behavior as rules plus examples, not adjectives. "Make it on-brand" fails. A banned-words list and before/after pairs work.
  • Always include edge-case instructions (already-on-voice text, fragments, preserving numbers). They make a Gem reliable for other people, not just you.
  • Test adversarially before trusting it: clean input, banned-word input, fragments, real numbers. Patch the instructions or example bank, then re-test.
  • Gems work in the Gemini app and the Workspace side panel. For code use the Gemini API, and for your own tools or data move to ADK on Vertex AI.

What to do, from this lesson

These actions are compiled in the role's Playbook.

  • Build a Gem at the third repeat when setup is stable
  • Encode brand behavior as banned-word lists and before/after pairs, not adjectives
See the full action playbook →