How to Share Gemini Skills with Your Team: Build a Team Registry with Workspace Skills

Introduction

A skill that only one person can use is a personal shortcut. A skill that the whole team can use, in the same version, is a team standard. Google’s October 8, 2026 announcement of the Gemini agent for work describes that second model: teams publish custom skills to a shared company registry so best practices spread across the organization. Developer teams do not have to wait for a managed registry product. Gemini CLI already treats workspace skills as team skills shared through version control, so a Git repo plus the Agent Skills folder layout gives you a working team registry today. This tutorial builds one: a changelog-writer skill, published to a shared repo, discovered automatically by teammates, governed by code review, and rolled back with a normal git revert.

Quick answer

Put the skill in your repo under .agents/skills//, commit it, and have teammates pull the repo. Gemini CLI discovers workspace skills automatically, so the shared folder is your team registry.

Evidence: what Google has actually announced and shipped

Two layers matter here, and confusing them is the most common mistake in team rollouts. The first is the product announcement. At its Gemini at Work event on October 8, 2026, Google announced Gemini as a single universal agent for work, and described skills as reusable sets of instructions, knowledge, or workflows stored as modular prompts, with a global library, a shared company registry for team-published skills, and personal skills for individuals. Google CEO Thomas Kurian summarized the philosophy in one line: “You give it objectives, not instructions.

The second layer is what is documented and usable today. The Gemini CLI Agent Skills documentation states that workspace skills live in .gemini/skills/ or the .agents/skills/ alias, and adds the sentence that makes this tutorial possible: “Workspace skills are shared with your team via version control.” Discovery runs from built-in skills, to extension skills, to user skills, to workspace skills at the highest precedence, with the .agents/skills/ alias winning within a tier. The Agent Skills open standard defines a skill as a self-contained directory built around a SKILL.md file, which is why the same folder works across tools that adopt the standard.

Discovery is cheap by design: at session start, Gemini CLI loads only each skill’s name and description, and the full instructions load only when the skill activates, a pattern the docs call progressive disclosure. A registry with dozens of skills therefore costs each session roughly a paragraph of metadata per skill. The Gems retirement schedule is the other forcing function: Gems go away for personal accounts in November 2026, for Workspace business accounts in March 2027, and for education accounts in June 2027, so teams still carrying shared Gems should rebuild the ones that matter now. Our guide to migrating Gemini Gems to Skills before the November 2026 deadline covers that migration, and this tutorial covers the sharing step after it.

One caveat before the steps. The company-wide registry in the October 2026 announcement and the Git-based workspace registry in the CLI docs are not the same surface. This tutorial builds the Git-based registry, which is documented, testable, and under your control. Treat the managed registry as the future home for non-developer teams, and check your admin console for its availability rather than assuming it is live in your domain.

Prerequisites

• A shared Git repository that all teammates already clone, with push access for the author and review access for at least one teammate.
• Gemini CLI installed and authenticated on the author’s machine and on at least one teammate’s machine for verification.
• Git 2.30 or later.
• One repeatable team workflow worth encoding. This tutorial uses changelog writing: fixed input (merged pull request titles), fixed output format (Keep a Changelog sections), and a clear failure mode (invented version numbers).
• A naming decision made before you start: team skills use a team- prefix, for example team-changelog-writer, so a team skill can never silently shadow a personal skill.

Step-by-step guide

Step 1: Create the skill folder in the shared repo

Pull the latest main branch and create the skill directory with the standard layout: a SKILL.md file plus optional scripts/ and references/ subdirectories. Use the .agents/skills/ path, not the legacy .gemini/skills/ path, because the alias is the interoperable location other tools adopting the standard also read, and it wins precedence within the workspace tier.

cd ~/work/team-platform
git pull origin main
mkdir -p .agents/skills/team-changelog-writer/references

Do not add .agents/ to the repo’s .gitignore: a gitignore template that excludes agent folders silently keeps the skill off every teammate’s machine. Check before you commit:

git check-ignore -v .agents/skills/team-changelog-writer/ || echo "not ignored, safe to commit"

If it prints a gitignore rule, remove that rule for the skills path before continuing.

Step 2: Write a SKILL.md that a stranger could run

Create .agents/skills/team-changelog-writer/SKILL.md. The frontmatter carries the name and description, and the description is the most important field: it is what Gemini CLI reads at session start to decide whether the skill matches a task, so write what the skill does and when to use it, in the third person, and keep it specific. A vague description activates the skill at the wrong time or never at all.

---
name: team-changelog-writer
description: Drafts Keep a Changelog entries from merged pull request titles for the team-platform repo. Use when a release is being prepared or a teammate asks what changed in a release.
---

# Team Changelog Writer

## When to use this skill

Use this skill only when drafting changelog entries for a team-platform
release, never for marketing copy or release announcements.

## Procedure

1. Ask the user for the release version and date, or read them from
   the release branch name.
2. Collect the merged pull request titles for the release range.
3. Group entries under Added, Changed, Fixed, and Removed, following the
   Keep a Changelog format in references/keep-a-changelog-format.md.
4. List every title once, under exactly one section. Never invent a
   version number, a date, or a feature that is not in the input.

## Output format

Return a Markdown section headed with the version and date, followed by
one bullet per change:

## [1.4.0] - 2026-10-26
### Added
- Search filters on the orders page.

## Guardrails

- If a title is ambiguous, put it under Changed with a note saying it
  needs human review, rather than guessing its section.
- Never publish the changelog. Draft it and stop, so a human reviews
  every entry before release.

Keep the body short and procedural. The skill encodes the team’s judgment: ambiguous entries default to Changed with a review note, and the agent drafts but never publishes. Those two rules are why the skill is worth sharing.

Step 3: Validate the skill locally before anyone else sees it

A skill with broken frontmatter or an empty description fails silently: it never activates, and teammates conclude the registry does not work. Validate before committing:

import re, sys

text = open(sys.argv[1]).read()
m = re.match(r"---\n(.*?)\n---\n", text, re.S)
assert m, "missing YAML frontmatter block"
front = m.group(1)
name = re.search(r"^name: (.+)$", front, re.M).group(1).strip()
desc = re.search(r"^description: (.+)$", front, re.M).group(1).strip()
assert re.fullmatch(r"[a-z0-9-]+", name), f"bad skill name: {name}"
assert 10 <= len(desc) <= 1024, f"description length out of range: {len(desc)}"
print(f"OK: name={name}, description_chars={len(desc)}")

python3 /tmp/validate_skill.py .agents/skills/team-changelog-writer/SKILL.md

Expected output is a single line starting with OK:, naming the skill and reporting its description length. If the script fails on the name pattern, rename the folder and the frontmatter together: a folder name that differs from the frontmatter name is a second silent failure mode. Our guide to writing n8n agent skills with SKILL.md files covers the naming and frontmatter rules in depth for a second tool.

Step 4: Publish the skill through a pull request, not a direct push

Commit the skill on a branch and open a pull request, with the skill owner as reviewer. The description should state what the skill does, what it must never do, and one example input with expected output.

git checkout -b skill/team-changelog-writer
git add .agents/skills/team-changelog-writer/
git commit -m "Add team-changelog-writer skill for release notes"
git push origin skill/team-changelog-writer

Add a CODEOWNERS entry so future changes get reviewed:

.agents/skills/ @team-platform-leads

Merge only after the reviewer checks three things: the description matches the right tasks and no others, the guardrails forbid the known failure mode, and the example output contains nothing invented. From the merge onward, main is the registry, and its history is the audit trail of who changed the team’s standard and when.

Step 5: Verify discovery on a teammate’s machine

The author verifying their own machine proves nothing, because it may carry a local copy. Verification must happen on a teammate’s checkout:

cd ~/work/team-platform
git pull origin main
gemini

Inside the interactive session, run:

/skills list

The output should include team-changelog-writer with its description. If it is missing, the teammate is likely outside the repo root, where workspace discovery does not apply, or the checkout predates the merge. A stale list after a fresh pull is fixed with /skills reload.

Teammates can also install a skill from another repo without cloning the whole project:

gemini skills install https://github.com/your-org/team-platform.git --scope workspace --path .agents/skills/team-changelog-writer

The --scope workspace flag installs it for the current project only, and --path points at the skill inside a larger repo. Use --consent only in automation: the consent prompt exists because installing a skill grants it directory access.

Step 6: Govern versions, changes, and retirement

A registry without governance becomes a junk drawer within a month. Adopt four rules, written in the repo’s contributing guide. First, version skills with the repo: a breaking change ships in a pull request titled as breaking, naming who must re-test. Second, every skill change carries a one-line entry in a CHANGELOG.md inside the skill folder. Third, review skill changes like code: the reviewer runs the skill once on a real input before approving. Fourth, retire deliberately: delete the folder in a pull request, announce the replacement, and tell teammates to run /skills disable <name> on any copies installed elsewhere.

For teams that also run n8n, the same governance applies to workflow skills; see the complete n8n guide for scaling team automation beyond single skills.

Step 7: Add the managed-registry track for non-developer teammates

The CLI registry covers developers. For teammates in the Gemini app or Workspace, track the managed surfaces separately. Google’s October 2026 announcement places team-published skills in a shared company registry for the Gemini agent for work, and Workspace sharing is administered through the admin console. Two rules keep this track honest. First, never promise that a CLI skill will appear in a teammate’s Gemini app or Workspace: as of October 2026, skills do not sync between the two. Second, when the managed registry reaches your domain, publish the same content there under the same team- name, and record both locations in the repo’s skills README.

Troubleshooting

The skill does not appear in /skills list

The cause is almost always location. Confirm the teammate is inside the repo checkout, that the SKILL.md file exists on disk, and that the folder is not gitignored, then run /skills reload. If it still does not appear, check for a same-name personal skill in ~/.agents/skills/: the workspace skill shadows it rather than merging with it.

The skill activates for the wrong tasks

This is a description problem. A description that says “helps with releases” matches every release-related prompt. Rewrite it to name the exact trigger, the repo, and the output, then test with two prompts: one that should trigger it and one similar prompt that should not.

Teammates see different skill behavior

Teammates are on different versions: the skill has no version number of its own, so “the latest” means whatever main contained when you last pulled. Ask the teammate to run git log -1 -- .agents/skills/team-changelog-writer/ and compare the hash with main. If they differ, the fix is a pull, not a reinstall.

Installing a skill from a Git repo fails or installs the wrong folder

Two flags cause most failures. Without --path, the install looks at the repo root and fails when the skill lives in a subdirectory. Without --scope workspace, the install lands in the user tier, outside workspace precedence. Reinstall with both flags explicit, and uninstall a misplaced copy with gemini skills uninstall <name> --scope user.

A merged skill change breaks everyone’s workflow

Disable first, fix second. Any teammate can run /skills disable <name> immediately, which stops the broken version while the owner prepares a fix. Then revert the breaking commit on main, or merge a forward fix, and announce the recovery with the commit hash. Do not edit the skill directly on main to “fix it fast”.

FAQ

Is a shared folder really a registry, or do I need a separate registry product?

For developer teams, the shared folder plus version control is the registry: it provides publishing, versioning, rollback, and access control.

Can I share a skill with teammates who do not use the command line?

Not through the CLI path, which requires a repo checkout. Non-developer teammates use the Gemini app or Workspace surfaces, which do not sync, so each surface needs its own copy.

What happens when two skills have the same name?

Workspace skills take precedence over user skills, and within a tier the .agents/skills/ alias wins. Use unique team- prefixed names to avoid silent shadowing.

How do I roll back a bad skill version?

Revert the commit, push the revert, and tell teammates to pull and run /skills reload. A broken skill can also be disabled immediately with /skills disable <name>.

Who is allowed to change a team skill?

Whoever can merge to the skills path. Add a CODEOWNERS entry for .agents/skills/ so changes require owner review.

Do teammates need to install anything extra to receive a shared skill?

No. Teammates need only the repo checkout and Gemini CLI; workspace skills are discovered automatically.

Conclusion

A team registry for Gemini skills does not require a new product. It requires a folder in the repo everyone already uses, a skill written tightly enough that a stranger could run it, a pull request review that treats the skill like code, and a teammate’s machine as the verification step. Build the changelog skill this week, verify it on one teammate’s checkout, and add the next skill the same way. For the personal side of the same migration, revisit migrating Gemini Gems to Skills before the November 2026 deadline to make sure nothing your team relies on is left behind in Gems.

Frequently asked questions