Building a gem: your own reusable assistant

• 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 not "thorough," it is overhead on every single turn.

You create and manage Gems from the Gem manager in the Gemini app (the "Explore Gems" / "New Gem" area in the sidebar). Workspace admins can also publish shared Gems to a whole organization, which is the difference between a personal habit and a team standard.

Designing the brand voice rewriter

Before touching the UI, decide the three things every Gem needs:

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. Notice it is structured, specific, and shows examples rather than just describing them.

That last block is the part people skip. Edge-case rules (what to do with on-voice text, what to do with fragments) are what 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 PDF, a glossary of approved product names, and a document of 10 to 15 before/after rewrite pairs. The Gem reads these as reference, so when someone pastes a sentence about your "FreightSync" product, it uses the correct capitalization and description.

A few 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 over time 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. Upload your style guide and example-pair files as knowledge.

4. Use the live preview panel on the right to test before saving.

5. Save. It now lives in your sidebar.

The official walkthrough and current UI details are in Google's Gems help documentation, which is worth checking since the layout shifts as the product evolves.

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, adversarial testing then 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, that is a signal you have outgrown the app. The same instruction text becomes a system_instruction in the Gemini API via Google AI Studio, where you can script a test set:

That is the same Gem behavior, now as code you can run in CI. The app Gem and the APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → share the same idea: a system instruction is the spine of both.

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

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

A Gem wins when:

• The behavior repeats. You do this task weekly or daily. Reuse amortizes the setup cost.
• Consistency matters across people. Five marketers should produce the same voice. A shared, admin-published 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. A saved Gem is one click in the sidebar.

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.
• You need it inside a document or inbox. Gems live in the Gemini app. For "rewrite this paragraph right here," Gemini in Google Workspace (the side panel in Docs and Gmail) is the better surface. It sees the document you are in.

That last point is the most useful boundary. A Gem is a reusable *assistant you go to*. Gemini in Workspace is help that *comes to you* inside the file. The Brand Voice Rewriter as a Gem is great for bulk rewriting a batch of pasted drafts. For polishing one line as you write it, the Docs side panel is faster.

When you have outgrown Gems entirely

Gems are deliberately simple: instructions plus knowledge, no custom logic, no external tools. You have outgrown a Gem when you need any of these:

• Programmatic access. Other software calls it. Move to the Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →.
• Live data or tool use. It needs to hit 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.
• Spreadsheet or Workspace automation. A Gem cannot run on a schedule or transform a Sheet. Apps Script with the Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → can.

A Gem is the right tool at exactly one layer: a fixed behavior you trigger by hand. The moment it needs to *act on its own* or *be called by code*, you have crossed into agent and APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → territory, which the rest of this path covers.

Key Takeaways

• Build a Gem when the behavior repeats and consistency matters, especially across a team. For genuinely one-time tasks, a sharp prompt is faster.
• 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). That is what makes 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.
• Know the upgrade path: for in-document help use Gemini in Workspace, for code use the Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, and for tools or live data move to ADK on Vertex AI.