Syncing into Agents

Introduction

Agents read skills from a folder on the machine they run on. gatana skills install writes the skills you can read into those folders and adds a hook that refreshes them at the start of every session. After that, the machine follows Gatana: a skill edited in Gatana is on the machine at the next session start, and a skill removed from Gatana is removed from the folder.

Installing

curl -fsSL https://github.com/gatana-ai/gatana/releases/latest/download/install.sh | sh
gatana config login # opens the browser, where you choose your organization
gatana skills install # install all skills and the hook
gatana skills install my-collection # install all skills in collection and the hook
gatana skills install skill-123 # install specific skill and the hook

The name can be a skill or a collection. When a skill and a collection share a name, add --collection or --skill to say which one you mean.

Where the skills go

Without a target, the install writes into the folders of every agent:

Add a preset name or a directory to install into one place instead:

gatana skills install claude                     # only the Claude Code folder
gatana skills install my-collection ./team-skills # a directory of your own

Each skill becomes a folder named after it, holding a SKILL.md with the name and description in the frontmatter. Gatana adds its own metadata to the frontmatter (the organization, the skill id, the collection and the last update), which is how later runs know what came from Gatana.

What a folder follows

Gatana remembers what each folder follows: everything you can read, one collection, or one skill. Later syncs refresh that selection. Skills removed from Gatana, or that you lost access to, are removed from the folder. Skills that did not come from Gatana are left alone, as are Gatana skills you edited locally: a sync reports them and keeps your version until you push it or run with --force.

A folder that was never installed into follows everything you can read, so a sync alone is enough on a new machine.

Keeping them up to date

The install adds a hook on the SessionStart event of the agent. It runs gatana skills sync --quiet, which refreshes what each folder follows before the agent starts work. You can run gatana skills sync yourself at any time, with the same targets and options as the install.

gatana skills hook {agent} prints the block the install merges into the agent's configuration. Add --install to write it instead of printing it. gatana skills remove-hooks removes it again, from one agent or from all.

$ gatana skills hook claude
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "gatana skills sync --quiet"
          }
        ]
      }
    ]
  }
}

Options

gatana skills ls lists the skills you can read, with --query, --collection and --collections to narrow it.