Fundamentals

Introduction

Teams build up knowledge about how work is done: how to deploy a service, how to review a pull request, how to investigate an error. Today that knowledge is written down for AI agents as skills, and each agent reads them from a folder on the developer's machine. The folders drift apart, a new team member starts with none, and nobody can say which version is in use. Gatana stores the skills of your organization in one place, writes them into the folders your agents read, and keeps those folders in sync.

Quick Start

1. Create your skills in Gatana, or push the ones you already have.
2. On each machine that needs them: gatana skills install.
3. They are kept up to date automatically.

For the team view, including where Claude Code, Codex and the other agents read skills and how a git repository compares, see the guide How to share skills across Claude Code, Codex and other agents.

Definitions

• Skill: a Markdown document that tells an agent how a job is done in your organization. It has a name, a one-line description of when to use it, and the instructions.
• SKILL.md: the file format agents read. A folder named after the skill, holding a SKILL.md with the name and description in the frontmatter and the instructions as the body. Gatana uses the same format, so a skill travels between the two unchanged.
• Collection: a named group of skills. It is installed and shared as one unit.
• Skills folder: the directory an agent reads skills from, such as ~/.claude/skills for Claude Code or ~/.agents/skills for Codex, Cursor and others.
• Hook: a command an agent runs at the start of a session. Gatana installs one that refreshes the skills folders.
• Share: a grant that lets a person or a team read or maintain a private skill or collection.

What is a skill in Gatana?

A skill in Gatana is the source of truth for one SKILL.md. Agents never read it from Gatana directly in the normal case: the CLI installs a copy into each skills folder, and the session-start hook refreshes the copy before the agent starts work. An agent that has no skills folder reads the same skill over MCP, through the built-in Skills server.

The body is stored encrypted. The name and description are stored in plain text, so lists are answered without opening any skill.

Why use skills in Gatana?

• One copy. A skill is written once and every machine and agent gets the same version. An edit reaches everyone at the next session start.
• Every agent. Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Copilot, Amp and Hermes read from their own folders. Gatana writes to all of them.
• Access control. A skill is readable by the whole organization, or private and shared with chosen people and teams. Agents acting for a person read what that person can read.
• Two directions. Skills can be written in Gatana, or edited locally and pushed back. An agent can save a skill it has just worked out with the MCP tools.
• No repository to maintain. No clone, no symlinks, no pull before each session.

What your team experiences

Consider a release checklist that one developer has written as a skill.

Your team does not use Gatana

1. The skill lives in ~/.claude/skills/release-checklist on one machine.
2. The developer pastes it in chat, or commits it to a repository, and asks the others to copy it into their own folders.
3. Each colleague copies it to the folder of each agent they use.
4. The developer improves the checklist. The copies do not change.
5. A new team member joins and starts with an empty skills folder.

Each machine ends up with its own version, and no one knows which one an agent followed.

Your team uses Gatana

1. The developer runs gatana skills push. The skill is now in Gatana, readable by the organization.
2. Each colleague runs gatana skills install once. The skill lands in every agent folder on their machine, and a hook keeps it there.
3. The developer improves the checklist in Gatana, or edits the local copy and pushes again. Every colleague has the new version at their next session start.

A new team member runs gatana skills install and has every skill they are allowed to read.

Overview of the parts

Skill

Collections

A collection is a named group of skills. It follows the same name rule as a skill, so a collection name is a valid folder name wherever a skill name is. You can install a whole collection with the CLI, and share it as one unit. Deleting a collection does not delete the skills: they move to the root level.

Permissions

You set the base level of access of a skill or a collection:

A private skill or collection can be shared with individual accounts or teams. Each share has a level:

A skill in a collection is readable by everyone who can read the collection, in addition to its own shares. Organization owners can maintain every skill.

Installed folders

gatana skills install writes the skills into the folder of each agent on a machine and adds a hook that refreshes them at every session start. See Syncing into Agents.

The Skills server

Agents that cannot read a folder reach the same skills over MCP, through the built-in Skills server. See MCP Tooling.