How to Share Skills Across Claude Code, Codex and Other Agents in a Team

Short answer: A skill is a folder with a SKILL.md file. Claude Code reads it from ~/.claude/skills. Codex, Cursor and other agents read ~/.agents/skills. For a team, keep the skills in one place and install them into those folders on every machine. A git repository works for a small team. A registry adds access rules, a sync hook and an audit trail.

What a skill is

A skill tells an agent how a job is done in your organization. Examples: how to cut a release, what a pull request review must cover, where to look first when an error appears. A skill is one Markdown document in a folder of its own name.

---
name: release-checklist
description: Use when asked to release a backend service or cut a new version
---

1. Start from a clean checkout of `main` with a green test run.
2. Bump the version in `package.json` and tag the commit `backend/vX.Y.Z`.
3. Push the tag. The pipeline builds the image and deploys to staging.
4. Watch the staging dashboard for ten minutes before you promote.

The frontmatter contains the name and the description. The body contains the instructions. Write the description for an agent that decides whether the skill applies. Say when to use it, not what it contains. The format is open and documented at agentskills.io.

Where each agent reads skills

Agent	Folder
Claude Code	~/.claude/skills
Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Amp	~/.agents/skills
Hermes	~/.hermes/skills

A skill that is in the correct folder is available to the agent. Nothing else is necessary. The sharing problem is thus a file distribution problem: one set of folders, current on every machine, readable by the correct people.

Option 1: a git repository

1. Create a repository with one folder for each skill.
2. Each person clones it.
3. Each person links or copies the folders into ~/.claude/skills and ~/.agents/skills.
4. Each person pulls when a skill changes.

This works for a small team with one set of skills. Four limits appear as the team grows:

• Everyone with the repository sees every skill. There is no access rule for each team.
• An update reaches a machine only when the person pulls.
• A copy that one person edits locally drifts from the repository.
• Git records who changed a file. It does not record which agents read the skill.

Option 2: a skills registry in the gateway

Gatana stores skills under the same access rules as the rest of the gateway and installs them where the agents read.

Create the skills

Create skills in the dashboard under Skills, with a Write tab and a Preview tab. Or push folders that you already have:

npm install -g gatana
gatana config login your-organization
gatana skills push ~/.claude/skills/release-checklist     # one skill
gatana skills push ./team-skills -c release-engineering   # a folder of skills, into a collection

Install them on each machine

gatana skills install                      # every skill the person can read, plus the hook
gatana skills install release-engineering  # one collection

Install writes each skill into ~/.claude/skills and ~/.agents/skills. Pass hermes as a target for Hermes, or any other path. The CLI tracks the folders that it writes. It does not touch skills that you keep there yourself. It does not overwrite a local edit that has not been pushed. When a skill is deleted in Gatana, the next install removes it from the machine. Keep it with --no-prune.

Keep them current

Install adds a hook on the SessionStart event of Claude Code and Codex. The hook runs gatana skills sync --quiet before the first prompt. Every session starts with the current skills. The hook prints nothing, because Claude Code and Codex add hook output to the context of the model.

gatana skills hook claude        # prints the hook block to merge by hand
gatana skills install --no-hooks # install without the hook
gatana skills remove-hooks       # take the hook out again

Push changes back

Edit an installed SKILL.md, or write a new folder, and push:

gatana skills push    # everything that changed on this machine

The next session on every other machine gets the change. If someone else changed the same skill in the meantime, push reports a conflict and leaves the server copy alone. Install first to see their version, or push with --force.

Group and share

A collection is a named group of skills, for example release-engineering or support-runbooks. A machine that installs a collection follows it. New skills in the collection arrive on the next session. A collection is shared as one unit.

A skill is Organization-wide by default. Set it to Private and share it with people or teams. Each share is Can read or Can maintain. Install writes only the skills that the signed-in person can read. The instructions are stored encrypted at rest with the key of the organization. Every create, edit, share and delete is in the audit log.

Option 3: skills over MCP

Some agents have no skills folder. They reach the same skills through the built-in Skills MCP server:

Tool	What it does
skills_list_skills	Lists readable skills, grouped by collection. Takes a query or a collection
skills_get_skill	Returns one skill as a SKILL.md document
skills_create_skill	Saves a new skill, optionally private to teams or in a collection
skills_update_skill	Changes description or instructions, or renames

Add one line to the CLAUDE.md of the project or equivalent: “At the start of a task, call skills_list_skills and follow any skill that applies.”

Write skills that agents pick

• Put the trigger in the description: “Use when asked to release a backend service.”
• Keep the body to numbered steps. Name the files, commands and dashboards.
• Keep one job for each skill. Split a long procedure into two skills.
• Test the skill in Claude Code and in Codex before you share it. The agents read the same file, but they phrase their decisions differently.

The skills page in the documentation has the full reference.